[API Proposal]: AesGcm/AesCcm.KeySize

[sdrapkin]

API Proposal

namespace System.Security.Cryptography;

public partial class AesGcm
{
    public int KeySize { get; }
}

public partial class AesCcm
{
    public int KeySize { get; }
}

API Usage

void OnlyAesGcm256(AesGcm gcm)
{
    const int ALLOWED_KEY_SIZE = 256;
    if (gcm.KeySize != ALLOWED_KEY_SIZE) throw new CryptographicException();
    // do stuff
}

Alternative Designs

No response

Risks

New APIs. No breaking changes/risks. No performance regressions/impacts.

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

Issue Details

---

Background and motivation

System.Security.Cryptography:

Proposal-1:
AesGcm and AesCcm currently expose .NonceByteSizes and .TagByteSizes. However they do not expose allowed .KeyByteSizes.

AesGcm and AesCcm currently each support 3 key sizes: 16, 24, and 32 bytes.
This proposal is for a public static property exposing these supported key sizes.
Note: an instance of Aes already provides .LegalKeySizes property.

Proposal-2:
Add .KeySize public property to instances of AesGcm and AesCcm. The purpose is to validate the externally-provided instance of each of these classes for adherence to specific key-strength level (ex. API requires AesGcm instance with 256-bit key strength only). Note that instance of Aes already provides .KeySize property precisely for that purpose.

API Proposal

namespace System.Security.Cryptography;

public class AesGcm // and AesCcm
{
    public int KeySize { get; }
    public static KeySizes KeyByteSizes = new KeySizes(16, 32, 8);
}

API Usage

// don't use in production, but shows the new APIs
bool IsValidGcmKey(byte[] key)
{
    var allowedKeySizes = AesGcm.KeyByteSizes;
    var keyLength = key.Length;
    var min = allowedKeySizes.MinSize;
    var max = allowedKeySizes.MaxSize;
    var step = allowedKeySizes.SkipSize;
    for (var i = min; i <= max; i += step)
        if (keyLength == i) return true;
    return false;
}

void OnlyAesGcm256(AesGcm gcm)
{
    const int ALLOWED_KEY_SIZE = 256 / 8;
    if (gcm.KeySize != ALLOWED_KEY_SIZE) throw new CryptographicException();
    // do stuff
}

Alternative Designs

No response

Risks

New APIs. No breaking changes/risks. No performance regressions/impacts.

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

[bartonjs]

The reason for providing the NonceSizeBytes and TagSizeBytes is mainly to bring up that these have variability of implementation in the ecosystem at large; we've generally not found evidence that anyone actually ever reads them.

We intentionally don't allow retrieving the key itself from these new types, but adding an instance KeySize property seems reasonable to me.

[sdrapkin]

Can this be added to .NET 8?

[bartonjs]

I've removed the KeyByteSizes segment from the proposal and marked it ready-for-review. Given that every other KeySize property we have is reporting in bits, I think we should continue with that here, so I updated the sample accordingly.

[bartonjs]

Video

• Changed KeySize to KeySizeInBytes

namespace System.Security.Cryptography;

public partial class AesGcm
{
    public int KeySizeInBytes { get; }
}

public partial class AesCcm
{
    public int KeySizeInBytes { get; }
}