diff options
Diffstat (limited to 'docs/hazmat')
| -rw-r--r-- | docs/hazmat/backends/commoncrypto.rst | 5 | ||||
| -rw-r--r-- | docs/hazmat/backends/index.rst | 4 | ||||
| -rw-r--r-- | docs/hazmat/backends/interfaces.rst | 18 | ||||
| -rw-r--r-- | docs/hazmat/backends/openssl.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/bindings/commoncrypto.rst | 6 | ||||
| -rw-r--r-- | docs/hazmat/bindings/index.rst | 2 | ||||
| -rw-r--r-- | docs/hazmat/bindings/openssl.rst | 6 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/dsa.rst | 68 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/index.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/padding.rst | 36 | ||||
| -rw-r--r-- | docs/hazmat/primitives/asymmetric/rsa.rst | 72 | ||||
| -rw-r--r-- | docs/hazmat/primitives/cryptographic-hashes.rst | 57 | ||||
| -rw-r--r-- | docs/hazmat/primitives/hmac.rst | 34 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 124 | ||||
| -rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 10 | ||||
| -rw-r--r-- | docs/hazmat/primitives/symmetric-encryption.rst | 188 | ||||
| -rw-r--r-- | docs/hazmat/primitives/twofactor.rst | 24 |
17 files changed, 510 insertions, 157 deletions
diff --git a/docs/hazmat/backends/commoncrypto.rst b/docs/hazmat/backends/commoncrypto.rst index 16a61337..77d6612c 100644 --- a/docs/hazmat/backends/commoncrypto.rst +++ b/docs/hazmat/backends/commoncrypto.rst @@ -1,9 +1,10 @@ .. hazmat:: -CommonCrypto Backend +CommonCrypto backend ==================== -The `CommonCrypto`_ C library provided by Apple on OS X and iOS. +The `CommonCrypto`_ C library provided by Apple on OS X and iOS. The CommonCrypto +backend is only supported on OS X versions 10.8 and above. .. currentmodule:: cryptography.hazmat.backends.commoncrypto.backend diff --git a/docs/hazmat/backends/index.rst b/docs/hazmat/backends/index.rst index 983a44e9..aec7a1e0 100644 --- a/docs/hazmat/backends/index.rst +++ b/docs/hazmat/backends/index.rst @@ -3,7 +3,7 @@ Backends ======== -Getting a Backend +Getting a backend ----------------- .. currentmodule:: cryptography.hazmat.backends @@ -24,7 +24,7 @@ the libraries we use in those backends changes. :class:`~interfaces.CipherBackend`, :class:`~interfaces.HashBackend`, and :class:`~interfaces.HMACBackend`. -Individual Backends +Individual backends ------------------- .. toctree:: diff --git a/docs/hazmat/backends/interfaces.rst b/docs/hazmat/backends/interfaces.rst index af19fbc6..c38f818f 100644 --- a/docs/hazmat/backends/interfaces.rst +++ b/docs/hazmat/backends/interfaces.rst @@ -1,6 +1,6 @@ .. hazmat:: -Backend Interfaces +Backend interfaces ================== .. currentmodule:: cryptography.hazmat.backends.interfaces @@ -249,6 +249,20 @@ A specific ``backend`` may provide one or more of these interfaces. :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + .. method:: mgf1_hash_supported(algorithm) + + Check if the specified ``algorithm`` is supported for use with + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + inside :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` + padding. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :returns: ``True`` if the specified ``algorithm`` is supported by this + backend, otherwise ``False``. + .. class:: OpenSSLSerializationBackend @@ -258,7 +272,7 @@ A specific ``backend`` may provide one or more of these interfaces. style key serialization. .. method:: load_openssl_pem_private_key(data, password) - + :param bytes data: PEM data to deserialize. :param bytes password: The password to use if this data is encrypted. diff --git a/docs/hazmat/backends/openssl.rst b/docs/hazmat/backends/openssl.rst index d6351c9c..fdfadf0b 100644 --- a/docs/hazmat/backends/openssl.rst +++ b/docs/hazmat/backends/openssl.rst @@ -1,9 +1,11 @@ .. hazmat:: -OpenSSL Backend +OpenSSL backend =============== -The `OpenSSL`_ C library. +The `OpenSSL`_ C library. Cryptography supports version ``0.9.8e`` (present in +Red Hat Enterprise Linux 5) and greater. Earlier versions may work but are +**not tested or supported**. .. data:: cryptography.hazmat.backends.openssl.backend @@ -32,7 +34,7 @@ The `OpenSSL`_ C library. This will activate the default OpenSSL CSPRNG. -OS Random Engine +OS random engine ---------------- OpenSSL uses a user-space CSPRNG that is seeded from system random ( @@ -56,7 +58,7 @@ When importing only the binding it is added to the engine list but **not activated**. -OS Random Sources +OS random sources ----------------- On OS X and FreeBSD ``/dev/urandom`` is an alias for ``/dev/random`` and diff --git a/docs/hazmat/bindings/commoncrypto.rst b/docs/hazmat/bindings/commoncrypto.rst index 50dbe69a..9484cfa1 100644 --- a/docs/hazmat/bindings/commoncrypto.rst +++ b/docs/hazmat/bindings/commoncrypto.rst @@ -1,14 +1,14 @@ .. hazmat:: -CommonCrypto Binding +CommonCrypto binding ==================== .. currentmodule:: cryptography.hazmat.bindings.commoncrypto.binding .. versionadded:: 0.2 -These are `CFFI`_ bindings to the `CommonCrypto`_ C library. It is available on -Mac OS X. +These are `CFFI`_ bindings to the `CommonCrypto`_ C library. It is only +available on Mac OS X versions 10.8 and above. .. class:: cryptography.hazmat.bindings.commoncrypto.binding.Binding() diff --git a/docs/hazmat/bindings/index.rst b/docs/hazmat/bindings/index.rst index caab8d6a..ccd36e3e 100644 --- a/docs/hazmat/bindings/index.rst +++ b/docs/hazmat/bindings/index.rst @@ -13,7 +13,7 @@ Using these functions directly is likely to require you to be careful in managing memory allocation, locking and other resources. -Individual Bindings +Individual bindings ------------------- .. toctree:: diff --git a/docs/hazmat/bindings/openssl.rst b/docs/hazmat/bindings/openssl.rst index 557f8c4d..a6d1c484 100644 --- a/docs/hazmat/bindings/openssl.rst +++ b/docs/hazmat/bindings/openssl.rst @@ -1,11 +1,13 @@ .. hazmat:: -OpenSSL Binding +OpenSSL binding =============== .. currentmodule:: cryptography.hazmat.bindings.openssl.binding -These are `CFFI`_ bindings to the `OpenSSL`_ C library. +These are `CFFI`_ bindings to the `OpenSSL`_ C library. Cryptography supports +version ``0.9.8e`` (present in Red Hat Enterprise Linux 5) and greater. Earlier +versions may work but are **not tested or supported**. .. class:: cryptography.hazmat.bindings.openssl.binding.Binding() diff --git a/docs/hazmat/primitives/asymmetric/dsa.rst b/docs/hazmat/primitives/asymmetric/dsa.rst new file mode 100644 index 00000000..69e8d58e --- /dev/null +++ b/docs/hazmat/primitives/asymmetric/dsa.rst @@ -0,0 +1,68 @@ +.. hazmat:: + +DSA +=== + +.. currentmodule:: cryptography.hazmat.primitives.asymmetric.dsa + +`DSA`_ is a `public-key`_ algorithm for signing messages. + +.. class:: DSAParameters(modulus, subgroup_order, generator) + + .. versionadded:: 0.4 + + DSA Parameters are required for generating a DSA private key. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + +.. class:: DSAPrivateKey(modulus, subgroup_order, generator, x, y) + + .. versionadded:: 0.4 + + A DSA private key is required for signing messages. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAPrivateKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``, or ``generator`` do + not match the bounds specified in `FIPS 186-4`_. + + +.. class:: DSAPublicKey(modulus, subgroup_order, generator, y) + + .. versionadded:: 0.4 + + A DSA public key is required for verifying messages. + + Normally you do not need to directly construct public keys because you'll + be loading them from a file, generating them automatically or receiving + them from a 3rd party. + + This class conforms to the + :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + interface. + + :raises TypeError: This is raised when the arguments are not all integers. + + :raises ValueError: This is raised when the values of ``modulus``, + ``subgroup_order``,``generator``, or ``y`` + do not match the bounds specified in `FIPS 186-4`_. + + +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm +.. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography +.. _`FIPS 186-4`: http://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.186-4.pdf + diff --git a/docs/hazmat/primitives/asymmetric/index.rst b/docs/hazmat/primitives/asymmetric/index.rst index 10319fad..ca048d11 100644 --- a/docs/hazmat/primitives/asymmetric/index.rst +++ b/docs/hazmat/primitives/asymmetric/index.rst @@ -1,10 +1,11 @@ .. hazmat:: -Asymmetric Algorithms +Asymmetric algorithms ===================== .. toctree:: :maxdepth: 1 + dsa rsa padding diff --git a/docs/hazmat/primitives/asymmetric/padding.rst b/docs/hazmat/primitives/asymmetric/padding.rst index 7aec3bd3..2a5de3c7 100644 --- a/docs/hazmat/primitives/asymmetric/padding.rst +++ b/docs/hazmat/primitives/asymmetric/padding.rst @@ -10,6 +10,17 @@ Padding correct padding signatures can be forged, messages decrypted, and private keys compromised. +.. class:: PSS(mgf) + + .. versionadded:: 0.3 + + PSS (Probabilistic Signature Scheme) is a signature scheme defined in + :rfc:`3447`. It is more complex than PKCS1 but possesses a `security proof`_. + This is the `recommended padding algorithm`_ for RSA signatures. + + :param mgf: A mask generation function object. At this time the only + supported MGF is :class:`MGF1`. + .. class:: PKCS1v15() .. versionadded:: 0.3 @@ -17,4 +28,29 @@ Padding PKCS1 v1.5 (also known as simply PKCS1) is a simple padding scheme developed for use with RSA keys. It is defined in :rfc:`3447`. +Mask generation functions +~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: MGF1(algorithm, salt_length) + + .. versionadded:: 0.3 + + MGF1 (Mask Generation Function 1) is used as the mask generation function + in :class:`PSS` padding. It takes a hash algorithm and a salt length. + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param int salt_length: The length of the salt. It is recommended that this + be set to ``MGF1.MAX_LENGTH``. + + .. attribute:: MAX_LENGTH + + Pass this attribute to ``salt_length`` to get the maximum salt length + available. + + .. _`Padding is critical`: http://rdist.root.org/2009/10/06/why-rsa-encryption-padding-is-critical/ +.. _`security proof`: http://eprint.iacr.org/2001/062.pdf +.. _`recommended padding algorithm`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 7943981e..182e35d2 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -50,6 +50,11 @@ RSA provider. :return: A new instance of ``RSAPrivateKey``. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` + + .. method:: signer(padding, algorithm, backend) .. versionadded:: 0.3 @@ -67,7 +72,12 @@ RSA ... backend=default_backend() ... ) >>> signer = private_key.signer( - ... padding.PKCS1v15(), + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), ... hashes.SHA256(), ... default_backend() ... ) @@ -90,6 +100,24 @@ RSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricSignatureContext` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if + the backend does not support the chosen hash or padding algorithm. + If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` + with the + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + mask generation function it may also refer to the ``MGF1`` hash + algorithm. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when the chosen hash algorithm is + too large for the key size. + .. class:: RSAPublicKey(public_exponent, modulus) @@ -128,12 +156,31 @@ RSA ... key_size=2048, ... backend=default_backend() ... ) - >>> signer = private_key.signer(padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> signer = private_key.signer( + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> data= b"this is some data I'd like to sign" >>> signer.update(data) >>> signature = signer.finalize() >>> public_key = private_key.public_key() - >>> verifier = public_key.verifier(signature, padding.PKCS1v15(), hashes.SHA256(), default_backend()) + >>> verifier = public_key.verifier( + ... signature, + ... padding.PSS( + ... mgf=padding.MGF1( + ... algorithm=hashes.SHA256(), + ... salt_length=padding.MGF1.MAX_LENGTH + ... ) + ... ), + ... hashes.SHA256(), + ... default_backend() + ... ) >>> verifier.update(data) >>> verifier.verify() @@ -154,6 +201,25 @@ RSA :returns: :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricVerificationContext` + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if + the provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.RSABackend` or if + the backend does not support the chosen hash or padding algorithm. + If the padding is + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` + with the + :class:`~cryptography.hazmat.primitives.asymmetric.padding.MGF1` + mask generation function it may also refer to the ``MGF1`` hash + algorithm. + + :raises TypeError: This is raised when the padding is not an + :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` + provider. + + :raises ValueError: This is raised when the chosen hash algorithm is + too large for the key size. + + .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`public-key`: https://en.wikipedia.org/wiki/Public-key_cryptography .. _`use 65537`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html diff --git a/docs/hazmat/primitives/cryptographic-hashes.rst b/docs/hazmat/primitives/cryptographic-hashes.rst index 6c56acad..773d97f6 100644 --- a/docs/hazmat/primitives/cryptographic-hashes.rst +++ b/docs/hazmat/primitives/cryptographic-hashes.rst @@ -1,6 +1,6 @@ .. hazmat:: -Message Digests +Message digests =============== .. currentmodule:: cryptography.hazmat.primitives.hashes @@ -29,7 +29,8 @@ Message Digests 'l\xa1=R\xcap\xc8\x83\xe0\xf0\xbb\x10\x1eBZ\x89\xe8bM\xe5\x1d\xb2\xd29%\x93\xafj\x84\x11\x80\x90' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be + raised. Keep in mind that attacks against cryptographic hashes only get stronger with time, and that often algorithms that were once thought to be strong, @@ -45,28 +46,32 @@ Message Digests :class:`~cryptography.hazmat.backends.interfaces.HashBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HashBackend` + .. method:: update(data) - :param bytes data: The bytes you wish to hash. - :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + :param bytes data: The bytes to be hashed. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`. .. method:: copy() - Copy this :class:`Hash` instance, usually so that we may call - :meth:`finalize` and get an intermediate digest value while we continue - to call :meth:`update` on the original. + Copy this :class:`Hash` instance, usually so that you may call + :meth:`finalize` to get an intermediate digest value while we continue + to call :meth:`update` on the original instance. :return: A new instance of :class:`Hash` that can be updated - and finalized independently of the original instance. - :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize` + and finalized independently of the original instance. + :raises cryptography.exceptions.AlreadyFinalized: See :meth:`finalize`. .. method:: finalize() Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used and - :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise an + :class:`~cryptography.exceptions.AlreadyFinalized` exception. :return bytes: The message digest as bytes. @@ -83,31 +88,31 @@ SHA-1 .. class:: SHA1() - SHA-1 is a cryptographic hash function standardized by NIST. It has a + SHA-1 is a cryptographic hash function standardized by NIST. It produces an 160-bit message digest. -SHA-2 Family +SHA-2 family ~~~~~~~~~~~~ .. class:: SHA224() - SHA-224 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 224-bit message digest. + SHA-224 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 224-bit message digest. .. class:: SHA256() - SHA-256 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 256-bit message digest. + SHA-256 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 256-bit message digest. .. class:: SHA384() - SHA-384 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 384-bit message digest. + SHA-384 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 384-bit message digest. .. class:: SHA512() - SHA-512 is a cryptographic hash function from the SHA-2 family and - standardized by NIST. It has a 512-bit message digest. + SHA-512 is a cryptographic hash function from the SHA-2 family and is + standardized by NIST. It produces a 512-bit message digest. RIPEMD160 ~~~~~~~~~ @@ -115,7 +120,7 @@ RIPEMD160 .. class:: RIPEMD160() RIPEMD160 is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It has a 160-bit message digest. + 10118-3:2004. It produces a 160-bit message digest. Whirlpool ~~~~~~~~~ @@ -123,7 +128,7 @@ Whirlpool .. class:: Whirlpool() Whirlpool is a cryptographic hash function that is part of ISO/IEC - 10118-3:2004. It has a 512-bit message digest. + 10118-3:2004. It produces a 512-bit message digest. MD5 ~~~ @@ -136,8 +141,8 @@ MD5 .. class:: MD5() - MD5 is a deprecated cryptographic hash function. It has a 128-bit message - digest and has practical known collision attacks. + MD5 is a deprecated cryptographic hash function. It produces a 128-bit + message digest and has practical known collision attacks. .. _`Lifetimes of cryptographic hash functions`: http://valerieaurora.org/hash.html diff --git a/docs/hazmat/primitives/hmac.rst b/docs/hazmat/primitives/hmac.rst index 0118be78..11b10735 100644 --- a/docs/hazmat/primitives/hmac.rst +++ b/docs/hazmat/primitives/hmac.rst @@ -1,6 +1,6 @@ .. hazmat:: -Hash-based Message Authentication Codes +Hash-based message authentication codes ======================================= .. currentmodule:: cryptography.hazmat.primitives.hmac @@ -12,13 +12,13 @@ Hash-based Message Authentication Codes Hash-based message authentication codes (or HMACs) are a tool for calculating message authentication codes using a cryptographic hash function coupled with a -secret key. You can use an HMAC to verify integrity as well as authenticate a -message. +secret key. You can use an HMAC to verify both the integrity and authenticity +of a message. .. class:: HMAC(key, algorithm, backend) - HMAC objects take a ``key`` and a provider of - :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`. + HMAC objects take a ``key`` and a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider. The ``key`` should be randomly generated bytes and is recommended to be equal in length to the ``digest_size`` of the hash function chosen. You must keep the ``key`` secret. @@ -35,7 +35,8 @@ message. '#F\xdaI\x8b"e\xc4\xf1\xbb\x9a\x8fc\xff\xf5\xdex.\xbc\xcd/+\x8a\x86\x1d\x84\'\xc3\xa6\x1d\xd8J' If the backend doesn't support the requested ``algorithm`` an - :class:`~cryptography.exceptions.UnsupportedAlgorithm` will be raised. + :class:`~cryptography.exceptions.UnsupportedAlgorithm` exception will be + raised. To check that a given signature is correct use the :meth:`verify` method. You will receive an exception if the signature is wrong: @@ -47,15 +48,19 @@ message. ... cryptography.exceptions.InvalidSignature: Signature did not match digest. - :param key: Secret key as ``bytes``. - :param algorithm: A + :param bytes key: Secret key as ``bytes``. + :param algorithm: An :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` provider such as those described in :ref:`Cryptographic Hashes <cryptographic-hash-algorithms>`. - :param backend: A + :param backend: An :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + .. method:: update(msg) :param bytes msg: The bytes to hash and authenticate. @@ -64,8 +69,8 @@ message. .. method:: copy() Copy this :class:`HMAC` instance, usually so that we may call - :meth:`finalize` and get an intermediate digest value while we continue - to call :meth:`update` on the original. + :meth:`finalize` to get an intermediate digest value while we continue + to call :meth:`update` on the original instance. :return: A new instance of :class:`HMAC` that can be updated and finalized independently of the original instance. @@ -86,9 +91,10 @@ message. Finalize the current context and return the message digest as bytes. - Once ``finalize`` is called this object can no longer be used and - :meth:`update`, :meth:`copy`, and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + After ``finalize`` has been called this object can no longer be used + and :meth:`update`, :meth:`copy`, :meth:`verify` and :meth:`finalize` + will raise an :class:`~cryptography.exceptions.AlreadyFinalized` + exception. :return bytes: The message digest as bytes. :raises cryptography.exceptions.AlreadyFinalized: diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 15ad1d1b..9a1f3307 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -12,7 +12,7 @@ to document argument and return types. .. _`Abstract Base Classes`: http://docs.python.org/3.2/library/abc.html -Symmetric Ciphers +Symmetric ciphers ~~~~~~~~~~~~~~~~~ .. currentmodule:: cryptography.hazmat.primitives.interfaces @@ -47,7 +47,7 @@ Symmetric Ciphers The number of bits in a block. -Cipher Modes +Cipher modes ------------ Interfaces used by the symmetric cipher modes described in @@ -103,7 +103,7 @@ Interfaces used by the symmetric cipher modes described in Exact requirements of the nonce are described by the documentation of individual modes. -Asymmetric Interfaces +Asymmetric interfaces ~~~~~~~~~~~~~~~~~~~~~ .. class:: RSAPrivateKey @@ -231,6 +231,119 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +.. class:: DSAParameters + + .. versionadded:: 0.3 + + `DSA`_ parameters. + + .. attribute:: modulus + + :type: int + + The prime modulus that is used in generating the DSA key pair and used + in the DSA signing and verification processes. + + .. attribute:: subgroup_order + + :type: int + + The subgroup order that is used in generating the DSA key pair + by the generator and used in the DSA signing and verification + processes. + + .. attribute:: generator + + :type: int + + The generator that is used in generating the DSA key pair and used + in the DSA signing and verification processes. + + .. attribute:: p + + :type: int + + The prime modulus that is used in generating the DSA key pair and used + in the DSA signing and verification processes. Alias for :attr:`modulus`. + + .. attribute:: q + + :type: int + + The subgroup order that is used in generating the DSA key pair + by the generator and used in the DSA signing and verification + processes. Alias for :attr:`subgroup_order`. + + .. attribute:: g + + :type: int + + The generator that is used in generating the DSA key pair and used + in the DSA signing and verification processes. Alias for :attr:`generator`. + + +.. class:: DSAPrivateKey + + .. versionadded:: 0.3 + + A `DSA`_ private key. + + .. method:: public_key() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAPublicKey` + + An DSA public key object corresponding to the values of the private key. + + .. method:: parameters() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + + The DSAParameters object associated with this private key. + + .. attribute:: key_size + + :type: int + + The bit length of the modulus. + + .. attribute:: x + + :type: int + + The private key. + + .. attribute:: y + + :type: int + + The public key. + + +.. class:: DSAPublicKey + + .. versionadded:: 0.3 + + A `DSA`_ public key. + + .. attribute:: key_size + + :type: int + + The bit length of the modulus. + + .. method:: parameters() + + :return: :class:`~cryptography.hazmat.primitives.interfaces.DSAParameters` + + The DSAParameters object associated with this public key. + + .. attribute:: y + + :type: int + + The public key. + + .. class:: AsymmetricSignatureContext .. versionadded:: 0.2 @@ -264,7 +377,7 @@ Asymmetric Interfaces .. attribute:: name -Hash Algorithms +Hash algorithms ~~~~~~~~~~~~~~~ .. class:: HashAlgorithm @@ -289,7 +402,7 @@ Hash Algorithms The internal block size of the hash algorithm in bytes. -Key Derivation Functions +Key derivation functions ~~~~~~~~~~~~~~~~~~~~~~~~ .. class:: KeyDerivationFunction @@ -335,3 +448,4 @@ Key Derivation Functions .. _`RSA`: https://en.wikipedia.org/wiki/RSA_(cryptosystem) .. _`Chinese remainder theorem`: https://en.wikipedia.org/wiki/Chinese_remainder_theorem +.. _`DSA`: https://en.wikipedia.org/wiki/Digital_Signature_Algorithm diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 851dbb0b..269f949d 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -1,6 +1,6 @@ .. hazmat:: -Key Derivation Functions +Key derivation functions ======================== .. currentmodule:: cryptography.hazmat.primitives.kdf @@ -84,6 +84,10 @@ Different KDFs are suitable for different tasks such as: :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.PBKDF2HMACBackend` + .. method:: derive(key_material) :param bytes key_material: The input key material. For PBKDF2 this @@ -183,6 +187,10 @@ Different KDFs are suitable for different tasks such as: :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + .. method:: derive(key_material) :param bytes key_material: The input key material. diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 2306c5b7..28de611e 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -1,7 +1,7 @@ .. hazmat:: /fernet -Symmetric Encryption +Symmetric encryption ==================== .. currentmodule:: cryptography.hazmat.primitives.ciphers @@ -13,23 +13,25 @@ Symmetric Encryption iv = binascii.unhexlify(b"0" * 32) -Symmetric encryption is a way to encrypt (hide the plaintext value) material -where the sender and receiver both use the same key. Note that symmetric -encryption is **not** sufficient for most applications, because it only -provides secrecy (an attacker can't see the message) but not authenticity (an -attacker can create bogus messages and force the application to decrypt them). +Symmetric encryption is a way to `encrypt`_ or hide the contents of material +where the sender and receiver both use the same secret key. Note that symmetric +encryption is **not** sufficient for most applications because it only +provides secrecy but not authenticity. That means an attacker can't see the +message but an attacker can create bogus messages and force the application to +decrypt them. + For this reason it is *strongly* recommended to combine encryption with a message authentication code, such as :doc:`HMAC </hazmat/primitives/hmac>`, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. .. class:: Cipher(algorithm, mode, backend) - Cipher objects combine an algorithm (such as - :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES`) with a - mode (such as + Cipher objects combine an algorithm such as + :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` with a + mode like :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` or - :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`). A simple - example of encrypting (and then decrypting) content with AES is: + :class:`~cryptography.hazmat.primitives.ciphers.modes.CTR`. A simple + example of encrypting and then decrypting content with AES is: .. doctest:: @@ -54,6 +56,10 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` + .. method:: encryptor() :return: An encrypting @@ -62,7 +68,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. If the backend doesn't support the requested combination of ``cipher`` and ``mode`` an :class:`~cryptography.exceptions.UnsupportedAlgorithm` - will be raised. + exception will be raised. .. method:: decryptor() @@ -72,7 +78,7 @@ an "encrypt-then-MAC" formulation as `described by Colin Percival`_. If the backend doesn't support the requested combination of ``cipher`` and ``mode`` an :class:`cryptography.exceptions.UnsupportedAlgorithm` - will be raised. + exception will be raised. .. _symmetric-encryption-algorithms: @@ -87,17 +93,17 @@ Algorithms AES is both fast, and cryptographically strong. It is a good default choice for encryption. - :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``128``, + ``192``, or ``256`` bits long. .. class:: Camellia(key) - Camellia is a block cipher approved for use by CRYPTREC and ISO/IEC. - It is considered to have comparable security and performance to AES, but + Camellia is a block cipher approved for use by `CRYPTREC`_ and ISO/IEC. + It is considered to have comparable security and performance to AES but is not as widely studied or deployed. - :param bytes key: The secret key, either ``128``, ``192``, or ``256`` bits. - This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``128``, + ``192``, or ``256`` bits long. .. class:: TripleDES(key) @@ -107,12 +113,11 @@ Algorithms Nonetheless, Triples DES is not recommended for new applications because it is incredibly slow; old applications should consider moving away from it. - :param bytes key: The secret key, either ``64``, ``128``, or ``192`` bits - (note that DES functionally uses ``56``, ``112``, or ``168`` bits of - the key, there is a parity byte in each component of the key), in some - materials these are referred to as being up to three separate keys - (each ``56`` bits long), they can simply be concatenated to produce the - full key. This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``64``, + ``128``, or ``192`` bits long. DES only uses ``56``, ``112``, or ``168`` + bits of the key as there is a parity byte in each component of the key. + Some writing refers to there being up to three separate keys that are each + ``56`` bits long, they can simply be concatenated to produce the full key. .. class:: CAST5(key) @@ -122,10 +127,10 @@ Algorithms Canadian government by the `Communications Security Establishment`_. It is a variable key length cipher and supports keys from 40-128 bits in length. - :param bytes key: The secret key, 40-128 bits in length (in increments of - 8). This must be kept secret. + :param bytes key: The secret key, This must be kept secret. 40 to 128 bits + in length in increments of 8 bits. -Weak Ciphers +Weak ciphers ------------ .. warning:: @@ -138,10 +143,10 @@ Weak Ciphers Blowfish is a block cipher developed by Bruce Schneier. It is known to be susceptible to attacks when using weak keys. The author has recommended - that users of Blowfish move to newer algorithms, such as :class:`AES`. + that users of Blowfish move to newer algorithms such as :class:`AES`. - :param bytes key: The secret key, 32-448 bits in length (in increments of - 8). This must be kept secret. + :param bytes key: The secret key. This must be kept secret. 32 to 448 bits + in length in increments of 8 bits. .. class:: ARC4(key) @@ -149,8 +154,8 @@ Weak Ciphers initial stream output. Its use is strongly discouraged. ARC4 does not use mode constructions. - :param bytes key: The secret key, ``40``, ``56``, ``64``, ``80``, ``128``, - ``192``, or ``256`` bits in length. This must be kept secret. + :param bytes key: The secret key. This must be kept secret. Either ``40``, + ``56``, ``64``, ``80``, ``128``, ``192``, or ``256`` bits in length. .. doctest:: @@ -164,6 +169,16 @@ Weak Ciphers >>> decryptor.update(ct) 'a secret message' +.. class:: IDEA(key) + + IDEA (`International Data Encryption Algorithm`_) is a block cipher created + in 1991. It is an optional component of the `OpenPGP`_ standard. This cipher + is susceptible to attacks when using weak keys. It is recommended that you + do not use this cipher for new applications. + + :param bytes key: The secret key This must be kept secret. ``128`` bits in + length. + .. _symmetric-encryption-modes: @@ -174,16 +189,16 @@ Modes .. class:: CBC(initialization_vector) - CBC (Cipher block chaining) is a mode of operation for block ciphers. It is + CBC (Cipher Block Chaining) is a mode of operation for block ciphers. It is considered cryptographically strong. **Padding is required when using this mode.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). Must - be the same number of bytes as the ``block_size`` of the cipher. Each - time something is encrypted a new ``initialization_vector`` should be - generated. Do not reuse an ``initialization_vector`` with a given + to be kept secret and they can be included in a transmitted message. + Must be the same number of bytes as the ``block_size`` of the cipher. + Each time something is encrypted a new ``initialization_vector`` should + be generated. Do not reuse an ``initialization_vector`` with a given ``key``, and particularly do not use a constant ``initialization_vector``. @@ -223,7 +238,7 @@ Modes compromises the security of every message encrypted with that key. Must be the same number of bytes as the ``block_size`` of the cipher with a given key. The nonce does not need to be kept secret and may be - included alongside the ciphertext. + included with the ciphertext. .. class:: OFB(initialization_vector) @@ -233,9 +248,9 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). Must - be the same number of bytes as the ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with a given ``key``. + to be kept secret and they can be included in a transmitted message. + Must be the same number of bytes as the ``block_size`` of the cipher. + Do not reuse an ``initialization_vector`` with a given ``key``. .. class:: CFB(initialization_vector) @@ -245,38 +260,38 @@ Modes **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). Must - be the same number of bytes as the ``block_size`` of the cipher. Do not - reuse an ``initialization_vector`` with a given ``key``. + to be kept secret and they can be included in a transmitted message. + Must be the same number of bytes as the ``block_size`` of the cipher. + Do not reuse an ``initialization_vector`` with a given ``key``. .. class:: GCM(initialization_vector, tag=None) .. danger:: - When using this mode you MUST not use the decrypted data until + When using this mode you **must** not use the decrypted data until :meth:`~cryptography.hazmat.primitives.interfaces.CipherContext.finalize` - has been called. GCM provides NO guarantees of ciphertext integrity + has been called. GCM provides **no** guarantees of ciphertext integrity until decryption is complete. GCM (Galois Counter Mode) is a mode of operation for block ciphers. An AEAD (authenticated encryption with additional data) mode is a type of - block cipher mode that encrypts the message as well as authenticating it - (and optionally additional data that is not encrypted) simultaneously. - Additional means of verifying integrity (like - :doc:`HMAC </hazmat/primitives/hmac>`) are not necessary. + block cipher mode that simultaneously encrypts the message as well as + authenticating it. Additional unencrypted data may also be authenticated. + Additional means of verifying integrity such as + :doc:`HMAC </hazmat/primitives/hmac>` are not necessary. **This mode does not require padding.** :param bytes initialization_vector: Must be random bytes. They do not need - to be kept secret (they can be included in a transmitted message). NIST - `recommends 96-bit IV length`_ for performance critical situations, but - it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an + to be kept secret and they can be included in a transmitted message. + NIST `recommends a 96-bit IV length`_ for performance critical + situations but it can be up to 2\ :sup:`64` - 1 bits. Do not reuse an ``initialization_vector`` with a given ``key``. .. note:: - Cryptography will emit a 128-bit tag when finalizing encryption. - You can shorten a tag by truncating it to the desired length, but this + Cryptography will generate a 128-bit tag when finalizing encryption. + You can shorten a tag by truncating it to the desired length but this is **not recommended** as it lowers the security margins of the authentication (`NIST SP-800-38D`_ recommends 96-bits or greater). If you must shorten the tag the minimum allowed length is 4 bytes @@ -298,8 +313,8 @@ Modes # Generate a random 96-bit IV. iv = os.urandom(12) - # Construct a AES-GCM Cipher object with the given and our randomly - # generated IV. + # Construct a AES-GCM Cipher object with the given key and a + # randomly generated IV. encryptor = Cipher( algorithms.AES(key), modes.GCM(iv), @@ -357,7 +372,7 @@ Modes a secret message! -Insecure Modes +Insecure modes -------------- .. warning:: @@ -371,7 +386,7 @@ Insecure Modes ECB (Electronic Code Book) is the simplest mode of operation for block ciphers. Each block of data is encrypted in the same way. This means identical plaintext blocks will always result in identical ciphertext - blocks, and thus result in information leakage + blocks, which can leave `significant patterns in the output`_. **Padding is required when using this mode.** @@ -386,12 +401,13 @@ Interfaces context. Once that is done call ``finalize()`` to finish the operation and obtain the remainder of the data. - Block ciphers require that plaintext or ciphertext always be a multiple of - their block size, because of that **padding** is sometimes required to make - a message the correct size. ``CipherContext`` will not automatically apply - any padding; you'll need to add your own. For block ciphers the recommended - padding is :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you - are using a stream cipher mode (such as + Block ciphers require that the plaintext or ciphertext always be a multiple + of their block size. Because of that **padding** is sometimes required to + make a message the correct size. ``CipherContext`` will not automatically + apply any padding; you'll need to add your own. For block ciphers the + recommended padding is + :class:`cryptography.hazmat.primitives.padding.PKCS7`. If you are using a + stream cipher mode (such as :class:`cryptography.hazmat.primitives.modes.CTR`) you don't have to worry about this. @@ -404,31 +420,31 @@ Interfaces When the ``Cipher`` was constructed in a mode that turns it into a stream cipher (e.g. :class:`cryptography.hazmat.primitives.ciphers.modes.CTR`), this will - return bytes immediately, however in other modes it will return chunks, + return bytes immediately, however in other modes it will return chunks whose size is determined by the cipher's block size. .. method:: finalize() :return bytes: Returns the remainder of the data. :raises ValueError: This is raised when the data provided isn't - correctly padded to be a multiple of the algorithm's block size. + a multiple of the algorithm's block size. Once ``finalize`` is called this object can no longer be used and - :meth:`update` and :meth:`finalize` will raise - :class:`~cryptography.exceptions.AlreadyFinalized`. + :meth:`update` and :meth:`finalize` will raise an + :class:`~cryptography.exceptions.AlreadyFinalized` exception. .. class:: AEADCipherContext - When calling ``encryptor()`` or ``decryptor()`` on a ``Cipher`` object + When calling ``encryptor`` or ``decryptor`` on a ``Cipher`` object with an AEAD mode (e.g. :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) the result will conform to the ``AEADCipherContext`` and ``CipherContext`` interfaces. If it is an encryption context it will additionally be an - ``AEADEncryptionContext`` interface. ``AEADCipherContext`` contains an - additional method ``authenticate_additional_data`` for adding additional - authenticated but unencrypted data (see note below). You should call this - before calls to ``update``. When you are done call ``finalize()`` to finish - the operation. + ``AEADEncryptionContext`` provider. ``AEADCipherContext`` contains an + additional method :meth:`authenticate_additional_data` for adding + additional authenticated but unencrypted data (see note below). You should + call this before calls to ``update``. When you are done call `finalize`` + to finish the operation. .. note:: @@ -444,12 +460,13 @@ Interfaces .. class:: AEADEncryptionContext - When creating an encryption context using ``encryptor()`` on a ``Cipher`` - object with an AEAD mode (e.g. - :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM`) you will receive - a return object conforming to the ``AEADEncryptionContext`` interface (as - well as ``AEADCipherContext``). This interface provides one additional - attribute ``tag``. ``tag`` can only be obtained after ``finalize()``. + When creating an encryption context using ``encryptor`` on a ``Cipher`` + object with an AEAD mode such as + :class:`~cryptography.hazmat.primitives.ciphers.modes.GCM` an object + conforming to both the ``AEADEncryptionContext`` and ``AEADCipherContext`` + interfaces will be returned. This interface provides one + additional attribute ``tag``. ``tag`` can only be obtained after + ``finalize`` has been called. .. attribute:: tag @@ -459,6 +476,11 @@ Interfaces .. _`described by Colin Percival`: http://www.daemonology.net/blog/2009-06-11-cryptographic-right-answers.html -.. _`recommends 96-bit IV length`: http://csrc.nist.gov/groups/ST/toolkit/BCM/documents/proposedmodes/gcm/gcm-spec.pdf +.. _`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 +.. _`CRYPTREC`: http://www.cryptrec.go.jp/english/ +.. _`significant patterns in the output`: http://en.wikipedia.org/wiki/Cipher_block_chaining#Electronic_codebook_.28ECB.29 +.. _`International Data Encryption Algorithm`: https://en.wikipedia.org/wiki/International_Data_Encryption_Algorithm +.. _`OpenPGP`: http://www.openpgp.org diff --git a/docs/hazmat/primitives/twofactor.rst b/docs/hazmat/primitives/twofactor.rst index 3df1a147..f19cf0e6 100644 --- a/docs/hazmat/primitives/twofactor.rst +++ b/docs/hazmat/primitives/twofactor.rst @@ -1,6 +1,6 @@ .. hazmat:: -Two-factor Authentication +Two-factor authentication ========================= .. currentmodule:: cryptography.hazmat.primitives.twofactor @@ -47,10 +47,14 @@ codes (HMAC). provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` - is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :raises TypeError: This is raised if the provided ``algorithm`` is not + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or - :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the + ``length`` parameter is not an integer. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` .. method:: generate(counter) @@ -75,7 +79,7 @@ locks out the account for a period of time after a number of failed attempts. The number of allowed attempts should be as low as possible while still ensuring that usability is not significantly impacted. -Re-synchronization of the Counter +Re-synchronization of the counter ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The server's counter value should only be incremented on a successful HOTP @@ -142,10 +146,14 @@ similar to the following code. provider. :raises ValueError: This is raised if the provided ``key`` is shorter than 128 bits or if the ``length`` parameter is not 6, 7 or 8. - :raises UnsupportedAlgorithm: This is raised if the provided ``algorithm`` - is not :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, + :raises TypeError: This is raised if the provided ``algorithm`` is not + :class:`~cryptography.hazmat.primitives.hashes.SHA1()`, :class:`~cryptography.hazmat.primitives.hashes.SHA256()` or - :class:`~cryptography.hazmat.primitives.hashes.SHA512()`. + :class:`~cryptography.hazmat.primitives.hashes.SHA512()` or if the + ``length`` parameter is not an integer. + :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the + provided ``backend`` does not implement + :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` .. method:: generate(time) |