Skip to content

Commit

Permalink
doc: EVP_KDF document the semantic meaning of output
Browse files Browse the repository at this point in the history
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 <[email protected]>
Reviewed-by: Tomas Mraz <[email protected]>
(Merged from openssl#25610)

(cherry picked from commit 6f08353)
  • Loading branch information
xnox authored and t8m committed Oct 8, 2024
1 parent 4d8e2d7 commit 518a687
Show file tree
Hide file tree
Showing 9 changed files with 18 additions and 0 deletions.
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-HKDF.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-KB.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-PBKDF2.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-SS.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-SSHKDF.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-TLS13_KDF.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-TLS1_PRF.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-X942-ASN1.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 2 additions & 0 deletions doc/man7/EVP_KDF-X963.pod
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 518a687

Please sign in to comment.