aboutsummaryrefslogtreecommitdiffstats
path: root/doc/manual
diff options
context:
space:
mode:
authorJack Lloyd <jack@randombit.net>2019-01-18 11:37:01 -0500
committerJack Lloyd <jack@randombit.net>2019-01-18 11:37:01 -0500
commitb835fdf8fd3910a79ab408660757d9736f82d14d (patch)
treefbbd8e89d9cf910bc3a9e9ecbfce5ce290b7c8d9 /doc/manual
parent9ca22335edcb9800158f4691de20fa5d0f9cc849 (diff)
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
Diffstat (limited to 'doc/manual')
-rw-r--r--doc/manual/cipher_modes.rst17
-rw-r--r--doc/manual/keywrap.rst4
2 files changed, 15 insertions, 6 deletions
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<uint8_t> 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<uint8_t> 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<uint8_t> 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