From: Viktor Dukhovni <openssl-users@dukhovni.org>
Date: Fri, 4 Mar 2016 04:30:42 +0000 (-0500)
Subject: Improved HKDF and TLS1-PRF documentation
X-Git-Tag: OpenSSL_1_1_0-pre4~372
X-Git-Url: https://git.librecmc.org/?a=commitdiff_plain;h=f04abe7d500eeebc078a0ffb0e82997d5f62b2df;p=oweals%2Fopenssl.git

Improved HKDF and TLS1-PRF documentation

Reviewed-by: Rich Salz <rsalz@openssl.org>
---

diff --git a/doc/apps/pkeyutl.pod b/doc/apps/pkeyutl.pod
index 0426009094..1c8e83fa48 100644
--- a/doc/apps/pkeyutl.pod
+++ b/doc/apps/pkeyutl.pod
@@ -123,12 +123,15 @@ derive a shared secret using the peer key.
 
 =item B<-kdf algorithm>
 
-Use key derivation function B<algorithm>. Note: additional paramers
-will normally have to be set and the KDF output length for this to work.
+Use key derivation function B<algorithm>.  The supported algorithms are
+at present B<TLS1-PRF> and B<HKDF>.
+Note: additional paramers and the KDF output length will normally have to be
+set for this to work.  See L<EVP_PKEY_HKDF(3)> and L<EVP_PKEY_TLS1_PRF(3)>
+for the supported string parameters of each algorithm.
 
 =item B<-kdflen length>
 
-Set the ouput length for KDF.
+Set the output length for KDF.
 
 =item B<-pkeyopt opt:value>
 
@@ -155,7 +158,6 @@ for all available algorithms.
 When used with the B<-engine> option, it specifies to also use
 engine B<id> for crypto operations.
 
-
 =back
 
 =head1 NOTES
@@ -269,4 +271,5 @@ seed consisting of the single byte 0xFF.
 =head1 SEE ALSO
 
 L<genpkey(1)>, L<pkey(1)>, L<rsautl(1)>
-L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>
+L<dgst(1)>, L<rsa(1)>, L<genrsa(1)>,
+L<EVP_PKEY_HKDF(3)>, L<EVP_PKEY_TLS1_PRF(3)>
diff --git a/doc/crypto/EVP_PKEY_HKDF.pod b/doc/crypto/EVP_PKEY_HKDF.pod
index d44e130850..00c0a76bff 100644
--- a/doc/crypto/EVP_PKEY_HKDF.pod
+++ b/doc/crypto/EVP_PKEY_HKDF.pod
@@ -23,7 +23,7 @@ HMAC-based Extract-and-Expand key derivation algorithm
 
 =head1 DESCRIPTION
 
-The EVP_PKEY_HKDF alogorithm implements the HKDF key derivation function.
+The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function.
 HKDF follows the "extract-then-expand" paradigm, where the KDF logically
 consists of two modules. The first stage takes the input keying material
 and "extracts" from it a fixed-length pseudorandom key K. The second stage
@@ -42,6 +42,17 @@ EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the
 buffer B<info>. If a value is already set, it is appended to the existing
 value.
 
+=head1 STRING CTRLS
+
+HKDF also supports string based control operations via
+L<EVP_PKEY_CTX_ctrl_str(3)>.
+The B<type> parameter "md" uses the supplied B<value> as the name of the digest
+algorithm to use.
+The B<type> parameters "salt", "key" and "info" use the supplied B<value>
+parameter as a B<seed>, B<key> or B<info> value.
+The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex
+string which is converted to binary.
+
 =head1 NOTES
 
 All these functions are implemented as macros.
@@ -56,9 +67,13 @@ an error occurs.
 The total length of the info buffer cannot exceed 1024 bytes in length: this
 should be more than enough for any normal use of HKDF.
 
-The output length of the KDF is specified by the length parameter in the
-EVP_PKEY_derive() function. Since the output length is variable, setting
-the buffer to B<NULL> is not meaningful for HKDF.
+The output length of the KDF is specified via the length parameter to the
+L<EVP_PKEY_derive(3)> function.
+Since the HKDF output length is variable, passing a B<NULL> buffer as a means
+to obtain the requisite length is not meaningful with HKDF.
+Instead, the caller must allocate a buffer of the desired length, and pass that
+buffer to L<EVP_PKEY_derive(3)> along with (a pointer initialized to) the
+desired length.
 
 Optimised versions of HKDF can be implemented in an ENGINE.
 
@@ -98,6 +113,7 @@ RFC 5869
 =head1 SEE ALSO
 
 L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_derive(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
+L<EVP_PKEY_derive(3)>
 
 =cut
diff --git a/doc/crypto/EVP_PKEY_TLS1_PRF.pod b/doc/crypto/EVP_PKEY_TLS1_PRF.pod
index e2a695dff1..e2264fc34d 100644
--- a/doc/crypto/EVP_PKEY_TLS1_PRF.pod
+++ b/doc/crypto/EVP_PKEY_TLS1_PRF.pod
@@ -36,10 +36,13 @@ If a seed is already set it is appended to the existing value.
 =head1 STRING CTRLS
 
 The TLS PRF also supports string based control operations using
-EVP_PKEY_CTX_ctrl_str(). The B<type> parameters "secret" and "seed" use
-the supplied B<value> parameter as a secret or seed value. The names
-"hexsecret" and "hexseed" are similar except they take a hex string which
-is converted to binary.
+L<EVP_PKEY_CTX_ctrl_str(3)>.
+The B<type> parameter "md" uses the supplied B<value> as the name of the digest
+algorithm to use.
+The B<type> parameters "secret" and "seed" use the supplied B<value> parameter
+as a secret or seed value.
+The names "hexsecret" and "hexseed" are similar except they take a hex string
+which is converted to binary.
 
 =head1 NOTES
 
@@ -90,7 +93,7 @@ and seed value "seed":
 =head1 SEE ALSO
 
 L<EVP_PKEY_CTX_new(3)>,
-L<EVP_PKEY_CTX_ctrl(3)>,
+L<EVP_PKEY_CTX_ctrl_str(3)>,
 L<EVP_PKEY_derive(3)>
 
 =cut