diff options
author | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-03-03 23:30:42 -0500 |
---|---|---|
committer | Viktor Dukhovni <openssl-users@dukhovni.org> | 2016-03-04 01:23:46 -0500 |
commit | f04abe7d500eeebc078a0ffb0e82997d5f62b2df (patch) | |
tree | 45ac08dfbfb141d42c992797be2e0dcf5980e217 /doc | |
parent | c8cca980dc9a3d38eed6356219b84fcb5e257e0a (diff) |
Improved HKDF and TLS1-PRF documentation
Reviewed-by: Rich Salz <rsalz@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/apps/pkeyutl.pod | 13 | ||||
-rw-r--r-- | doc/crypto/EVP_PKEY_HKDF.pod | 26 | ||||
-rw-r--r-- | doc/crypto/EVP_PKEY_TLS1_PRF.pod | 13 |
3 files changed, 37 insertions, 15 deletions
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 |