diff options
Diffstat (limited to 'doc/man1/kdf.pod')
| -rw-r--r-- | doc/man1/kdf.pod | 167 |
1 files changed, 167 insertions, 0 deletions
diff --git a/doc/man1/kdf.pod b/doc/man1/kdf.pod new file mode 100644 index 0000000000..0ff7762b88 --- /dev/null +++ b/doc/man1/kdf.pod @@ -0,0 +1,167 @@ +=pod + +=head1 NAME + +openssl-kdf, +kdf - perform Key Derivation Function operations + +=head1 SYNOPSIS + +B<openssl kdf> +[B<-help>] +[B<-kdfopt> I<nm:v>] +[B<-keylen> I<num>] +[B<-out> I<filename>] +[B<-binary>] +I<kdf_name> + +=head1 DESCRIPTION + +The key derivation functions generate a derived key from either a secret or +password. + +=head1 OPTIONS + +=over 4 + +=item B<-help> + +Print a usage message. + +=item B<-keylen> I<num> + +The output size of the derived key. This field is required. + +=item B<-out> I<filename> + +Filename to output to, or standard output by default. + +=item B<-binary> + +Output the derived key in binary form. Uses hexadecimal text format if not specified. + +=item B<-kdfopt> I<nm:v> + +Passes options to the KDF algorithm. +A comprehensive list of controls can be found in the EVP_KDF_CTX implementation +documentation. +Common control strings used by EVP_KDF_ctrl_str() are: + +=over 4 + +=item B<key:>I<string> + +Specifies the secret key as an alphanumeric string (use if the key contains +printable characters only). +The string length must conform to any restrictions of the KDF algorithm. +A key must be specified for most KDF algorithms. + +=item B<hexkey:>I<string> + +Specifies the secret key in hexadecimal form (two hex digits per byte). +The key length must conform to any restrictions of the KDF algorithm. +A key must be specified for most KDF algorithms. + +=item B<pass:>I<string> + +Specifies the password as an alphanumeric string (use if the password contains +printable characters only). +The password must be specified for PBKDF2 and scrypt. + +=item B<hexpass:>I<string> + +Specifies the password in hexadecimal form (two hex digits per byte). +The password must be specified for PBKDF2 and scrypt. + +=item B<digest:>I<string> + +Specifies the name of a digest as an alphanumeric string. +To see the list of supported digests, use the command I<list -digest-commands>. + +=back + +=item I<kdf_name> + +Specifies the name of a supported KDF algorithm which will be used. +The supported algorithms names are TLS1-PRF, HKDF, SSKDF, PBKDF2, SSHKDF and id-scrypt. + +=back + +=head1 EXAMPLES + +Use TLS1-PRF to create a hex-encoded derived key from a secret key and seed: + + openssl kdf -keylen 16 -kdfopt digest:SHA256 -kdfopt key:secret \ + -kdfopt seed:seed TLS1-PRF + +Use HKDF to create a hex-encoded derived key from a secret key, salt and info: + + openssl kdf -keylen 10 -kdfopt digest:SHA256 -kdfopt key:secret \ + -kdfopt salt:salt -kdfopt info:label HKDF + +Use SSKDF with KMAC to create a hex-encoded derived key from a secret key, salt and info: + + openssl kdf -keylen 64 -kdfopt mac:KMAC128 -kdfopt maclen:20 \ + -kdfopt hexkey:b74a149a161545 -kdfopt hexinfo:348a37a2 \ + -kdfopt hexsalt:3638271ccd68a2 SSKDF + +Use SSKDF with HMAC to create a hex-encoded derived key from a secret key, salt and info: + + openssl kdf -keylen 16 -kdfopt mac:HMAC -kdfopt digest:SHA256 \ + -kdfopt hexkey:b74a149a -kdfopt hexinfo:348a37a2 \ + -kdfopt hexsalt:3638271c SSKDF + +Use SSKDF with Hash to create a hex-encoded derived key from a secret key, salt and info: + + openssl kdf -keylen 14 -kdfopt digest:SHA256 \ + -kdfopt hexkey:6dbdc23f045488 \ + -kdfopt hexinfo:a1b2c3d4 SSKDF + +Use SSHKDF to create a hex-encoded derived key from a secret key, hash and session_id: + + openssl kdf -keylen 16 -kdfopt digest:SHA256 \ + -kdfopt hexkey:0102030405 \ + -kdfopt hexxcghash:06090A \ + -kdfopt hexsession_id:01020304 \ + -kdfopt type:A SSHKDF + +Use PBKDF2 to create a hex-encoded derived key from a password and salt: + + openssl kdf -keylen 32 -kdfopt digest:SHA256 -kdfopt pass:password \ + -kdfopt salt:salt -kdfopt iter:2 PBKDF2 + +Use scrypt to create a hex-encoded derived key from a password and salt: + + openssl kdf -keylen 64 -kdfopt pass:password -kdfopt salt:NaCl \ + -kdfopt N:1024 -kdfopt r:8 -kdfopt p:16 \ + -kdfopt maxmem_bytes:10485760 id-scrypt + +=head1 NOTES + +The KDF mechanisms that are available will depend on the options +used when building OpenSSL. + +=head1 SEE ALSO + +L<EVP_KDF_CTX(3)>, +L<EVP_KDF_SCRYPT(7)> +L<EVP_KDF_TLS1_PRF(7)> +L<EVP_KDF_PBKDF2(7)> +L<EVP_KDF_HKDF(7)> +L<EVP_KDF_SS(7)> +L<EVP_KDF_SSHKDF(7)> + +=head1 HISTORY + +Added in OpenSSL 3.0 + +=head1 COPYRIGHT + +Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. + +Licensed under the OpenSSL license (the "License"). You may not use +this file except in compliance with the License. You can obtain a copy +in the file LICENSE in the source distribution or at +L<https://www.openssl.org/source/license.html>. + +=cut |