[API Proposal]: Add public [Compute/Verify]IntegrityCheck methods to NegotiateAuthentication

[filipnavara]

Background and motivation

The NegotiateAuthentication API (#69920) was added in .NET 7. It exposes functionality for Negotiate, NTLM and Kerberos authentication. It's implemented as a wrapper over GSSAPI (Unix), SSPI (Windows), and there's managed NTLM implementation for other platforms (Android, tvOS) where native API is not available. The initial API shape was driven by the goal of removing reflection access to internal NTAuthentication class, with focus on meeting the needs of email protocols (SASL in context of IMAP, SMTP), SQL protocols (SQL Server and PostgreSQL), client-side HTTP, and server-side HTTP in ASP.NET.

One omission in the original proposal and its later updates are the GetMIC and VerifyMIC operations defined in GSSAPI (https://datatracker.ietf.org/doc/html/rfc2743). These APIs are not used in any of the scenarios above, but they are needed for more specialized protocols, like the NegotiateStream. It is thus desirable to expose them for public use as well.

The operations implemented by the API are generating a "message integrity code" on one side of the communication protocol and verifying it on the other side. It is usually implemented as cryptographic signing operation with a negotiated key.

API Proposal

namespace System.Net.Security;

public sealed class NegotiateAuthentication : IDisposable
{
 /// <summary>
 /// Computes the message integrity check of a given message.
 /// </summary>
 /// <param name="message">Input message for MIC calculation.</param>
 /// <param name="signature">Buffer writer where the MIC is written.</param>
 /// <remarks>
 /// Implements the GSSAPI GetMIC operation.
 ///
 /// The method modifies the internal state and may update sequence numbers depending on the
 /// selected algorithm. Two successive invocations thus don't produce the same result and
 /// it's important to carefully pair GetMIC and VerifyMIC calls on the both sides of the
 /// authenticated session.
 /// </remarks>
 public void ComputeIntegrityCheck(ReadOnlySpan<byte> message, IBufferWriter<byte> signature);

 /// <summary>
 /// Verifies the message integrity check of a given message.
 /// </summary>
 /// <param name="message">Input message for MIC calculation.</param>
 /// <param name="signature">MIC to be verified.</param>
 /// <returns>For successfully verified MIC, the method returns true.</returns>
 /// <remarks>
 /// Implements the GSSAPI VerifyMIC operation.
 ///
 /// The method modifies the internal state and may update sequence numbers depending on the
 /// selected algorithm. Two successive invocations thus don't produce the same result and
 /// it's important to carefully pair GetMIC and VerifyMIC calls on the both sides of the
 /// authenticated session.
 /// </remarks>
 public bool VerifyIntegrityCheck(ReadOnlySpan<byte> message, ReadOnlySpan<byte> signature);
}

API Usage

// Client:
var signatureBuffer = new ArrayBufferWriter<byte>();
negotiateAuthentication.ComputeIntegrityCheck(message, signatureBuffer);
// Send (message, signatureSize: signatureBuffer.WrittenBytes, signatureSpan: signatureBuffer.WrittenSpan) to server

// Server:
// Reconstruct (message, signatureSize, signatureSpan) from the wire format
if (!negotiateAuthentication.VerifyIntegrityCheck(message, signatureSpan))
 throw new FormatException("The message has been altered");
// Process the message

Alternative Designs

No response

Risks

No response

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

Issue Details

---

Background and motivation

The NegotiateAuthentication API (#69920) was added in .NET 7. It exposes functionality for Negotiate, NTLM and Kerberos authentication. It's implemented as a wrapper over GSSAPI (Unix), SSPI (Windows), and there's managed NTLM implementation for other platforms (Android, tvOS) where native API is not available. The initial API shape was driven by the goal of removing reflection access to internal NTAuthentication class, with focus on meeting the needs of email protocols (SASL in context of IMAP, SMTP), SQL protocols (SQL Server and PostgreSQL), client-side HTTP, and server-side HTTP in ASP.NET.

One omission in the original proposal and its later updates are the GetMIC and VerifyMIC operations defined in GSSAPI (https://datatracker.ietf.org/doc/html/rfc2743). These APIs are not used in any of the scenarios above, but they are needed for more specialized protocols, like the NegotiateStream. It is thus desirable to expose them for public use as well.

The operations implemented by the API are generating a "message integrity code" on one side of the communication protocol and verifying it on the other side. It is usually implemented as cryptographic signing operation with a negotiated key.

API Proposal

namespace System.Net.Security;

public sealed class NegotiateAuthentication : IDisposable
{
 /// <summary>
 /// Computes the message integrity check of a given message.
 /// </summary>
 /// <param name="message">Input message for MIC calculation.</param>
 /// <param name="signature">Buffer writer where the MIC is written.</param>
 /// <remarks>
 /// The method modifies the internal state and may update sequence numbers depending on the
 /// selected algorithm. Two successive invocations thus don't produce the same result and
 /// it's important to carefully pair GetMIC and VerifyMIC calls on the both sides of the
 /// authenticated session.
 /// </remarks>
 internal void GetMIC(ReadOnlySpan<byte> message, IBufferWriter<byte> signature);

 /// <summary>
 /// Verifies the message integrity check of a given message.
 /// </summary>
 /// <param name="message">Input message for MIC calculation.</param>
 /// <param name="signature">MIC to be verified.</param>
 /// <returns>For successfully verified MIC, the method returns true.</returns>
 /// <remarks>
 /// The method modifies the internal state and may update sequence numbers depending on the
 /// selected algorithm. Two successive invocations thus don't produce the same result and
 /// it's important to carefully pair GetMIC and VerifyMIC calls on the both sides of the
 /// authenticated session.
 /// </remarks>
 internal bool VerifyMIC(ReadOnlySpan<byte> message, ReadOnlySpan<byte> signature);
}

API Usage

TBD

Alternative Designs

No response

Risks

No response

Author:	filipnavara
Assignees:	-
Labels:	api-suggestion, area-System.Net.Security, untriaged
Milestone:	-

[filipnavara]

Related: #86948 /cc @wfurt

[wfurt]

I assume we have internal implementation already for NegotiateStream @filipnavara? e.g. the main focus is internal cleanup?

[filipnavara]

I assume we have internal implementation already for NegotiateStream @filipnavara?

We have it on Unix and managed, it is somewhat trivial on Windows and introduced in #86948.

e.g. the main focus is internal cleanup?

Correct. It's primarily to expose everything through testable public APIs on NegotiateAuthentication instead of compiling the whole implementation again into the test assemblies.

[vcsjones]

• Writing to an IBufferWriter verifying with a Span seems like a somewhat odd symmetry. Should GetMIC write to a Span, or have an overload that does?
• Should GetMIC return an int indicating how many bytes were written to the destination?
• Input buffers that are written to are typically called "destination", should we do that here? Or rather, why have an exception here?

[filipnavara]

• Writing to an IBufferWriter verifying with a Span seems like a somewhat odd symmetry. Should GetMIC write to a Span, or have an overload that does?

You don't know the size of the signature upfront. That's a similar issue like in the existing Wrap/Unwrap methods on the same type.

• Should GetMIC return an int indicating how many bytes were written to the destination?

I don't see the need if IBufferWriter is used since it already has the information.

• Input buffers that are written to are typically called "destination", should we do that here? Or rather, why have an exception here?

I don't have strong opinion about naming.

[bartonjs]

Acronyms/abbreviations/initialisms are generally discouraged.

ComputeIntegrityCheck and VerifyIntegrityCheck seem like more approachable names.

[filipnavara]

ComputeIntegrityCheck and VerifyIntegrityCheck seem like more approachable names.

That would have been my second choice if I had to name it. 😅 The only reason going for MIC is to follow the GSSAPI specification and make it easier to search for it.

[filipnavara]

I updated the names and added API usage.