aboutsummaryrefslogtreecommitdiffstats
path: root/docs/hazmat
diff options
context:
space:
mode:
authorAlex Gaynor <alex.gaynor@gmail.com>2014-06-29 20:43:29 -0700
committerAlex Gaynor <alex.gaynor@gmail.com>2014-06-29 20:43:29 -0700
commit8f1b8e88e6e9ed7d73661bb90f0e558059b610f3 (patch)
tree5b3fd5321c77e1f1b0da4d93497d03bd20f75282 /docs/hazmat
parent2d6e91f81266129c48ae775228a18d92c2d0f2c7 (diff)
downloadcryptography-8f1b8e88e6e9ed7d73661bb90f0e558059b610f3.tar.gz
cryptography-8f1b8e88e6e9ed7d73661bb90f0e558059b610f3.tar.bz2
cryptography-8f1b8e88e6e9ed7d73661bb90f0e558059b610f3.zip
Fixes #1200 -- disallow GCM truncation by default
Diffstat (limited to 'docs/hazmat')
-rw-r--r--docs/hazmat/primitives/symmetric-encryption.rst21
1 files changed, 12 insertions, 9 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index abc2b076..fffad6e8 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -317,14 +317,22 @@ Modes
Cryptography will generate a 128-bit tag when finalizing encryption.
You can shorten a tag by truncating it to the desired length but this
is **not recommended** as it lowers the security margins of the
- authentication (`NIST SP-800-38D`_ recommends 96-bits or greater).
- If you must shorten the tag the minimum allowed length is 4 bytes
- (32-bits). Applications **must** verify the tag is the expected length
- to guarantee the expected security margin.
+ authentication (`NIST SP-800-38D`_ recommends 96-bits or greater). If
+ you must shorten the tag the minimum allowed length is 4 bytes
+ (32-bits). Applications wishing to allow truncation must pass the
+ ``min_tag_length`` parameter.
+
+ .. versionchanged:: 0.5
+
+ The ``min_tag_length`` parameter was added in ``0.5``, previously
+ truncation up to ``4`` bytes was always allowed.
:param bytes tag: The tag bytes to verify during decryption. When
encrypting this must be ``None``.
+ :param bytes min_tag_length: The minimum length ``tag`` must be. By default
+ this is ``16``, meaning tag truncation is not allowed.
+
.. testcode::
import os
@@ -356,11 +364,6 @@ Modes
return (iv, ciphertext, encryptor.tag)
def decrypt(key, associated_data, iv, ciphertext, tag):
- if len(tag) != 16:
- raise ValueError(
- "tag must be 16 bytes -- truncation not supported"
- )
-
# Construct a Cipher object, with the key, iv, and additionally the
# GCM tag used for authenticating the message.
decryptor = Cipher(