From a397d75a1e091299d012035655bdc30376378b4c Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Mon, 2 Oct 2017 10:03:20 +0800 Subject: Add support for AES XTS (#3900) * Add support for AES XTS We drop the non-byte aligned test vectors because according to NIST http://csrc.nist.gov/groups/STM/cavp/documents/aes/XTSVS.pdf "An implementation may support a data unit length that is not a multiple of 8 bits." OpenSSL does not support this, so we can't use those test vectors. * fix docs and pep8 * docs fix * the spellchecker is so frustrating * add note about AES 192 for XTS (it's not supported) * docs work * enforce key length on ECB mode in AES as well (thanks XTS) * a few more words about why we exclude some test vectors for XTS --- docs/hazmat/primitives/symmetric-encryption.rst | 41 +++++++++++++++++++++++++ 1 file changed, 41 insertions(+) (limited to 'docs/hazmat/primitives/symmetric-encryption.rst') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 10a349b1..2635e753 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -469,6 +469,32 @@ Modes a secret message! +.. class:: XTS(tweak) + + .. versionadded:: 2.1 + + .. warning:: + + XTS mode is meant for disk encryption and should not be used in other + contexts. ``cryptography`` only supports XTS mode with + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`. + + .. note:: + + AES XTS keys are double length. This means that to do AES-128 + encryption in XTS mode you need a 256-bit key. Similarly, AES-256 + requires passing a 512-bit key. AES 192 is not supported in XTS mode. + + XTS (XEX-based tweaked-codebook mode with ciphertext stealing) is a mode + of operation for the AES block cipher that is used for `disk encryption`_. + + **This mode does not require padding.** + + :param bytes tweak: The tweak is a 16 byte value typically derived from + something like the disk sector number. A given ``(tweak, key)`` pair + should not be reused, although doing so is less catastrophic than + in CTR mode. + Insecure modes -------------- @@ -744,6 +770,20 @@ Interfaces used by the symmetric cipher modes described in Exact requirements of the tag are described by the documentation of individual modes. + +.. class:: ModeWithTweak + + .. versionadded:: 2.1 + + A cipher mode with a tweak. + + .. attribute:: tweak + + :type: bytes + + Exact requirements of the tweak are described by the documentation of + individual modes. + Exceptions ~~~~~~~~~~ @@ -766,3 +806,4 @@ Exceptions .. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation#Electronic_Codebook_.28ECB.29 .. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm .. _`OpenPGP`: http://openpgp.org +.. _`disk encryption`: https://en.wikipedia.org/wiki/Disk_encryption_theory#XTS -- cgit v1.2.3