diff options
| -rw-r--r-- | CHANGELOG.rst | 3 | ||||
| -rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 42 | ||||
| -rw-r--r-- | docs/hazmat/primitives/key-derivation-functions.rst | 51 | ||||
| -rw-r--r-- | src/cryptography/hazmat/primitives/interfaces/__init__.py | 26 | ||||
| -rw-r--r-- | src/cryptography/hazmat/primitives/kdf/__init__.py | 21 | ||||
| -rw-r--r-- | src/cryptography/hazmat/primitives/kdf/hkdf.py | 7 | ||||
| -rw-r--r-- | src/cryptography/hazmat/primitives/kdf/pbkdf2.py | 5 |
7 files changed, 92 insertions, 63 deletions
diff --git a/CHANGELOG.rst b/CHANGELOG.rst index 6439a4c8..97b0d6c7 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -10,6 +10,9 @@ Changelog now load elliptic curve public keys. * Added :func:`~cryptography.hazmat.primitives.asymmetric.rsa.rsa_recover_prime_factors` +* :class:`~cryptography.hazmat.primitives.kdf.KeyDerivationFunction` was moved + from :mod:`~cryptography.hazmat.primitives.interfaces` to + :mod:`~cryptography.hazmat.primitives.kdf`. * :class:`~cryptography.hazmat.primitives.hashes.HashAlgorithm` and :class:`~cryptography.hazmat.primitives.hashes.HashContext` were moved from :mod:`~cryptography.hazmat.primitives.interfaces` to diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 6029d1a9..f58d324d 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -47,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/src/cryptography/hazmat/primitives/interfaces/__init__.py b/src/cryptography/hazmat/primitives/interfaces/__init__.py index acd56458..6b4241bd 100644 --- a/src/cryptography/hazmat/primitives/interfaces/__init__.py +++ b/src/cryptography/hazmat/primitives/interfaces/__init__.py @@ -15,6 +15,7 @@ from cryptography.hazmat.primitives.asymmetric import ( padding, rsa ) from cryptography.hazmat.primitives.ciphers import modes +from cryptography.hazmat.primitives.kdf import KeyDerivationFunction from cryptography.hazmat.primitives.padding import PaddingContext @@ -347,22 +348,15 @@ AsymmetricVerificationContext = utils.deprecated( utils.DeprecatedIn08 ) - -@six.add_metaclass(abc.ABCMeta) -class KeyDerivationFunction(object): - @abc.abstractmethod - def derive(self, key_material): - """ - Deterministically generates and returns a new key based on the existing - key material. - """ - - @abc.abstractmethod - def verify(self, key_material, expected_key): - """ - Checks whether the key generated by the key material matches the - expected derived key. Raises an exception if they do not match. - """ +KeyDerivationFunction = utils.deprecated( + KeyDerivationFunction, + __name__, + ( + "The KeyDerivationFunction interface has moved to the " + "cryptography.hazmat.primitives.kdf module" + ), + utils.DeprecatedIn08 +) @six.add_metaclass(abc.ABCMeta) diff --git a/src/cryptography/hazmat/primitives/kdf/__init__.py b/src/cryptography/hazmat/primitives/kdf/__init__.py index 4b540884..2d0724e5 100644 --- a/src/cryptography/hazmat/primitives/kdf/__init__.py +++ b/src/cryptography/hazmat/primitives/kdf/__init__.py @@ -3,3 +3,24 @@ # for complete details. from __future__ import absolute_import, division, print_function + +import abc + +import six + + +@six.add_metaclass(abc.ABCMeta) +class KeyDerivationFunction(object): + @abc.abstractmethod + def derive(self, key_material): + """ + Deterministically generates and returns a new key based on the existing + key material. + """ + + @abc.abstractmethod + def verify(self, key_material, expected_key): + """ + Checks whether the key generated by the key material matches the + expected derived key. Raises an exception if they do not match. + """ diff --git a/src/cryptography/hazmat/primitives/kdf/hkdf.py b/src/cryptography/hazmat/primitives/kdf/hkdf.py index 3d4c9fb1..65b7091a 100644 --- a/src/cryptography/hazmat/primitives/kdf/hkdf.py +++ b/src/cryptography/hazmat/primitives/kdf/hkdf.py @@ -11,10 +11,11 @@ from cryptography.exceptions import ( AlreadyFinalized, InvalidKey, UnsupportedAlgorithm, _Reasons ) from cryptography.hazmat.backends.interfaces import HMACBackend -from cryptography.hazmat.primitives import constant_time, hmac, interfaces +from cryptography.hazmat.primitives import constant_time, hmac +from cryptography.hazmat.primitives.kdf import KeyDerivationFunction -@utils.register_interface(interfaces.KeyDerivationFunction) +@utils.register_interface(KeyDerivationFunction) class HKDF(object): def __init__(self, algorithm, length, salt, info, backend): if not isinstance(backend, HMACBackend): @@ -53,7 +54,7 @@ class HKDF(object): raise InvalidKey -@utils.register_interface(interfaces.KeyDerivationFunction) +@utils.register_interface(KeyDerivationFunction) class HKDFExpand(object): def __init__(self, algorithm, length, info, backend): if not isinstance(backend, HMACBackend): diff --git a/src/cryptography/hazmat/primitives/kdf/pbkdf2.py b/src/cryptography/hazmat/primitives/kdf/pbkdf2.py index 3d565be2..f8ce7a3b 100644 --- a/src/cryptography/hazmat/primitives/kdf/pbkdf2.py +++ b/src/cryptography/hazmat/primitives/kdf/pbkdf2.py @@ -9,10 +9,11 @@ from cryptography.exceptions import ( AlreadyFinalized, InvalidKey, UnsupportedAlgorithm, _Reasons ) from cryptography.hazmat.backends.interfaces import PBKDF2HMACBackend -from cryptography.hazmat.primitives import constant_time, interfaces +from cryptography.hazmat.primitives import constant_time +from cryptography.hazmat.primitives.kdf import KeyDerivationFunction -@utils.register_interface(interfaces.KeyDerivationFunction) +@utils.register_interface(KeyDerivationFunction) class PBKDF2HMAC(object): def __init__(self, algorithm, length, salt, iterations, backend): if not isinstance(backend, PBKDF2HMACBackend): |