AesGcm.Decrypt() doesn't throw CryptographicException

[samuel-lucas6]

Type of issue

Typo

Description

This page says a CryptographicException is thrown if the tag couldn't be verified, but the function actually throws AuthenticationTagMismatchException.

This error may apply to other AEAD pages as well, but I haven't tested those.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.aesgcm.decrypt?view=net-8.0#system-security-cryptography-aesgcm-decrypt(system-readonlyspan((system-byte))-system-readonlyspan((system-byte))-system-readonlyspan((system-byte))-system-span((system-byte))-system-readonlyspan((system-byte)))

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System.Security.Cryptography/AesGcm.xml

Document Version Independent Id

4ea1eb00-71c7-149a-d174-b44f3b9b91a4

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-security, @vcsjones

[vcsjones]

AuthenticationTagMismatchException derives from CryptographicException. In .NET 8 it was changed to throw a more specific kind of CryptographicException. I suppose the documentation could be updated to reflect that.

This also applies to AesCcm and ChaCha20Poly1305.

[samuel-lucas6]

I didn't think about that. This just came up whilst writing tests for a wrapper around AES-GCM and checking for CryptographicException causes the test to fail.

[vcsjones]

@gewarren what is the best way to address this? We need to make a change to the documentation for .NET 8+. Can you point me to an example of how to do conditional documentation? "For .NET < 8, the documentation is this, and for .NET >= 8 the documentation is that".

[gewarren]

@vcsjones Here's an example:

dotnet-api-docs/xml/System/Enum.xml

Line 565 in 77ee1b1

<exception cref="T:System.InvalidOperationException">.NET 8 and later versions: <paramref name="enumType" /> is a Boolean-backed enumeration type.</exception>

I would change CryptographicException to ".NET 7 and earlier versions only:...".
And add one for AuthenticationTagMismatchException with ".NET 8 and later versions:..."

[bartonjs]

This just came up whilst writing tests for a wrapper around AES-GCM and checking for CryptographicException causes the test to fail.

In general, the expectation is that you should be using (in xUnit terms) Assert.ThrowsAny instead of Assert.Throws when calling into anything in the framework. CryptographicException, in particular, is subclassed with non-public types to handle "we're returning an OS error and don't know what it is"; and thus it's not actually possible to write a "throws this exactly" filter in many cases.

[samuel-lucas6]

In general, the expectation is that you should be using (in xUnit terms) Assert.ThrowsAny instead of Assert.Throws when calling into anything in the framework. CryptographicException, in particular, is subclassed with non-public types to handle "we're returning an OS error and don't know what it is"; and thus it's not actually possible to write a "throws this exactly" filter in many cases.

Thanks for that advice. I've always used MSTest and not sure that has that type of method but will look into it.