[Breaking change]: AesGcm constructors without a tag size are obsolete

[vcsjones]

Description

The constructors for System.Security.Cryptography.AesGcm that do not accept a tagSizeInBytes parameter have been marked obsolete in favor of new constructors that accept the required tag size.

Version

.NET 8 Preview 5

Previous behavior

The AesGcm(byte[] key) and AesGcm(ReadOnlySpan<byte> key) constructors were not obsolete.

New behavior

The AesGcm(byte[] key) and AesGcm(ReadOnlySpan<byte> key) constructors have been marked as obsolete.

Type of breaking change

• Binary incompatible: Existing binaries may encounter a breaking change in behavior, such as failure to load or execute, and if so, require recompilation.
• Source incompatible: When recompiled using the new SDK or component or to target the new runtime, existing source code may require source changes to compile successfully.
• Behavioral change: Existing binaries may behave differently at run time.

Reason for change

AES-GCM supports tags of various lengths, from 12 to 16 bytes, depending on the platform. Previously, the AesGcm class would determine the desired tag size based on the size of the tag itself. For example, if Decrypt was used with a 14 byte tag, it was assumed the tag was supposed to be 14 bytes.

However, AES-GCM supports these various lengths by truncation. AES-GCM natively produces 16 byte tags, and shorter tags are produced by truncating the tag.

If callers of Decrypt get the tag from input and pass the tag as-is, this would effectively allow Decrypt to be used with the shortest possible tag, which reduces the effective size of the tag.

To help consumers ensure they are using tags of the correct size, new constructors for AesGcm were introduced which require up-front declaring the size of the expected tag. During Encrypt or Decrypt, the supplied tag parameter must match the size declared in the constructor.

Recommended action

Use a constructor that accepts the desired tag size.

For example, if 128-bit or 16-byte tags were being used, replace:

using AesGcm aes = new AesGcm(yourKey);

with

using AesGcm aes = new AesGcm(yourKey, tagSizeInBytes: 16);

Feature area

Cryptography

Affected APIs

• M:System.Security.Cryptography.AesGcm.#ctor(System.Byte[])
• M:System.Security.Cryptography.AesGcm.#ctor(System.ReadOnlySpan{System.Byte})

---

Associated WorkItem - 97019