[API Proposal]: Expose a high level authentication API

[wfurt]

Background and motivation

runtime already have very similar implementation - used primarily by SocketsHttphandler and partially by SMTP.
Kestrel currently use this internal API via Reflection (#29270). Additionally, we would like to have similar authentication in Android handler that lives outside of runtime repo.

Tha main goal is to expose existing functionality via public API so other components can leverage it as well.

API Proposal

namespace System.Net.Security
{
 public class NegotiateAuthenticationClientOptions
 {
 // Specifies the GSSAPI authentication package used for the authentication.
 // Common values are Negotiate, NTLM or Kerberos. Default value is Negotiate.
 public string Package { get; set; }

 // The NetworkCredential that is used to establish the identity of the client.
 // Default value is CrendentialCache.DefaultCredential.
 public NetworkCredential Credential { get; set; }

 // The Service Principal Name (SPN) that uniquely identifies the server to authenticate.
 public string? TargetName { get; set; }

 // The ChannelBinding that is used for extended protection.
 public ChannelBinding? Binding { get; set; }

 // Indicates the requires level of protection of the authentication exchange
 // and any further data exchange.
 // Valid values: None, Sign, EncryptAndSign
 // Default value: None
 System.Net.Security.ProtectionLevel RequiredProtectionLevel { get; set; }
 }

 public class NegotiateAuthenticationServerOptions
 {
 // Specifies the GSSAPI authentication package used for the authentication.
 // Common values are Negotiate, NTLM or Kerberos. Default value is Negotiate.
 public string Package { get; set; }

 // The NetworkCredential that is used to establish the identity of the client.
 // Default value is CrendentialCache.DefaultCredential.
 // Note: I'm not quite sure of the meaning of this on the server side but
 // it exists on GSSAPI side.
 public NetworkCredential Credential { get; set; }

 // The ChannelBinding that is used for extended protection.
 public ChannelBinding? Binding { get; set; }

 // Indicates the requires level of protection of the authentication exchange
 // and any further data exchange.
 // Valid values: None, Sign, EncryptAndSign
 // Default value: None
 System.Net.Security.ProtectionLevel RequiredProtectionLevel { get; set; }
 }

 public class NegotiateAuthentication : IDisposable
 {
 // Create client-side authentication
 public NegotiateAuthentication(NegotiateAuthenticationClientOptions clientOptions);

 // Create server-side authentication
 public NegotiateAuthentication(NegotiateAuthenticationServerOptions serverOptions);

 // Indicates whether the initial authentication finished.
 // NOTE: Original it was named IsCompleted in the proposal but I renamed
 // it to match the property on NegotiateStream.
 public bool IsAuthenticated { get; set; }

 // Indicates negotiated protection level (can be higher than the required one).
 // Returns None if authentication was not finished yet.
 public System.Net.Security.ProtectionLevel ProtectionLevel { get; set; }

 // Indicates whether signing was negotiated.
 // Returns false if authentication was not finished yet.
 public bool IsSigned { get; set; }

 // Indicates whether signing was negotiated.
 // Returns false if authentication was not finished yet.
 public bool IsEncrypted { get; set; }

 // Indicates whether the client and server are mutually authenticated.
 // Returns false if authentication was not finished yet.
 public bool IsMutuallyAuthenticated { get; set; }

 // Indicates whether this is server-side authentication context.
 // Returns value based on the constructor used, provided for parity with
 // NegoatiateStream.
 public bool IsServer { get; set; }

 // The GSSAPI package name that was used for the authentiation. Initially it's
 // the name specified in the options in constructor. After successful authentication
 // it should return the actual mechanism used. For example, if Negotiate is
 // specified as the requested GSSAPI package this may return NTLM or Kerberos once
 // authentication exchange is complete (eg. IsAuthenticated == true).
 //
 // NOTE: This is partly duplicate with RemoteIdentity so it may not be necessary
 // on the public API.
 public string Package { get; }

 // For server context it returns the SPN target name of the client after successful
 // authentication. For client context it returns the target name specified in the
 // constructor options.
 public string? TargetName { get; }

 // Gets information about the identity of the remote party.
 //
 // When accessed by the client, this property returns a GenericIdentity containing
 // the Service Principal Name (SPN) of the server and the authentication protocol used.
 //
 // Throws InvalidOperationException if authentication was not finished yet
 // (IsAuthenticated == false) for server-side.
 public System.Security.Principal.IIdentity RemoteIdentity { get };

 public byte[] GetOutgoingBlob(ReadOnlySpan<byte> incomingBlob, out NegotiateAuthenticationStatusCode statusCode);

 // Base64 version of GetOutgoingBlob
 public string GetOutgoingBlob(string incomingBlob, out NegotiateAuthenticationStatusCode statusCode);

 // TODO (APIs not necessary for HTTP authentication but necessary for high-level protocols
 // like SASL and NegotiateStream):
 // Wrap, Unwrap as replacement for Encrypt, Decrypt, MakeSignature and VerifySignature
 // GetMIC and VerifyMIC if we find a use for that
 }

 // NOTE: Mirrors SecurityStatusPalErrorCode at the moment but it should mostly map to GSSAPI error
 // codes.
 public enum NegotiateAuthenticationStatusCode
 {
 NotSet = 0,
 OK,
 ContinueNeeded,
 CompleteNeeded,
 CompleteAndContinue,
 ContextExpired,
 CredentialsNeeded,
 Renegotiate,
 TryAgain,

 // Errors
 OutOfMemory,
 InvalidHandle,
 Unsupported,
 TargetUnknown,
 InternalError,
 PackageNotFound,
 NotOwner,
 CannotInstall,
 InvalidToken,
 CannotPack,
 QopNotSupported,
 NoImpersonation,
 LogonDenied,
 UnknownCredentials,
 NoCredentials,
 MessageAltered,
 OutOfSequence,
 NoAuthenticatingAuthority,
 IncompleteMessage,
 IncompleteCredentials,
 BufferNotEnough,
 WrongPrincipal,
 TimeSkew,
 UntrustedRoot,
 IllegalMessage,
 CertUnknown,
 CertExpired,
 DecryptFailure,
 AlgorithmMismatch,
 SecurityQosFailed,
 SmartcardLogonRequired,
 UnsupportedPreauth,
 BadBinding,
 DowngradeDetected,
 ApplicationProtocolMismatch,
 NoRenegotiation
 }
}

API Usage

var auth = new NegotiateAuthentication(new NegotiateAuthenticationClientOptions("NTLM", testCredential "HTTP/foo"));
NegotiateAuthenticationStatusCode statusCode;

byte[]? negotiateBlob = ntAuth.GetOutgoingBlob(ReadOnlySpan<byte>.Empty, out NegotiateAuthenticationStatusCode statusCode);
sendBlob(negotiateBlob);
do
{
 buffer = receiveBlob();
 byte[]? negotiateBlob = ntAuth.GetOutgoingBlob(buffer, out statusCode);
} while (statusCode == NegotiateAuthenticationStatusCode .ContinueNeeded);

if (statusCode == NegotiateAuthenticationStatusCode.OK)
{
 ....
}
else
{
...
}

Alternative Designs

No response

Risks

This API currently works well for bot client and server side of HTTP. We really have weak test coverage for SMTP and other protocols.

Tagging subscribers to this area: @dotnet/ncl, @vcsjones
See info in area-owners.md if you want to be subscribed.

Issue Details

---

Background and motivation

runtime already have very similar implementation - used primarily by SocketsHttphandler and partially by SMTP.
Kestrel currently use this internal API via Reflection (#29270). Additionally, we would like to have similar authentication in Android handler that lives outside of runtime repo.

Tha main goal is to expose existing functionality via public API so other components can leverage it as well.

API Proposal

namespace System.Net.Security
{
 public class NegotiateAuthenticationClientOptions
 {
 // Specifies the GSSAPI authentication package used for the authentication.
 // Common values are Negotiate, NTLM or Kerberos. Default value is Negotiate.
 public string Package { get; set; }

 // The NetworkCredential that is used to establish the identity of the client.
 // Default value is CrendentialCache.DefaultCredential.
 public NetworkCredential Credential { get; set; }

 // The Service Principal Name (SPN) that uniquely identifies the server to authenticate.
 public string? TargetName { get; set; }

 // The ChannelBinding that is used for extended protection.
 public ChannelBinding? Binding { get; set; }

 // Indicates the requires level of protection of the authentication exchange
 // and any further data exchange.
 // Valid values: None, Sign, EncryptAndSign
 // Default value: None
 System.Net.Security.ProtectionLevel RequiredProtectionLevel { get; set; }
 }

 public class NegotiateAuthenticationServerOptions
 {
 // Specifies the GSSAPI authentication package used for the authentication.
 // Common values are Negotiate, NTLM or Kerberos. Default value is Negotiate.
 public string Package { get; set; }

 // The NetworkCredential that is used to establish the identity of the client.
 // Default value is CrendentialCache.DefaultCredential.
 // Note: I'm not quite sure of the meaning of this on the server side but
 // it exists on GSSAPI side.
 public NetworkCredential Credential { get; set; }

 // The ChannelBinding that is used for extended protection.
 public ChannelBinding? Binding { get; set; }

 // Indicates the requires level of protection of the authentication exchange
 // and any further data exchange.
 // Valid values: None, Sign, EncryptAndSign
 // Default value: None
 System.Net.Security.ProtectionLevel RequiredProtectionLevel { get; set; }
 }

 public class NegotiateAuthentication : IDisposable
 {
 // Create client-side authentication
 public NegotiateAuthentication(NegotiateAuthenticationClientOptions clientOptions);

 // Create server-side authentication
 public NegotiateAuthentication(NegotiateAuthenticationServerOptions serverOptions);

 // Indicates whether the initial authentication finished.
 // NOTE: Original it was named IsCompleted in the proposal but I renamed
 // it to match the property on NegotiateStream.
 public bool IsAuthenticated { get; set; }

 // Indicates negotiated protection level (can be higher than the required one).
 // Returns None if authentication was not finished yet.
 public System.Net.Security.ProtectionLevel ProtectionLevel { get; set; }

 // Indicates whether signing was negotiated.
 // Returns false if authentication was not finished yet.
 public bool IsSigned { get; set; }

 // Indicates whether signing was negotiated.
 // Returns false if authentication was not finished yet.
 public bool IsEncrypted { get; set; }

 // Indicates whether the client and server are mutually authenticated.
 // Returns false if authentication was not finished yet.
 public bool IsMutuallyAuthenticated { get; set; }

 // Indicates whether this is server-side authentication context.
 // Returns value based on the constructor used, provided for parity with
 // NegoatiateStream.
 public bool IsServer { get; set; }

 // The GSSAPI package name that was used for the authentiation. Initially it's
 // the name specified in the options in constructor. After successful authentication
 // it should return the actual mechanism used. For example, if Negotiate is
 // specified as the requested GSSAPI package this may return NTLM or Kerberos once
 // authentication exchange is complete (eg. IsAuthenticated == true).
 //
 // NOTE: This is partly duplicate with RemoteIdentity so it may not be necessary
 // on the public API.
 public string Package { get; }

 // For server context it returns the SPN target name of the client after successful
 // authentication. For client context it returns the target name specified in the
 // constructor options.
 public string? TargetName { get; }

 // Gets information about the identity of the remote party.
 //
 // When accessed by the client, this property returns a GenericIdentity containing
 // the Service Principal Name (SPN) of the server and the authentication protocol used.
 //
 // Throws InvalidOperationException if authentication was not finished yet
 // (IsAuthenticated == false) for server-side.
 public System.Security.Principal.IIdentity RemoteIdentity { get };

 public byte[] GetOutgoingBlob(ReadOnlySpan<byte> incomingBlob, out NegotiateAuthenticationStatusCode statusCode);

 // Base64 version of GetOutgoingBlob
 public string GetOutgoingBlob(string incomingBlob, out NegotiateAuthenticationStatusCode statusCode);

 // TODO (APIs not necessary for HTTP authentication but necessary for high-level protocols
 // like SASL and NegotiateStream):
 // Wrap, Unwrap as replacement for Encrypt, Decrypt, MakeSignature and VerifySignature
 // GetMIC and VerifyMIC if we find a use for that
 }

 // NOTE: Mirrors SecurityStatusPalErrorCode at the moment but it should mostly map to GSSAPI error
 // codes.
 public enum NegotiateAuthenticationStatusCode
 {
 NotSet = 0,
 OK,
 ContinueNeeded,
 CompleteNeeded,
 CompleteAndContinue,
 ContextExpired,
 CredentialsNeeded,
 Renegotiate,
 TryAgain,

 // Errors
 OutOfMemory,
 InvalidHandle,
 Unsupported,
 TargetUnknown,
 InternalError,
 PackageNotFound,
 NotOwner,
 CannotInstall,
 InvalidToken,
 CannotPack,
 QopNotSupported,
 NoImpersonation,
 LogonDenied,
 UnknownCredentials,
 NoCredentials,
 MessageAltered,
 OutOfSequence,
 NoAuthenticatingAuthority,
 IncompleteMessage,
 IncompleteCredentials,
 BufferNotEnough,
 WrongPrincipal,
 TimeSkew,
 UntrustedRoot,
 IllegalMessage,
 CertUnknown,
 CertExpired,
 DecryptFailure,
 AlgorithmMismatch,
 SecurityQosFailed,
 SmartcardLogonRequired,
 UnsupportedPreauth,
 BadBinding,
 DowngradeDetected,
 ApplicationProtocolMismatch,
 NoRenegotiation
 }
}

API Usage

var auth = new NegotiateAuthentication(new NegotiateAuthenticationClientOptions("NTLM", testCredential "HTTP/foo"));
NegotiateAuthenticationStatusCode statusCode;

byte[]? negotiateBlob = ntAuth.GetOutgoingBlob(ReadOnlySpan<byte>.Empty, out NegotiateAuthenticationStatusCode statusCode);
sendBlob(negotiateBlob);
do
{
 buffer = receiveBlob();
 byte[]? negotiateBlob = ntAuth.GetOutgoingBlob(buffer, out statusCode);
} while (statusCode == NegotiateAuthenticationStatusCode .ContinueNeeded);

if (statusCode == NegotiateAuthenticationStatusCode.OK)
{
 ....
}
else
{
...
}

### Alternative Designs

_No response_

### Risks

This API currently works well for bot client and server side of HTTP. We really have weak test coverage for SMTP and other protocols. 

<table>
 <tr>
 <th align="left">Author:</th>
 <td>wfurt</td>
 </tr>
 <tr>
 <th align="left">Assignees:</th>
 <td>wfurt</td>
 </tr>
 <tr>
 <th align="left">Labels:</th>
 <td>

`api-suggestion`, `area-System.Net.Security`

</td>
 </tr>
 <tr>
 <th align="left">Milestone:</th>
 <td>7.0.0</td>
 </tr>
</table>
</details>

[davidfowl]

public byte[] GetOutgoingBlob(ReadOnlySpan<byte> incomingBlob, out NegotiateAuthenticationStatusCode statusCode);

Can we make a non-allocating API as well?

[filipnavara]

Can we make a non-allocating API as well?

It's non-trivial, unfortunately. GetOutgoingBlob mutates the internal state and there's no easy way to know how big buffer you would need. That prevents using the common Try*+Span patterns used elsewhere. It may be possible to make a version that has optimistic non-allocating code path for the buffer although some internal allocations are likely still going to happen. I am open to suggestions.

[wfurt]

There is pattern in SslStream where you can pass in buffer via ref and if big enough it would be used, if not, new one would be allocated. I don't know if that is worth of the try but I agree the rest is difficult. We we would go would go down that path it would be

NegotiateAuthenticationStatusCode GetOutgoingBlob(ReadOnlySpan<byte> incomingBlob,ref byte[]? outgoingBlob);

[filipnavara]

There is pattern in SslStream where you can pass in buffer via ref and if big enough it would be used, if not, new one would be allocated. I don't know if that is worth of the try but I agree the rest is difficult. We we would go would go down that path it would be

NegotiateAuthenticationStatusCode GetOutgoingBlob(ReadOnlySpan<byte> incomingBlob,ref byte[]? outgoingBlob);

I am honestly not sure if it's worth it. Another idea would be to return a simple disposable struct. That way it would be possible to pool the buffer and it would make it possible to clear the buffer contents during Dispose too. It's additional complexity but it would make it slightly less error-prone to ensure that some sensitive data are not kept around.

[wfurt]

yah. I'm not sure either.

[filipnavara]

Apparently the concept in my proposal above already exists as the IMemoryOwner<T> interface, so we can have

public IMemoryOwner<byte> GetOutgoingBlob(ReadOnlySpan<byte> incomingBlob, out NegotiateAuthenticationStatusCode statusCode);

and do the pooling.