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
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst
index 10a349b..2635e75 100644
--- a/docs/hazmat/primitives/symmetric-encryption.rst
+++ b/docs/hazmat/primitives/symmetric-encryption.rst
@@ -469,6 +469,32 @@
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 @@
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 @@
.. _`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