diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 26 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/ec.rst | 6 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/interfaces.rst | 33 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 20 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 166 | ||||
| -rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 51 | ||||
| -rw-r--r-- | docs/hazmat/primitives/mac/cmac.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/padding.rst | 8 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 120 |
12 files changed, 238 insertions, 208 deletions
diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index 15d8b980..0ce8f5f7 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.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.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.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.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.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.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.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.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.BlockCipherAlgorithm` provider. :returns: @@ -244,7 +244,7 @@ A specific ``backend`` may provide one or more of these interfaces. Check if the specified ``padding`` is supported by the backend. :param padding: An instance of an - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding` provider. :returns: ``True`` if the specified ``padding`` is supported by this diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index 6c3d8752..4e0f6282 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -80,4 +80,4 @@ seeded from the same pool as ``/dev/random``. .. _`OpenSSL`: https://www.openssl.org/ .. _`initializing the RNG`: https://en.wikipedia.org/wiki/OpenSSL#Predictable_keys_.28Debian-specific.29 .. _`Yarrow`: https://en.wikipedia.org/wiki/Yarrow_algorithm -.. _`Microsoft documentation`: http://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx +.. _`Microsoft documentation`: https://msdn.microsoft.com/en-us/library/windows/desktop/aa379942(v=vs.85).aspx diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst index 36bc801f..3a47da45 100644 --- a/docs/hazmat/primitives/asymmetric/dsa.rst +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -275,7 +275,7 @@ Key interfaces provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` .. attribute:: key_size @@ -338,7 +338,7 @@ Key interfaces provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext` .. class:: DSAPublicKeyWithNumbers diff --git a/docs/hazmat/primitives/asymmetric/ec.rst b/docs/hazmat/primitives/asymmetric/ec.rst index 5b114710..8b9a584b 100644 --- a/docs/hazmat/primitives/asymmetric/ec.rst +++ b/docs/hazmat/primitives/asymmetric/ec.rst @@ -304,7 +304,7 @@ Key Interfaces :class:`EllipticCurveSignatureAlgorithm` provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` .. method:: public_key() @@ -344,7 +344,7 @@ Key Interfaces :class:`EllipticCurveSignatureAlgorithm` provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext` .. attribute:: curve @@ -370,7 +370,7 @@ Key Interfaces .. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf .. _`some concern`: https://crypto.stackexchange.com/questions/10263/should-we-trust-the-nist-recommended-ecc-parameters .. _`less than 224 bits`: http://www.ecrypt.eu.org/documents/D.SPA.20.pdf -.. _`64x lower computational cost than DH`: http://www.nsa.gov/business/programs/elliptic_curve.shtml +.. _`64x lower computational cost than DH`: https://www.nsa.gov/business/programs/elliptic_curve.shtml .. _`minimize the number of security concerns for elliptic-curve cryptography`: http://cr.yp.to/ecdh/curve25519-20060209.pdf .. _`SafeCurves`: http://safecurves.cr.yp.to/ .. _`ECDSA`: https://en.wikipedia.org/wiki/ECDSA diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 43761fde..59f00c5d 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -30,6 +30,8 @@ and Elliptic Curve. ec rsa serialization + interfaces utils + .. _`proof of identity`: https://en.wikipedia.org/wiki/Public-key_infrastructure diff --git a/docs/hazmat/primitives/asymmetric/interfaces.rst b/docs/hazmat/primitives/asymmetric/interfaces.rst new file mode 100644 index 00000000..4932faa5 --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/interfaces.rst @@ -0,0 +1,33 @@ +.. hazmat:: + +.. module:: cryptography.hazmat.primitives.asymmetric + +Signature Interfaces +==================== + +.. class:: AsymmetricSignatureContext + + .. versionadded:: 0.2 + + .. method:: update(data) + + :param bytes data: The data you want to sign. + + .. method:: finalize() + + :return bytes signature: The signature. + + +.. class:: AsymmetricVerificationContext + + .. versionadded:: 0.2 + + .. method:: update(data) + + :param bytes data: The data you wish to verify using the signature. + + .. method:: verify() + + :raises cryptography.exceptions.InvalidSignature: If the signature does + not validate. + diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 4855a45c..fd97d75b 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -186,7 +186,13 @@ Once you have an encrypted message, it can be decrypted using the private key: Padding ~~~~~~~ -.. currentmodule:: cryptography.hazmat.primitives.asymmetric.padding +.. module:: cryptography.hazmat.primitives.asymmetric.padding + +.. class:: AsymmetricPadding + + .. versionadded:: 0.2 + + .. attribute:: name .. class:: PSS(mgf, salt_length) @@ -425,7 +431,7 @@ Key interfaces Sign data which can be verified later by others using the public key. :param padding: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding` provider. :param algorithm: An instance of a @@ -433,7 +439,7 @@ Key interfaces provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricSignatureContext` .. method:: decrypt(ciphertext, padding) @@ -444,7 +450,7 @@ Key interfaces :param bytes ciphertext: The ciphertext to decrypt. :param padding: An instance of an - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding` provider. :return bytes: Decrypted data. @@ -495,7 +501,7 @@ Key interfaces :param bytes signature: The signature to verify. :param padding: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding` provider. :param algorithm: An instance of a @@ -503,7 +509,7 @@ Key interfaces provider. :returns: - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + :class:`~cryptography.hazmat.primitives.asymmetric.AsymmetricVerificationContext` .. method:: encrypt(plaintext, padding) @@ -514,7 +520,7 @@ Key interfaces :param bytes plaintext: The plaintext to encrypt. :param padding: An instance of a - :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.AsymmetricPadding` provider. :return bytes: Encrypted data. diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 86a3a7e4..f58d324d 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -14,130 +14,14 @@ 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 --------------------- -.. class:: AsymmetricSignatureContext - - .. versionadded:: 0.2 - - .. method:: update(data) - - :param bytes data: The data you want to sign. - - .. method:: finalize() - - :return bytes signature: The signature. - - -.. class:: AsymmetricVerificationContext - - .. versionadded:: 0.2 - - .. method:: update(data) - - :param bytes data: The data you wish to verify using the signature. - - .. method:: verify() - - :raises cryptography.exceptions.InvalidSignature: If the signature does - not validate. - - -.. class:: AsymmetricPadding - - .. versionadded:: 0.2 +In 0.8 the asymmetric signature and verification interfaces were moved to the +:mod:`cryptography.hazmat.primitives.asymmetric` module. - .. attribute:: name +In 0.8 the asymmetric padding interface was moved to the +:mod:`cryptography.hazmat.primitives.asymmetric.padding` module. DSA ~~~ @@ -163,46 +47,8 @@ In 0.8 the EC key interfaces were moved to the Key derivation functions ------------------------ -.. class:: KeyDerivationFunction - - .. versionadded:: 0.2 - - .. method:: derive(key_material) - - :param bytes key_material: The input key material. Depending on what - key derivation function you are using this - could be either random bytes, or a user - supplied password. - :return: The new key. - :raises cryptography.exceptions.AlreadyFinalized: This is raised when - :meth:`derive` or - :meth:`verify` is - called more than - once. - - This generates and returns a new key from the supplied key material. - - .. method:: verify(key_material, expected_key) - - :param bytes key_material: The input key material. This is the same as - ``key_material`` in :meth:`derive`. - :param bytes expected_key: The expected result of deriving a new key, - this is the same as the return value of - :meth:`derive`. - :raises cryptography.exceptions.InvalidKey: This is raised when the - derived key does not match - the expected key. - :raises cryptography.exceptions.AlreadyFinalized: This is raised when - :meth:`derive` or - :meth:`verify` is - called more than - once. - - This checks whether deriving a new key from the supplied - ``key_material`` generates the same key as the ``expected_key``, and - raises an exception if they do not match. This can be used for - something like checking whether a user's password attempt matches the - stored derived key. +In 0.8 the key derivation function interface was moved to the +:mod:`cryptography.hazmat.primitives.kdf` module. `Message Authentication Code`_ diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 4a47159f..78d40315 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -3,7 +3,7 @@ Key derivation functions ======================== -.. currentmodule:: cryptography.hazmat.primitives.kdf +.. module:: cryptography.hazmat.primitives.kdf Key derivation functions derive bytes suitable for cryptographic operations from passwords or other data sources using a pseudo-random function (PRF). @@ -38,7 +38,7 @@ Different KDFs are suitable for different tasks such as: considered a better solution. This class conforms to the - :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` + :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction` interface. .. doctest:: @@ -324,6 +324,53 @@ Different KDFs are suitable for different tasks such as: ``key_material`` generates the same key as the ``expected_key``, and raises an exception if they do not match. +Interface +~~~~~~~~~ + +.. currentmodule:: cryptography.hazmat.primitives.kdf + +.. class:: KeyDerivationFunction + + .. versionadded:: 0.2 + + .. method:: derive(key_material) + + :param bytes key_material: The input key material. Depending on what + key derivation function you are using this + could be either random bytes, or a user + supplied password. + :return: The new key. + :raises cryptography.exceptions.AlreadyFinalized: This is raised when + :meth:`derive` or + :meth:`verify` is + called more than + once. + + This generates and returns a new key from the supplied key material. + + .. method:: verify(key_material, expected_key) + + :param bytes key_material: The input key material. This is the same as + ``key_material`` in :meth:`derive`. + :param bytes expected_key: The expected result of deriving a new key, + this is the same as the return value of + :meth:`derive`. + :raises cryptography.exceptions.InvalidKey: This is raised when the + derived key does not match + the expected key. + :raises cryptography.exceptions.AlreadyFinalized: This is raised when + :meth:`derive` or + :meth:`verify` is + called more than + once. + + This checks whether deriving a new key from the supplied + ``key_material`` generates the same key as the ``expected_key``, and + raises an exception if they do not match. This can be used for + something like checking whether a user's password attempt matches the + stored derived key. + + .. _`NIST SP 800-132`: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf .. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet .. _`PBKDF2`: https://en.wikipedia.org/wiki/PBKDF2 diff --git a/docs/hazmat/primitives/mac/cmac.rst b/docs/hazmat/primitives/mac/cmac.rst index 1ba1b3fa..e04a849f 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.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.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.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.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/padding.rst b/docs/hazmat/primitives/padding.rst index 0322f9d2..a60f5ac8 100644 --- a/docs/hazmat/primitives/padding.rst +++ b/docs/hazmat/primitives/padding.rst @@ -3,7 +3,7 @@ Padding ======= -.. currentmodule:: cryptography.hazmat.primitives.padding +.. module:: cryptography.hazmat.primitives.padding Padding is a way to take data that may or may not be a multiple of the block size for a cipher and extend it out so that it is. This is required for many @@ -44,18 +44,16 @@ multiple of the block size. .. method:: padder() :returns: A padding - :class:`~cryptography.hazmat.primitives.interfaces.PaddingContext` + :class:`~cryptography.hazmat.primitives.padding.PaddingContext` provider. .. method:: unpadder() :returns: An unpadding - :class:`~cryptography.hazmat.primitives.interfaces.PaddingContext` + :class:`~cryptography.hazmat.primitives.padding.PaddingContext` provider. -.. currentmodule:: cryptography.hazmat.primitives.interfaces - .. class:: PaddingContext When calling ``padder()`` or ``unpadder()`` the result will conform to the diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index b2ce376b..0f7e0377 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,13 +506,110 @@ 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 .. _`NIST SP-800-38D`: http://csrc.nist.gov/publications/nistpubs/800-38D/SP-800-38D.pdf -.. _`Communications Security Establishment`: http://www.cse-cst.gc.ca -.. _`encrypt`: https://ssd.eff.org/tech/encryption +.. _`Communications Security Establishment`: https://www.cse-cst.gc.ca +.. _`encrypt`: https://ssd.eff.org/en/module/what-encryption .. _`CRYPTREC`: http://www.cryptrec.go.jp/english/ -.. _`significant patterns in the output`: https://en.wikipedia.org/wiki/Cipher_block_chaining#Electronic_codebook_.28ECB.29 +.. _`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://www.openpgp.org |