=pod
{- OpenSSL::safe::output_do_not_edit_headers(); -}

=head1 NAME

openssl-kdf - perform Key Derivation Function operations

=head1 SYNOPSIS

B<openssl kdf>
[B<-help>]
[B<-kdfopt> I<nm>:I<v>]
[B<-keylen> I<num>]
[B<-out> I<filename>]
[B<-binary>]
{- $OpenSSL::safe::opt_provider_synopsis -}
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>:I<v>

Passes options to the KDF algorithm.
A comprehensive list of parameters can be found in the EVP_KDF_CTX
implementation documentation.
Common parameter names used by EVP_KDF_CTX_set_params() 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

{- $OpenSSL::safe::opt_provider_item -}

=item I<kdf_name>

Specifies the name of a supported KDF algorithm which will be used.
The supported algorithms names include TLS1-PRF, HKDF, SSKDF, PBKDF2,
SSHKDF, X942KDF, X963KDF and 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:SHA2-256 -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:SHA2-256 -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:KMAC-128 -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:SHA2-256 \
                -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:SHA2-256 \
                -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:SHA2-256 \
                -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 SCRYPT

=head1 NOTES

The KDF mechanisms that are available will depend on the options
used when building OpenSSL.

=head1 SEE ALSO

L<openssl(1)>,
L<openssl-pkeyutl(1)>,
L<EVP_KDF(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)>,
L<EVP_KDF-X942(7)>,
L<EVP_KDF-X963(7)>

=head1 HISTORY

Added in OpenSSL 3.0

=head1 COPYRIGHT

Copyright 2019-2020 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