diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 24 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 89 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/cmac.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 98 |
4 files changed, 108 insertions, 111 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 15d8b980..2f4cdd3b 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -30,10 +30,10 @@ A specific ``backend`` may provide one or more of these interfaces. this backend. :param cipher: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherAlgorithm` provider. :param mode: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider. :returns: ``True`` if the specified ``cipher`` and ``mode`` combination is supported by this backend, otherwise ``False`` @@ -42,18 +42,18 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_symmetric_encryption_ctx(cipher, mode) Create a - :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` that + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherContext` that can be used for encrypting data with the symmetric ``cipher`` using the given ``mode``. :param cipher: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherAlgorithm` provider. :param mode: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherContext` :raises ValueError: When tag is not None in an AEAD mode @@ -61,18 +61,18 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: create_symmetric_decryption_ctx(cipher, mode) Create a - :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` that + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherContext` that can be used for decrypting data with the symmetric ``cipher`` using the given ``mode``. :param cipher: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.CipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherAlgorithm` provider. :param mode: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.Mode` provider. + :class:`~cryptography.hazmat.primitives.ciphers.modes.Mode` provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.CipherContext` + :class:`~cryptography.hazmat.primitives.ciphers.base.CipherContext` :raises ValueError: When tag is None in an AEAD mode @@ -157,7 +157,7 @@ A specific ``backend`` may provide one or more of these interfaces. .. method:: cmac_algorithm_supported(algorithm) :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.BlockCipherAlgorithm` provider. :return: Returns True if the block cipher is supported for CMAC by this backend @@ -168,7 +168,7 @@ A specific ``backend`` may provide one or more of these interfaces. uses the specified ``algorithm`` to calculate a message authentication code. :param algorithm: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.BlockCipherAlgorithm` provider. :returns: diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 86a3a7e4..67c6b3d5 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -14,95 +14,6 @@ to document argument and return types. .. _`Abstract Base Classes`: https://docs.python.org/3/library/abc.html -Symmetric ciphers ------------------ - -.. 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. - - -Cipher modes -~~~~~~~~~~~~ - -Interfaces used by the symmetric cipher modes described in -:ref:`Symmetric Encryption Modes <symmetric-encryption-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. - Asymmetric interfaces --------------------- diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst index 1ba1b3fa..14e1842f 100644 --- a/docs/hazmat/primitives/mac/cmac.rst +++ b/docs/hazmat/primitives/mac/cmac.rst @@ -22,7 +22,7 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. .. versionadded:: 0.4 CMAC objects take a - :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` provider. + :class:`~cryptography.hazmat.primitives.ciphers.base.BlockCipherAlgorithm` provider. .. doctest:: @@ -39,7 +39,7 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. raised. If ``algorithm`` isn't a - :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.BlockCipherAlgorithm` provider then ``TypeError`` will be raised. To check that a given signature is correct use the :meth:`verify` method. @@ -55,13 +55,13 @@ A subset of CMAC with the AES-128 algorithm is described in :rfc:`4493`. cryptography.exceptions.InvalidSignature: Signature did not match digest. :param algorithm: An - :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.BlockCipherAlgorithm` provider. :param backend: An :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` provider. :raises TypeError: This is raised if the provided ``algorithm`` is not an instance of - :class:`~cryptography.hazmat.primitives.interfaces.BlockCipherAlgorithm` + :class:`~cryptography.hazmat.primitives.ciphers.base.BlockCipherAlgorithm` :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the provided ``backend`` does not implement :class:`~cryptography.hazmat.backends.interfaces.CMACBackend` diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index b2ce376b..53023015 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -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.base.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.base.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.base.CipherContext` provider. If the backend doesn't support the requested combination of ``cipher`` @@ -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.base.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.base .. class:: CipherContext @@ -505,6 +506,91 @@ 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. + + .. _`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 |