From: Dimitri John Ledkov Date: Fri, 4 Oct 2024 22:41:44 +0000 (+0100) Subject: doc: EVP_KDF document the semantic meaning of output X-Git-Tag: openssl-3.1.8~101 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=baaa1356ce33716ededa82dbf59ae74c0652a67e;p=thirdparty%2Fopenssl.git doc: EVP_KDF document the semantic meaning of output Explicitely document what semantic meaning do various EVP_KDF algorithms produce. PBKDF2 produces cryptographic keys that are subject to cryptographic security measures, for example as defined in NIST SP 800-132. All other algorithms produce keying material, not subject to explicit output length checks in any known standards. Reviewed-by: Paul Dale Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/25610) (cherry picked from commit 6f08353a4b816fc04ab53880855b0d79c833e777) --- diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod index 833c6bfa856..b874a2a722e 100644 --- a/doc/man7/EVP_KDF-HKDF.pod +++ b/doc/man7/EVP_KDF-HKDF.pod @@ -15,6 +15,8 @@ and "extracts" from it a fixed-length pseudorandom key K. The second stage "expands" the key K into several additional pseudorandom keys (the output of the KDF). +The output is considered to be keying material. + =head2 Identity "HKDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-KB.pod b/doc/man7/EVP_KDF-KB.pod index 1b9342f6911..5d6bc481527 100644 --- a/doc/man7/EVP_KDF-KB.pod +++ b/doc/man7/EVP_KDF-KB.pod @@ -10,6 +10,8 @@ The EVP_KDF-KB algorithm implements the Key-Based key derivation function (KBKDF). KBKDF derives a key from repeated application of a keyed MAC to an input secret (and other optional values). +The output is considered to be keying material. + =head2 Identity "KBKDF" is the name for this implementation; it can be used with the diff --git a/doc/man7/EVP_KDF-PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod index e6cadc8b826..9a90f7583ab 100644 --- a/doc/man7/EVP_KDF-PBKDF2.pod +++ b/doc/man7/EVP_KDF-PBKDF2.pod @@ -13,6 +13,8 @@ The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key derivation function, as described in SP800-132; it derives a key from a password using a salt and iteration count. +The output is considered to be a cryptographic key. + =head2 Identity "PBKDF2" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod index c8d19691a79..6640703eef1 100644 --- a/doc/man7/EVP_KDF-SS.pod +++ b/doc/man7/EVP_KDF-SS.pod @@ -11,6 +11,8 @@ SSKDF derives a key using input such as a shared secret key (that was generated during the execution of a key establishment scheme) and fixedinfo. SSKDF is also informally referred to as 'Concat KDF'. +The output is considered to be keying material. + =head2 Auxiliary function The implementation uses a selectable auxiliary function H, which can be one of: diff --git a/doc/man7/EVP_KDF-SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod index c7a3263f455..a5b15394755 100644 --- a/doc/man7/EVP_KDF-SSHKDF.pod +++ b/doc/man7/EVP_KDF-SSHKDF.pod @@ -15,6 +15,8 @@ Five inputs are required to perform key derivation: The hashing function (for example SHA256), the Initial Key, the Exchange Hash, the Session ID, and the derivation key type. +The output is considered to be keying material. + =head2 Identity "SSHKDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-TLS13_KDF.pod b/doc/man7/EVP_KDF-TLS13_KDF.pod index c589c8380a4..92eda67d0f6 100644 --- a/doc/man7/EVP_KDF-TLS13_KDF.pod +++ b/doc/man7/EVP_KDF-TLS13_KDF.pod @@ -12,6 +12,8 @@ the B API. The EVP_KDF-TLS13_KDF algorithm implements the HKDF key derivation function as used by TLS 1.3. +The output is considered to be keying material. + =head2 Identity "TLS13-KDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod index ecc95a56e3e..ce110a1736f 100644 --- a/doc/man7/EVP_KDF-TLS1_PRF.pod +++ b/doc/man7/EVP_KDF-TLS1_PRF.pod @@ -11,6 +11,8 @@ Support for computing the B PRF through the B API. The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to and including TLS 1.2. +The output is considered to be keying material. + =head2 Identity "TLS1-PRF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-X942-ASN1.pod b/doc/man7/EVP_KDF-X942-ASN1.pod index a5786ab83fa..17464738b51 100644 --- a/doc/man7/EVP_KDF-X942-ASN1.pod +++ b/doc/man7/EVP_KDF-X942-ASN1.pod @@ -13,6 +13,8 @@ contains a 32 bit counter as well as optional fields for "partyu-info", "partyv-info", "supp-pubinfo" and "supp-privinfo". This kdf is used by Cryptographic Message Syntax (CMS). +The output is considered to be keying material. + =head2 Identity "X942KDF-ASN1" or "X942KDF" is the name for this implementation; it diff --git a/doc/man7/EVP_KDF-X963.pod b/doc/man7/EVP_KDF-X963.pod index 882e03d98bb..be86e46f73f 100644 --- a/doc/man7/EVP_KDF-X963.pod +++ b/doc/man7/EVP_KDF-X963.pod @@ -10,6 +10,8 @@ The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF). X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to derive a key using input such as a shared secret key and shared info. +The output is considered to be keying material. + =head2 Identity "X963KDF" is the name for this implementation; it