From b2774f53bc5840ae7c414ee78bef654a2ae89f01 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 27 Jan 2014 11:05:29 -0800 Subject: Begin designing the KDF interfaces. Fixes #511 --- docs/exceptions.rst | 6 ++++++ docs/hazmat/primitives/interfaces.rst | 30 ++++++++++++++++++++++++++++++ 2 files changed, 36 insertions(+) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index 1fbd3267..f9e29f3c 100644 --- a/docs/exceptions.rst +++ b/docs/exceptions.rst @@ -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 does not + compare equal. diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index bf78e367..ac48dd2c 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -204,4 +204,34 @@ Asymmetric Interfaces The public exponent. Alias for :attr:`public_exponent`. +Key Derivation Functions +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. class:: KeyDerivationFunction + + .. method:: derive(key_material) + + :param key_material bytes: The raw key material. Depending on what key + derivation function you are using this could + be either random material, or a user + supplied password. + :return: The resulting key. + + The generates and returns a new key from the supplied key material. + + .. method:: verify(key_material, expected_key) + + :param key_material bytes: The raw key material. This is the same as + ``key_material`` in :meth:`derive`. + :param expected_key bytes: What the expected result of deriving a new + key is. + :raises cryptography.exceptions.InvalidKey: This is raised when the + derived key does not match + the expected key. + + This checks whether deriving a 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) -- cgit v1.2.3 From 288403a1a45554609d8b519d8b8d5a5abc9576c5 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Mon, 27 Jan 2014 15:59:17 -0800 Subject: Attempt some more natural language --- docs/exceptions.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) (limited to 'docs') diff --git a/docs/exceptions.rst b/docs/exceptions.rst index f9e29f3c..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 @@ -34,5 +34,5 @@ Exceptions .. class:: InvalidKey - This is raised when the verify method of a key derivation function does not - compare equal. + This is raised when the verify method of a key derivation function's + computed key does not match the expected key. -- cgit v1.2.3 From 5484f72a8f83b8488bd22cae98be7c0c3576991a Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 05:46:15 -0800 Subject: Try to improve the docs --- docs/hazmat/primitives/interfaces.rst | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) (limited to 'docs') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index ac48dd2c..ddccb773 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -211,27 +211,29 @@ Key Derivation Functions .. method:: derive(key_material) - :param key_material bytes: The raw key material. Depending on what key - derivation function you are using this could - be either random material, or a user + :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 resulting key. + :return: The new key. - The generates and returns a new key from the supplied key material. + This generates and returns a new key from the supplied key material. .. method:: verify(key_material, expected_key) - :param key_material bytes: The raw key material. This is the same as + :param key_material bytes: The input key material. This is the same as ``key_material`` in :meth:`derive`. - :param expected_key bytes: What the expected result of deriving a new - key is. + :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. - This checks whether deriving a 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. + 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) -- cgit v1.2.3 From e19e89f3e29c057a8250f5f63dde444b495259f7 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 06:58:43 -0800 Subject: Enforce that these may only be called once --- docs/hazmat/primitives/interfaces.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index ddccb773..12644f4c 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -216,6 +216,11 @@ Key Derivation Functions 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. @@ -229,6 +234,11 @@ Key Derivation Functions :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 -- cgit v1.2.3 From 8454c5153537439b36b879e82ab3a3d8e7aa7909 Mon Sep 17 00:00:00 2001 From: Alex Gaynor Date: Tue, 28 Jan 2014 07:01:54 -0800 Subject: Document that this is new in 0.2 --- docs/hazmat/primitives/interfaces.rst | 2 ++ 1 file changed, 2 insertions(+) (limited to 'docs') diff --git a/docs/hazmat/primitives/interfaces.rst b/docs/hazmat/primitives/interfaces.rst index 12644f4c..2adad913 100644 --- a/docs/hazmat/primitives/interfaces.rst +++ b/docs/hazmat/primitives/interfaces.rst @@ -209,6 +209,8 @@ Key Derivation Functions .. class:: KeyDerivationFunction + .. versionadded:: 0.2 + .. method:: derive(key_material) :param key_material bytes: The input key material. Depending on what -- cgit v1.2.3