diff options
Diffstat (limited to 'docs/hazmat/primitives/symmetric-encryption.rst')
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 114 |
1 files changed, 106 insertions, 8 deletions
diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index b2ce376b..1cbf60ee 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -4,7 +4,7 @@ Symmetric encryption ==================== -.. currentmodule:: cryptography.hazmat.primitives.ciphers +.. module:: cryptography.hazmat.primitives.ciphers Symmetric encryption is a way to `encrypt`_ or hide the contents of material @@ -43,10 +43,10 @@ in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. 'a secret message' :param algorithms: A - :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.CipherAlgorithm` provider such as those described :ref:`below <symmetric-encryption-algorithms>`. - :param mode: A :class:`~cryptography.hazmat.primitives.interfaces.Mode` + :param mode: A :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider such as those described :ref:`below <symmetric-encryption-modes>`. :param backend: A @@ -60,7 +60,7 @@ in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. method:: encryptor() :return: An encrypting - :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :class:`~cryptography.hazmat.primitives.ciphers.CipherContext` provider. If the backend doesn't support the requested combination of ``cipher`` @@ -70,7 +70,7 @@ in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. method:: decryptor() :return: A decrypting - :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :class:`~cryptography.hazmat.primitives.ciphers.CipherContext` provider. If the backend doesn't support the requested combination of ``cipher`` @@ -193,7 +193,7 @@ Weak ciphers Modes ~~~~~ -.. currentmodule:: cryptography.hazmat.primitives.ciphers.modes +.. module:: cryptography.hazmat.primitives.ciphers.modes .. class:: CBC(initialization_vector) @@ -293,7 +293,7 @@ Modes .. danger:: When using this mode you **must** not use the decrypted data until - :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize` + :meth:`~cryptography.hazmat.primitives.ciphers.CipherContext.finalize` has been called. GCM provides **no** guarantees of ciphertext integrity until decryption is complete. @@ -422,7 +422,8 @@ Insecure modes Interfaces ---------- -.. currentmodule:: cryptography.hazmat.primitives.interfaces + +.. currentmodule:: cryptography.hazmat.primitives.ciphers .. class:: CipherContext @@ -505,6 +506,103 @@ Interfaces :raises: :class:`~cryptography.exceptions.NotYetFinalized` if called before the context is finalized. +.. class:: CipherAlgorithm + + A named symmetric encryption algorithm. + + .. attribute:: name + + :type: str + + The standard name for the mode, for example, "AES", "Camellia", or + "Blowfish". + + .. attribute:: key_size + + :type: int + + The number of bits in the key being used. + + +.. class:: BlockCipherAlgorithm + + A block cipher algorithm. + + .. attribute:: block_size + + :type: int + + The number of bits in a block. + +Interfaces used by the symmetric cipher modes described in +:ref:`Symmetric Encryption Modes <symmetric-encryption-modes>`. + +.. currentmodule:: cryptography.hazmat.primitives.ciphers.modes + +.. class:: Mode + + A named cipher mode. + + .. attribute:: name + + :type: str + + This should be the standard shorthand name for the mode, for example + Cipher-Block Chaining mode is "CBC". + + The name may be used by a backend to influence the operation of a + cipher in conjunction with the algorithm's name. + + .. method:: validate_for_algorithm(algorithm) + + :param CipherAlgorithm algorithm: + + Checks that the combination of this mode with the provided algorithm + meets any necessary invariants. This should raise an exception if they + are not met. + + For example, the + :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode uses + this method to check that the provided initialization vector's length + matches the block size of the algorithm. + + +.. class:: ModeWithInitializationVector + + A cipher mode with an initialization vector. + + .. attribute:: initialization_vector + + :type: bytes + + Exact requirements of the initialization are described by the + documentation of individual modes. + + +.. class:: ModeWithNonce + + A cipher mode with a nonce. + + .. attribute:: nonce + + :type: bytes + + Exact requirements of the nonce are described by the documentation of + individual modes. + + +.. class:: ModeWithAuthenticationTag + + A cipher mode with an authentication tag. + + .. attribute:: tag + + :type: bytes + + Exact requirements of the tag are described by the documentation of + individual modes. + + .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html .. _`recommends a 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf |