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 833c6bfa856b0c5646286c0186cd81be651bfef7..b874a2a722e5af2caabfd04229abe62fa4426923 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 1b9342f69116eabf3e7db1f4d6fbc8921625dbf0..5d6bc4815274f077c5f64d81531d37284a51dab4 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 c589c8380a4b576c9f400fda684414a53874ac58..92eda67d0f67fc49d3848bb42fc00bcc4928191f 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 ecc95a56e3ec4205c5bcb7f7a2bf39f04a154901..ce110a1736f6c187b4df5d68ee94afa4a569f27f 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 882e03d98bb692c7ee9b970b4880d458529c4bb3..be86e46f73fff589f9b2ac59893335205313cda7 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