From 2ad94ab70b03a8edc21163a6c66fbe6a49e80715 Mon Sep 17 00:00:00 2001 From: David Reid Date: Mon, 3 Feb 2014 10:01:15 -0800 Subject: Clarify salt language and link to the paper in addition to the RFC. --- docs/hazmat/primitives/key-derivation-functions.rst | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'docs/hazmat/primitives/key-derivation-functions.rst') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 678d13bf..df956326 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -126,7 +126,7 @@ Different KDFs are suitable for different tasks such as: .. versionadded:: 0.2 - `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) suitable + `HKDF`_ (HMAC-based Extract-and-Expand Key Derivation Function) is suitable for deriving keys of a fixed size used for other cryptographic operations. It consists of two distinct phases "Extract" and "Expand". The "Extract" @@ -141,8 +141,15 @@ Different KDFs are suitable for different tasks such as: :param int length: The desired length of the derived key. Maximum is 255 * (``algorithm.digest_size`` // 8). - :param bytes salt: A salt. If ``None`` is explicitly passed a default salt - of ``algorithm.digest_size // 8`` null bytes. + :param bytes salt: A salt. Randomizes the KDF's output. Optional, but + highly recommended. Ideally as many bits of entropy as the security + level of the hash: often that means cryptographically random and as + long as the hash output. Worse (shorter, less entropy) salt values can + still meaningfully contribute to security. May be reused. Does not have + to be secret, but may cause stronger security guarantees if secret; see + `RFC 5869`_ and the `HKDF paper`_ for more details. If ``None`` is + explicitly passed a default salt of ``algorithm.digest_size // 8`` null + bytes will be used. :param bytes info: Application specific context information. If ``None`` is explicitly passed an empty byte string will be used. @@ -186,4 +193,6 @@ Different KDFs are suitable for different tasks such as: .. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2 .. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt .. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching -.. _`HKDF`: http://tools.ietf.org/html/rfc5869 +.. _`HKDF`: +.. _`RFC 5869`: http://tools.ietf.org/html/rfc5869 +.. _`HKDF paper`: http://eprint.iacr.org/2010/264 -- cgit v1.2.3