From b835fdf8fd3910a79ab408660757d9736f82d14d Mon Sep 17 00:00:00 2001 From: Jack Lloyd Date: Fri, 18 Jan 2019 11:37:01 -0500 Subject: Rename Integrity_Failure to Invalid_Authentication_Tag This makes the meaning and usage more clear. Add a specific error type so invalid tags can be distinguished without having to catch that specific type. See also #1813 --- doc/manual/cipher_modes.rst | 17 +++++++++++++---- doc/manual/keywrap.rst | 4 ++-- 2 files changed, 15 insertions(+), 6 deletions(-) (limited to 'doc/manual') diff --git a/doc/manual/cipher_modes.rst b/doc/manual/cipher_modes.rst index cc04a3750..6e78a2c1b 100644 --- a/doc/manual/cipher_modes.rst +++ b/doc/manual/cipher_modes.rst @@ -269,10 +269,19 @@ will be returned by :cpp:func:`get_cipher` if the named cipher is an AEAD mode). ever calling update is both efficient and convenient. .. note:: - During decryption, finish will throw an instance of Integrity_Failure - if the MAC does not validate. If this occurs, all plaintext previously - output via calls to update must be destroyed and not used in any - way that an attacker could observe the effects of. + + During decryption, if the supplied authentication tag does not + validate, finish will throw an instance of Invalid_Authentication_Tag + (aka Integrity_Failure, which was the name for this exception in + versions before 2.10, a typedef is included for compatability). + + If this occurs, all plaintext previously output via calls to update + must be destroyed and not used in any way that an attacker could + observe the effects of. This could be anything from echoing the + plaintext back (perhaps in an error message), or by making an external + RPC whose destination or contents depend on the plaintext. The only + thing you can do is buffer it, and in the event of an invalid tag, + erase the previously decrypted content from memory. One simply way to assure this could never happen is to never call update, and instead always marshal the entire message diff --git a/doc/manual/keywrap.rst b/doc/manual/keywrap.rst index 3116797e5..5c3aac0a3 100644 --- a/doc/manual/keywrap.rst +++ b/doc/manual/keywrap.rst @@ -23,7 +23,7 @@ functions with AES, but any 128-bit cipher will do and some other implementation .. cpp:function:: secure_vector nist_key_unwrap(const uint8_t input[], \ size_t input_len, const BlockCipher& bc) - This unwraps the result of nist_key_wrap, or throw Integrity_Failure on error. + This unwraps the result of nist_key_wrap, or throw Invalid_Authentication_Tag on error. .. cpp:function:: std::vector nist_key_wrap_padded(const uint8_t input[], \ size_t input_len, const BlockCipher& bc) @@ -33,7 +33,7 @@ functions with AES, but any 128-bit cipher will do and some other implementation .. cpp:function:: secure_vector nist_key_unwrap_padded(const uint8_t input[], \ size_t input_len, const BlockCipher& bc) - This unwraps the result of nist_key_wrap_padded, or throws Integrity_Failure + This unwraps the result of nist_key_wrap_padded, or throws Invalid_Authentication_Tag on error. RFC 3394 Interface -- cgit v1.2.3