From 9d72f12dcb28191f87fde9740899a39060e14495 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Tue, 6 May 2014 20:27:51 +0800 Subject: Added documentation --- .../hazmat/primitives/key-derivation-functions.rst | 86 ++++++++++++++++++++++ 1 file changed, 86 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 269f949d..9b76bf64 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -219,6 +219,92 @@ 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. + +.. class:: HKDFExpandOnly(algorithm, length, info, backend) + + .. versionadded:: 0.5 + + HKDF consists of two stages, extract and expand. This class exposes an + expand only version of HKDF that is suitable when the key material is + already cryptographically strong. + + .. warning:: + + HKDFExpandOnly should only be used if the key material is + cryptographically strong. You should use + :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF` if + you are unsure. + + .. doctest:: + + >>> import os + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpandOnly + >>> from cryptography.hazmat.backends import default_backend + >>> backend = default_backend() + >>> info = b"hkdf-example" + >>> key_material = os.urandom(16) + >>> hkdf = HKDFExpandOnly( + ... algorithm=hashes.SHA256(), + ... length=32, + ... info=info, + ... backend=backend + ... ) + >>> key = hkdf.derive(key_material) + >>> hkdf = HKDFExpandOnly( + ... algorithm=hashes.SHA256(), + ... length=32, + ... info=info, + ... backend=backend + ... ) + >>> hkdf.verify(key_material, key) + + :param algorithm: An instance of a + :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` + provider. + + :param int length: The desired length of the derived key. Maximum is + ``255 * (algorithm.digest_size // 8)``. + + :param bytes info: Application specific context information. If ``None`` + is explicitly passed an empty byte string will be used. + + :param backend: A + :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. + :return bytes: The derived key. + + Derives a new key from the input key material by performing both the + extract and expand operations. + + .. method:: verify(key_material, expected_key) + + :param key_material bytes: The input key material. This is the same as + ``key_material`` in :meth:`derive`. + :param expected_key bytes: 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. + .. _`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 -- cgit v1.2.3 From c0ce911b4e971f3090d406cb88dea532647eeac6 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Wed, 7 May 2014 16:22:09 +0800 Subject: Renamed HKDFExpandOnly to HKDFExpand --- docs/hazmat/primitives/key-derivation-functions.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 9b76bf64..11fbd4e0 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -220,7 +220,7 @@ Different KDFs are suitable for different tasks such as: raises an exception if they do not match. -.. class:: HKDFExpandOnly(algorithm, length, info, backend) +.. class:: HKDFExpand(algorithm, length, info, backend) .. versionadded:: 0.5 @@ -230,7 +230,7 @@ Different KDFs are suitable for different tasks such as: .. warning:: - HKDFExpandOnly should only be used if the key material is + HKDFExpand should only be used if the key material is cryptographically strong. You should use :class:`~cryptography.hazmat.primitives.kdf.hkdf.HKDF` if you are unsure. @@ -239,19 +239,19 @@ Different KDFs are suitable for different tasks such as: >>> import os >>> from cryptography.hazmat.primitives import hashes - >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpandOnly + >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand >>> from cryptography.hazmat.backends import default_backend >>> backend = default_backend() >>> info = b"hkdf-example" >>> key_material = os.urandom(16) - >>> hkdf = HKDFExpandOnly( + >>> hkdf = HKDFExpand( ... algorithm=hashes.SHA256(), ... length=32, ... info=info, ... backend=backend ... ) >>> key = hkdf.derive(key_material) - >>> hkdf = HKDFExpandOnly( + >>> hkdf = HKDFExpand( ... algorithm=hashes.SHA256(), ... length=32, ... info=info, -- cgit v1.2.3 From dbd7a2554435b07d4e4fd8efcb72314b3b4d6962 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 9 May 2014 09:31:51 -0500 Subject: Multibackend now supports all of RSABackend Also convert some examples to doctest --- docs/hazmat/primitives/asymmetric/rsa.rst | 88 +++++++++++++++++++------------ 1 file changed, 54 insertions(+), 34 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 2700154c..7bae7142 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -154,21 +154,39 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. code-block:: python + .. doctest:: - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.asymmetric import padding + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding - plaintext = private_key.decrypt( - ciphertext, - padding.OAEP( - mgf=padding.MGF1(algorithm=hashes.SHA1()), - algorithm=hashes.SHA1(), - label=None - ), - default_backend() - ) + >>> # Generate a key + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) + >>> # Now do the actual decryption + >>> plaintext = private_key.decrypt( + ... ciphertext, + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) .. class:: RSAPublicKey(public_exponent, modulus) @@ -306,27 +324,29 @@ RSA :class:`~cryptography.hazmat.primitives.asymmetric.padding.OAEP` it may also be raised for invalid label values. - .. code-block:: python - - from cryptography.hazmat.backends import default_backend - from cryptography.hazmat.primitives import hashes - from cryptography.hazmat.primitives.asymmetric import padding, rsa - - private_key = rsa.RSAPrivateKey.generate( - public_exponent=65537, - key_size=2048, - backend=default_backend() - ) - public_key = private_key.public_key() - ciphertext = public_key.encrypt( - plaintext, - padding.OAEP( - mgf=padding.MGF1(algorithm=hashes.SHA1()), - algorithm=hashes.SHA1(), - label=None - ), - default_backend() - ) + .. doctest:: + + >>> from cryptography.hazmat.backends import default_backend + >>> from cryptography.hazmat.primitives import hashes + >>> from cryptography.hazmat.primitives.asymmetric import padding + + >>> # Generate a key + >>> private_key = rsa.RSAPrivateKey.generate( + ... public_exponent=65537, + ... key_size=2048, + ... backend=default_backend() + ... ) + >>> public_key = private_key.public_key() + >>> # encrypt some data + >>> ciphertext = public_key.encrypt( + ... b"encrypted data", + ... padding.OAEP( + ... mgf=padding.MGF1(algorithm=hashes.SHA1()), + ... algorithm=hashes.SHA1(), + ... label=None + ... ), + ... default_backend() + ... ) Handling partial RSA private keys -- cgit v1.2.3 From 006670cf9ad880ee46cdd41b4e65c2acf689f29a Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Fri, 9 May 2014 11:12:43 -0500 Subject: Use bold instead of italics --- docs/hazmat/primitives/symmetric-encryption.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/symmetric-encryption.rst b/docs/hazmat/primitives/symmetric-encryption.rst index 78bf6637..e5d8c65b 100644 --- a/docs/hazmat/primitives/symmetric-encryption.rst +++ b/docs/hazmat/primitives/symmetric-encryption.rst @@ -20,7 +20,7 @@ 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 +For this reason it is **strongly** recommended to combine encryption with a message authentication code, such as :doc:`HMAC `, in an "encrypt-then-MAC" formulation as `described by Colin Percival`_. -- cgit v1.2.3 From c48100a9126990552197b5431d22f7a9e065baf7 Mon Sep 17 00:00:00 2001 From: Ayrx Date: Sat, 10 May 2014 13:01:46 +0800 Subject: Added missing exception to documentation --- docs/hazmat/primitives/key-derivation-functions.rst | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 11fbd4e0..fdc540b9 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -276,12 +276,16 @@ Different KDFs are suitable for different tasks such as: :raises cryptography.exceptions.UnsupportedAlgorithm: This is raised if the provided ``backend`` does not implement :class:`~cryptography.hazmat.backends.interfaces.HMACBackend` + :raises TypeError: This is raised if the provided ``info`` is a unicode object .. method:: derive(key_material) :param bytes key_material: The input key material. :return bytes: The derived key. + :raises TypeError: This is raised if the provided ``key_material`` is + a unicode object + Derives a new key from the input key material by performing both the extract and expand operations. @@ -300,6 +304,8 @@ Different KDFs are suitable for different tasks such as: :meth:`verify` is called more than once. + :raises TypeError: This is raised if the provided ``key_material`` is + a unicode object This checks whether deriving a new key from the supplied ``key_material`` generates the same key as the ``expected_key``, and -- cgit v1.2.3 From aabc5a1386a75239418981742e85cd235f7d4a53 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 15 May 2014 13:42:41 -0400 Subject: Fixed #1039 -- provide links to PSS and PKCS1v15 in the RSA docs --- docs/hazmat/primitives/asymmetric/rsa.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 7bae7142..0f7e4093 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -85,7 +85,10 @@ RSA :param padding: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. + provider. Valid values are + :class:~cryptography.hazmat.primitives.asymmetric.padding.PSS` and + :class:~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` + (``PSS`` is recommended for all new applications). :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` @@ -254,7 +257,10 @@ RSA :param padding: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` - provider. + provider. Valid values are + :class:~cryptography.hazmat.primitives.asymmetric.padding.PSS` and + :class:~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` + (``PSS`` is recommended for all new applications). :param algorithm: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm` -- cgit v1.2.3 From af075f0e1e80d5ceb55f20dc95a305a741678469 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Thu, 15 May 2014 14:02:41 -0400 Subject: Missing semicolon --- docs/hazmat/primitives/asymmetric/rsa.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/asymmetric/rsa.rst b/docs/hazmat/primitives/asymmetric/rsa.rst index 0f7e4093..234a5c66 100644 --- a/docs/hazmat/primitives/asymmetric/rsa.rst +++ b/docs/hazmat/primitives/asymmetric/rsa.rst @@ -86,8 +86,8 @@ RSA :param padding: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. Valid values are - :class:~cryptography.hazmat.primitives.asymmetric.padding.PSS` and - :class:~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` and + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` (``PSS`` is recommended for all new applications). :param algorithm: An instance of a @@ -258,8 +258,8 @@ RSA :param padding: An instance of a :class:`~cryptography.hazmat.primitives.interfaces.AsymmetricPadding` provider. Valid values are - :class:~cryptography.hazmat.primitives.asymmetric.padding.PSS` and - :class:~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PSS` and + :class:`~cryptography.hazmat.primitives.asymmetric.padding.PKCS1v15` (``PSS`` is recommended for all new applications). :param algorithm: An instance of a -- cgit v1.2.3