[API Proposal]: Provide an implementation AesGcm in Microsoft.Bcl.Cryptography

[vcsjones]

Background and motivation

The AesGcm class was introduced in to .NET in .NET Core 3.1. AES-GCM is an AEAD that is used in many protocols and specifications. Its broad use in in those specs makes it desirable or mandatory to support them.

For .NET Framework, there is no AES-GCM implementation that is readily available. Developers that want AES-GCM either have to p/invoke to Windows or find some other alternative implementation.

This is a proposal to add AesGcm to Microsoft.Bcl.Cryptography.

1. When the package is build for .NET (Core), it will type-forward in to the shared runtime implementation.
2. When the package is build for .NET Framework, it will carry the required API surface and p/invokes similar to SP800108HmacCounterKdf
3. When the package is build for .NET Standard, it will behave similar to .NET Framework, however will perform a runtime check that the platform is Windows.

This means that the package will only provide an implementation on Windows. This is largely okay - developers on non-Windows platforms already have this in .NET itself and will benefit from the type forwards.

API Proposal

To provide the best experience, I think the ref needs to be split between .NET, .NET Framework, and .NET Standard.

This is because of the constructors that were replaced in .NET 8. For .NET Framework and .NET Standard, it would be ideal that we provide them with the same improved constructors since the new constructors are meant to mitigate misuse.

.NET Framework and .NET Standard

namespace System.Security.Cryptography;

public sealed partial class AesGcm : System.IDisposable
{
    // NOT included because they are obsolete
    // public AesGcm(byte[] key) { }
    // public AesGcm(System.ReadOnlySpan<byte> key) { }
    public AesGcm(byte[] key, int tagSizeInBytes) { }
    public AesGcm(System.ReadOnlySpan<byte> key, int tagSizeInBytes) { }
    public static bool IsSupported { get { throw null; } }
    public static System.Security.Cryptography.KeySizes NonceByteSizes { get { throw null; } }
    public static System.Security.Cryptography.KeySizes TagByteSizes { get { throw null; } }
    public int? TagSizeInBytes { get { throw null; } }
    public void Decrypt(byte[] nonce, byte[] ciphertext, byte[] tag, byte[] plaintext, byte[]? associatedData = null) { }
    public void Decrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> ciphertext, System.ReadOnlySpan<byte> tag, System.Span<byte> plaintext, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
    public void Dispose() { }
    public void Encrypt(byte[] nonce, byte[] plaintext, byte[] ciphertext, byte[] tag, byte[]? associatedData = null) { }
    public void Encrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> plaintext, System.Span<byte> ciphertext, System.Span<byte> tag, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
}

public sealed partial class AuthenticationTagMismatchException : CryptographicException
{
    public AuthenticationTagMismatchException();
    public AuthenticationTagMismatchException(string message);
    public AuthenticationTagMismatchException(string message, System.Exception inner);
}

.NET 8+ type forward

namespace System.Security.Cryptography;

// Matches ref for .NET 8.
public sealed partial class AesGcm : System.IDisposable
{
    [System.ObsoleteAttribute("AesGcm should indicate the required tag size for encryption and decryption. Use a constructor that accepts the tag size.", DiagnosticId="SYSLIB0053", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
    public AesGcm(byte[] key) { }
    public AesGcm(byte[] key, int tagSizeInBytes) { }
    [System.ObsoleteAttribute("AesGcm should indicate the required tag size for encryption and decryption. Use a constructor that accepts the tag size.", DiagnosticId="SYSLIB0053", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
    public AesGcm(System.ReadOnlySpan<byte> key) { }
    public AesGcm(System.ReadOnlySpan<byte> key, int tagSizeInBytes) { }
    public static bool IsSupported { get { throw null; } }
    public static System.Security.Cryptography.KeySizes NonceByteSizes { get { throw null; } }
    public static System.Security.Cryptography.KeySizes TagByteSizes { get { throw null; } }
    public int? TagSizeInBytes { get { throw null; } }
    public void Decrypt(byte[] nonce, byte[] ciphertext, byte[] tag, byte[] plaintext, byte[]? associatedData = null) { }
    public void Decrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> ciphertext, System.ReadOnlySpan<byte> tag, System.Span<byte> plaintext, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
    public void Dispose() { }
    public void Encrypt(byte[] nonce, byte[] plaintext, byte[] ciphertext, byte[] tag, byte[]? associatedData = null) { }
    public void Encrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> plaintext, System.Span<byte> ciphertext, System.Span<byte> tag, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
}

public sealed partial class AuthenticationTagMismatchException : CryptographicException
{
    public AuthenticationTagMismatchException();
    public AuthenticationTagMismatchException(string message);
    public AuthenticationTagMismatchException(string message, System.Exception inner);
}

API Usage

Same as .NET.

Alternative Designs

This proposal leaves out AesCcm. This omission is purely due to no known demand for AES-CCM in downlevel platforms, whereas AES-GCM has demonstrated considerable demand. We can include AesCcm for completeness if desired.

Risks

This carries the similar risks of providing any API as a package. It carries maintenance burden.

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

Issue Details

---

Background and motivation

The AesGcm class was introduced in to .NET in .NET Core 3.1. AES-GCM is an AEAD that is used in many protocols and specifications. Its broad use in in those specs makes it desirable or mandatory to support them.

For .NET Framework, there is no AES-GCM implementation that is readily available. Developers that want AES-GCM either have to p/invoke to Windows or find some other alternative implementation.

This is a proposal to add AesGcm to Microsoft.Bcl.Cryptography.

1. When the package is build for .NET (Core), it will type-forward in to the shared runtime implementation.
2. When the package is build for .NET Framework, it will carry the required API surface and p/invokes similar to SP800108HmacCounterKdf
3. When the package is build for .NET Standard, it will behave similar to .NET Framework, however will perform a runtime check that the platform is Windows.

This means that the package will only provide an implementation on Windows. This is largely okay - developers on non-Windows platforms already have this in .NET itself and will benefit from the type forwards.

API Proposal

To provide the best experience, I think the ref needs to be split between .NET, .NET Framework, and .NET Standard.

This is because of the constructors that were replaced in .NET 8. For .NET Framework and .NET Standard, it would be ideal that we provide them with the same improved constructors since the new constructors are meant to mitigate misuse.

For .NET, we need the API shape to make between the respective versions in order for the type forward to work, otherwise we'll get MissingMemberExceptions when the type forwards the new constructors.

As those versions of .NET age out of support, the ref-split can be simplified to just .NET Framework / Standard and .NET.

.NET Framework and .NET Standard

public sealed partial class AesGcm : System.IDisposable
{
    // NOT included because they are obsolete
    // public AesGcm(byte[] key) { }
    // public AesGcm(System.ReadOnlySpan<byte> key) { }
    public AesGcm(byte[] key, int tagSizeInBytes) { }
    public AesGcm(System.ReadOnlySpan<byte> key, int tagSizeInBytes) { }
    public static bool IsSupported { get { throw null; } }
    public static System.Security.Cryptography.KeySizes NonceByteSizes { get { throw null; } }
    public static System.Security.Cryptography.KeySizes TagByteSizes { get { throw null; } }
    public int? TagSizeInBytes { get { throw null; } }
    public void Decrypt(byte[] nonce, byte[] ciphertext, byte[] tag, byte[] plaintext, byte[]? associatedData = null) { }
    public void Decrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> ciphertext, System.ReadOnlySpan<byte> tag, System.Span<byte> plaintext, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
    public void Dispose() { }
    public void Encrypt(byte[] nonce, byte[] plaintext, byte[] ciphertext, byte[] tag, byte[]? associatedData = null) { }
    public void Encrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> plaintext, System.Span<byte> ciphertext, System.Span<byte> tag, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
}

.NET 6, 7 type forward

// Matches ref from .NET 6 and 7.
public sealed partial class AesGcm : System.IDisposable
{
    public AesGcm(byte[] key) { }
    public AesGcm(System.ReadOnlySpan<byte> key) { }
    public static bool IsSupported { get { throw null; } }
    public static System.Security.Cryptography.KeySizes NonceByteSizes { get { throw null; } }
    public static System.Security.Cryptography.KeySizes TagByteSizes { get { throw null; } }
    public void Decrypt(byte[] nonce, byte[] ciphertext, byte[] tag, byte[] plaintext, byte[]? associatedData = null) { }
    public void Decrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> ciphertext, System.ReadOnlySpan<byte> tag, System.Span<byte> plaintext, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
    public void Dispose() { }
    public void Encrypt(byte[] nonce, byte[] plaintext, byte[] ciphertext, byte[] tag, byte[]? associatedData = null) { }
    public void Encrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> plaintext, System.Span<byte> ciphertext, System.Span<byte> tag, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
}

.NET 8 type forward

// Matches ref for .NET 8.
public sealed partial class AesGcm : System.IDisposable
{
    [System.ObsoleteAttribute("AesGcm should indicate the required tag size for encryption and decryption. Use a constructor that accepts the tag size.", DiagnosticId="SYSLIB0053", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
    public AesGcm(byte[] key) { }
    public AesGcm(byte[] key, int tagSizeInBytes) { }
    [System.ObsoleteAttribute("AesGcm should indicate the required tag size for encryption and decryption. Use a constructor that accepts the tag size.", DiagnosticId="SYSLIB0053", UrlFormat="https://aka.ms/dotnet-warnings/{0}")]
    public AesGcm(System.ReadOnlySpan<byte> key) { }
    public AesGcm(System.ReadOnlySpan<byte> key, int tagSizeInBytes) { }
    public static bool IsSupported { get { throw null; } }
    public static System.Security.Cryptography.KeySizes NonceByteSizes { get { throw null; } }
    public static System.Security.Cryptography.KeySizes TagByteSizes { get { throw null; } }
    public int? TagSizeInBytes { get { throw null; } }
    public void Decrypt(byte[] nonce, byte[] ciphertext, byte[] tag, byte[] plaintext, byte[]? associatedData = null) { }
    public void Decrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> ciphertext, System.ReadOnlySpan<byte> tag, System.Span<byte> plaintext, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
    public void Dispose() { }
    public void Encrypt(byte[] nonce, byte[] plaintext, byte[] ciphertext, byte[] tag, byte[]? associatedData = null) { }
    public void Encrypt(System.ReadOnlySpan<byte> nonce, System.ReadOnlySpan<byte> plaintext, System.Span<byte> ciphertext, System.Span<byte> tag, System.ReadOnlySpan<byte> associatedData = default(System.ReadOnlySpan<byte>)) { }
}

API Usage

Same as .NET.

Alternative Designs

1. This proposal leaves out AesCcm. This omission is purely due to no known demand for AES-CCM in downlevel platforms, whereas AES-GCM has demonstrated considerable demand. We can include AesCcm for completeness if desired.

2. The ref-split is slightly complicated, but will improve as .NET 6 and 7 age out. The "simplest" thing to do is to outbox only the ref from .NET 6. However I think this is incorrect because it would mean outboxing constructors that are obsolete. There is no reason that .NET Framework needs the obsolete constructors. We could include both the new and obsolete constructors for .NET Framework if that makes multi-targeting easier.

Risks

This carries the similar risks of providing any API as a package. It carries maintenance burden.

Author:	vcsjones
Assignees:	-
Labels:	api-suggestion, area-System.Security
Milestone:	-

[vcsjones]

/cc @GrabYourPitchforks for additional info.

[scott-xu]

It would be very helpful for SSH.NET (.NET Framework target) if this is implemented.
Currently, it uses Managed implementation based on BouncyCastle for .NET Framework.

[vcsjones]

I updated the proposal to include outboxing AuthenticationTagMismatchException. This was added since the proposal was originally written.

[terrajobst]

Video

• We only expose the good ctors
• Practically, this means this package supports .NET Framework and .NET 8.0+, and offers .NET Standard 2.0 only as an easy way to target both from a single library
• We should raise a build error when consumed by an unsupported target framework (such as .NET Standard 2.1)

namespace System.Security.Cryptography;

public sealed partial class AesGcm : System.IDisposable
{
    public AesGcm(byte[] key, int tagSizeInBytes);
    public AesGcm(ReadOnlySpan<byte> key, int tagSizeInBytes);
    public static bool IsSupported { get; }
    public static KeySizes NonceByteSizes { get; }
    public static KeySizes TagByteSizes { get; }
    public int? TagSizeInBytes { get; }
    public void Decrypt(byte[] nonce, byte[] ciphertext, byte[] tag, byte[] plaintext, byte[]? associatedData = null);
    public void Decrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> ciphertext, ReadOnlySpan<byte> tag, Span<byte> plaintext, ReadOnlySpan<byte> associatedData = default(ReadOnlySpan<byte>));
    public void Dispose();
    public void Encrypt(byte[] nonce, byte[] plaintext, byte[] ciphertext, byte[] tag, byte[]? associatedData = null);
    public void Encrypt(ReadOnlySpan<byte> nonce, ReadOnlySpan<byte> plaintext, Span<byte> ciphertext, Span<byte> tag, ReadOnlySpan<byte> associatedData = default(ReadOnlySpan<byte>));
}

public sealed partial class AuthenticationTagMismatchException : CryptographicException
{
    public AuthenticationTagMismatchException();
    public AuthenticationTagMismatchException(string message);
    public AuthenticationTagMismatchException(string message, System.Exception inner);
}