diff options
author | Paul Kehrer <paul.l.kehrer@gmail.com> | 2014-01-28 08:50:37 -0800 |
---|---|---|
committer | Paul Kehrer <paul.l.kehrer@gmail.com> | 2014-01-28 08:50:37 -0800 |
commit | 1f8cd620cfbb854b0dfcdbf89c140160a8caba13 (patch) | |
tree | bc8df644f525bb5b5ed97e83324b1e3d4ad8a6f2 /docs | |
parent | 59393dde1b47e235bc3803815909f944f54fa32f (diff) | |
parent | 8454c5153537439b36b879e82ab3a3d8e7aa7909 (diff) | |
download | cryptography-1f8cd620cfbb854b0dfcdbf89c140160a8caba13.tar.gz cryptography-1f8cd620cfbb854b0dfcdbf89c140160a8caba13.tar.bz2 cryptography-1f8cd620cfbb854b0dfcdbf89c140160a8caba13.zip |
Merge pull request #513 from alex/kdf-interface
Begin designing the KDF interfaces. Fixes #511
Diffstat (limited to 'docs')
-rw-r--r-- | docs/exceptions.rst | 10 | ||||
-rw-r--r-- | docs/hazmat/primitives/interfaces.rst | 44 |
2 files changed, 52 insertions, 2 deletions
diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 1fbd3267..1e31e31c 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -10,8 +10,8 @@ Exceptions .. class:: InvalidSignature - This is raised when the verify method of a hash context does not - compare equal. + This is raised when the verify method of a hash context's computed digest + does not match the expected digest. .. class:: NotYetFinalized @@ -30,3 +30,9 @@ Exceptions This is raised when a backend doesn't support the requested algorithm (or combination of algorithms). + + +.. class:: InvalidKey + + This is raised when the verify method of a key derivation function's + computed key does not match the expected key. diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index bf78e367..2adad913 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -204,4 +204,48 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +Key Derivation Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: KeyDerivationFunction + + .. versionadded:: 0.2 + + .. method:: derive(key_material) + + :param key_material bytes: The input key material. Depending on what + key derivation function you are using this + could be either random material, 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 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. This can be used for + something like checking whether a user's password attempt matches the + stored derived key. + .. _`RSA`: http://en.wikipedia.org/wiki/RSA_(cryptosystem) |