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 <ppzgs1@gmail.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(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 5fc0a73241cca4bafb4b22a5abcb91dff5060048..b563efa5f5d756653cd37b7cf89166f6987c2fc1 100644 (file)
--- 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 6e25882d674c6e3ef3a043c4e6159938025b7494..78b81673a5bdab3cc4f4d11686c2a9574b797a63 100644 (file)
--- 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 e6cadc8b826d35e778ce52d1b6242140c0e2ac68..9a90f7583abe6d542db80dbd6facf9a0f0a1005d 100644 (file)
--- 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 c8d19691a797b86fd11ecb9e89351e2606eeb28f..6640703eef1c01242e8ff692f6765cbdf7a2f785 100644 (file)
--- 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 c7a3263f455ad25460da3ac9a817a0eb0d508d71..a5b153947558e2f01edc1dd01c4dc648ee52ae4b 100644 (file)
--- 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 d588b121faf5a3978ebf1c0b44015449c2c39117..7fad55ca61f1bc615f9a505a9e3cb3d431139384 100644 (file)
--- a/doc/man7/EVP_KDF-TLS13_KDF.pod
+++ b/doc/man7/EVP_KDF-TLS13_KDF.pod
@@ -12,6 +12,8 @@ the B<EVP_KDF> 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 8a60e97315549c89a8759ea6d4e17849c61c941d..90b357e70f0bb257c2bbba089b5d1cffa7333836 100644 (file)
--- 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<TLS1> PRF through the B<EVP_KDF> 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 a5786ab83faa8a6ce5baedb2244bb145d88584d7..17464738b511b45b79bddd74574e3cfa6816fc20 100644 (file)
--- 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 3d6f4372cf31229575a1b882789c6fe82be2298b..ca2f7c1df0efcc57fd0d3052404ad9fc52ab9471 100644 (file)
--- 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