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)

diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod
index b9860c3f05ebec4448f556b3e50d6867b6348f60..a269fbeabeb9499b823695104738384d27b4359c 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 13b865aa7671962e4c14e519118d1a64903fea14..0e63fb5b33552e8c92dae8ea00813267f54ccfa2 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 3db4498c42535f10fbadc779e6b2c3db8f100163..8af7fd78f17dcc2865513e029ade42b76c81017b 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 f10ce68d496d217106e516bd9d8d8023f184a525..acd2df00b2100010af9f3efdda06157de015133e 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 60ae62bb9ba7fe11445828d004592ab660546d86..e9531a8296e5befd18d8ed882c876e749d7e7e76 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 2b0c658b71fcc5dd0be4c4b6f6f7e4c896e74d10..d2805005913c125b1202894feb2ed7bde685c3d1 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 1c7c5516f09cb4751cfff20cdd55d7f0a8ef190b..a80915364a8f2194874a8f67910b5301df8b7c3e 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 3f62b8b82e7004f2454c0005478c567cd03422f3..b4d27a10782954744a0aa700fd12099834b4748d 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 38edc117a98bc99e6de4d22669d3b182d8e26fdf..2df67a728e47aa30e7322e4f1939fc6364549968 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