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

1 files changed, 41 insertions, 0 deletions

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