Fix AEAD algorithm documentation to indicate when AuthenticationTagMismatchException is thrown

dotnet / dotnet-api-docs

.NET API reference documentation (.NET 5+, .NET Core, .NET Framework)

https://docs.microsoft.com/dotnet/api/

Other

725 stars 1.56k forks source link

Fix AEAD algorithm documentation to indicate when AuthenticationTagMismatchException is thrown #10471

Closed vcsjones closed 1 month ago

vcsjones commented 1 month ago

Summary

Starting in .NET 8, AEAD algorithms throw AuthenticationTagMismatchException to indicate that decryption failed because of the authentication tag mismatch. This is a sub-type of CryptographicException, so it was not considered a breaking change.

This clarifies in the documentation that starting in .NET 8, users should expect this exception when the authentication tag does not match during decryption.

Fixes #10465

dotnet-policy-service[bot] commented 1 month ago

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

learn-build-service-prod[bot] commented 1 month ago

Learn Build status updates of commit 2dc41e7:

:white_check_mark: Validation status: passed

File	Status	Preview URL
xml/System.Security.Cryptography/AesCcm.xml	:white_check_mark:Succeeded	View
xml/System.Security.Cryptography/AesGcm.xml	:white_check_mark:Succeeded	View
xml/System.Security.Cryptography/ChaCha20Poly1305.xml	:white_check_mark:Succeeded	View

For more details, please refer to the build report.

For any questions, please:

Try searching the learn.microsoft.com contributor guides
Post your question in the Learn support channel