Skip to content

[API Proposal]: Authenticated ciphers should distigush between mismatched tag and failure #67082

@carlreinke

Description

@carlreinke

Background and motivation

When decrypting authenticated data, AesCcm, AesGcm, and ChaCha20Poly1305 throw CryptographicException in the case when the tag does not match (indicating that either the key is wrong or the data is inauthentic) and also in the case when "the decryption operation otherwise failed". A program may want to take a different action in these two scenarios but currently cannot.

API Proposal

namespace System.Security.Cryptography
{
    // Note for discussion: Should this be sealed or unsealed?
    public sealed class AuthenticationTagMismatchException : CryptographicException
    {
        public AuthenticationTagMismatchException();
        public AuthenticationTagMismatchException(string? message);
        public AuthenticationTagMismatchException(string? message, Exception? innerException);
    }
}

API Usage

// User has provided password, and PBKDF was used to derive key.
using (var aesGcm = new AesGcm(key))
{
    try
    {
        aesGcm.Decrypt(iv, ciphertext, tag, plaintext);
    }
    catch (AuthenticationTagMismatchException)
    {
        // Notify user that password was incorrect or data was corrupt.
        // Prompt user for password again in case user typo'd password.
    }
    catch (CryptographicException)
    {
        // Notify the user that decryption failed.
    }
}

Alternative Designs

No response

Risks

No response

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions