]>
Commit | Line | Data |
---|---|---|
c54492ec | 1 | =pod |
5e98904c | 2 | {- OpenSSL::safe::output_do_not_edit_headers(); -} |
c54492ec SL |
3 | |
4 | =head1 NAME | |
5 | ||
b6b66573 | 6 | openssl-kdf - perform Key Derivation Function operations |
c54492ec SL |
7 | |
8 | =head1 SYNOPSIS | |
9 | ||
10 | B<openssl kdf> | |
11 | [B<-help>] | |
e8769719 | 12 | [B<-kdfopt> I<nm>:I<v>] |
c54492ec SL |
13 | [B<-keylen> I<num>] |
14 | [B<-out> I<filename>] | |
15 | [B<-binary>] | |
6bd4e3f2 | 16 | {- $OpenSSL::safe::opt_provider_synopsis -} |
c54492ec SL |
17 | I<kdf_name> |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
21 | The key derivation functions generate a derived key from either a secret or | |
22 | password. | |
23 | ||
24 | =head1 OPTIONS | |
25 | ||
26 | =over 4 | |
27 | ||
28 | =item B<-help> | |
29 | ||
30 | Print a usage message. | |
31 | ||
32 | =item B<-keylen> I<num> | |
33 | ||
34 | The output size of the derived key. This field is required. | |
35 | ||
36 | =item B<-out> I<filename> | |
37 | ||
38 | Filename to output to, or standard output by default. | |
39 | ||
40 | =item B<-binary> | |
41 | ||
42 | Output the derived key in binary form. Uses hexadecimal text format if not specified. | |
43 | ||
e8769719 | 44 | =item B<-kdfopt> I<nm>:I<v> |
c54492ec SL |
45 | |
46 | Passes options to the KDF algorithm. | |
54488bd9 P |
47 | A comprehensive list of parameters can be found in the EVP_KDF_CTX |
48 | implementation documentation. | |
660c5344 | 49 | Common parameter names used by EVP_KDF_CTX_set_params() are: |
c54492ec SL |
50 | |
51 | =over 4 | |
52 | ||
53 | =item B<key:>I<string> | |
54 | ||
55 | Specifies the secret key as an alphanumeric string (use if the key contains | |
56 | printable characters only). | |
57 | The string length must conform to any restrictions of the KDF algorithm. | |
58 | A key must be specified for most KDF algorithms. | |
59 | ||
60 | =item B<hexkey:>I<string> | |
61 | ||
62 | Specifies the secret key in hexadecimal form (two hex digits per byte). | |
63 | The key length must conform to any restrictions of the KDF algorithm. | |
64 | A key must be specified for most KDF algorithms. | |
65 | ||
66 | =item B<pass:>I<string> | |
67 | ||
68 | Specifies the password as an alphanumeric string (use if the password contains | |
69 | printable characters only). | |
70 | The password must be specified for PBKDF2 and scrypt. | |
71 | ||
72 | =item B<hexpass:>I<string> | |
73 | ||
74 | Specifies the password in hexadecimal form (two hex digits per byte). | |
75 | The password must be specified for PBKDF2 and scrypt. | |
76 | ||
77 | =item B<digest:>I<string> | |
78 | ||
79 | Specifies the name of a digest as an alphanumeric string. | |
80 | To see the list of supported digests, use the command I<list -digest-commands>. | |
81 | ||
82 | =back | |
83 | ||
6bd4e3f2 P |
84 | {- $OpenSSL::safe::opt_provider_item -} |
85 | ||
c54492ec SL |
86 | =item I<kdf_name> |
87 | ||
88 | Specifies the name of a supported KDF algorithm which will be used. | |
54488bd9 | 89 | The supported algorithms names include TLS1-PRF, HKDF, SSKDF, PBKDF2, |
e44192d1 | 90 | SSHKDF, X942KDF, X963KDF and SCRYPT. |
c54492ec SL |
91 | |
92 | =back | |
93 | ||
94 | =head1 EXAMPLES | |
95 | ||
96 | Use TLS1-PRF to create a hex-encoded derived key from a secret key and seed: | |
97 | ||
e44192d1 | 98 | openssl kdf -keylen 16 -kdfopt digest:SHA2-256 -kdfopt key:secret \ |
c54492ec SL |
99 | -kdfopt seed:seed TLS1-PRF |
100 | ||
101 | Use HKDF to create a hex-encoded derived key from a secret key, salt and info: | |
102 | ||
e44192d1 | 103 | openssl kdf -keylen 10 -kdfopt digest:SHA2-256 -kdfopt key:secret \ |
c54492ec SL |
104 | -kdfopt salt:salt -kdfopt info:label HKDF |
105 | ||
106 | Use SSKDF with KMAC to create a hex-encoded derived key from a secret key, salt and info: | |
107 | ||
e44192d1 | 108 | openssl kdf -keylen 64 -kdfopt mac:KMAC-128 -kdfopt maclen:20 \ |
c54492ec SL |
109 | -kdfopt hexkey:b74a149a161545 -kdfopt hexinfo:348a37a2 \ |
110 | -kdfopt hexsalt:3638271ccd68a2 SSKDF | |
111 | ||
112 | Use SSKDF with HMAC to create a hex-encoded derived key from a secret key, salt and info: | |
113 | ||
e44192d1 | 114 | openssl kdf -keylen 16 -kdfopt mac:HMAC -kdfopt digest:SHA2-256 \ |
c54492ec SL |
115 | -kdfopt hexkey:b74a149a -kdfopt hexinfo:348a37a2 \ |
116 | -kdfopt hexsalt:3638271c SSKDF | |
117 | ||
118 | Use SSKDF with Hash to create a hex-encoded derived key from a secret key, salt and info: | |
119 | ||
e44192d1 | 120 | openssl kdf -keylen 14 -kdfopt digest:SHA2-256 \ |
c54492ec SL |
121 | -kdfopt hexkey:6dbdc23f045488 \ |
122 | -kdfopt hexinfo:a1b2c3d4 SSKDF | |
123 | ||
124 | Use SSHKDF to create a hex-encoded derived key from a secret key, hash and session_id: | |
125 | ||
e44192d1 | 126 | openssl kdf -keylen 16 -kdfopt digest:SHA2-256 \ |
c54492ec SL |
127 | -kdfopt hexkey:0102030405 \ |
128 | -kdfopt hexxcghash:06090A \ | |
129 | -kdfopt hexsession_id:01020304 \ | |
130 | -kdfopt type:A SSHKDF | |
131 | ||
132 | Use PBKDF2 to create a hex-encoded derived key from a password and salt: | |
133 | ||
134 | openssl kdf -keylen 32 -kdfopt digest:SHA256 -kdfopt pass:password \ | |
135 | -kdfopt salt:salt -kdfopt iter:2 PBKDF2 | |
136 | ||
137 | Use scrypt to create a hex-encoded derived key from a password and salt: | |
138 | ||
139 | openssl kdf -keylen 64 -kdfopt pass:password -kdfopt salt:NaCl \ | |
140 | -kdfopt N:1024 -kdfopt r:8 -kdfopt p:16 \ | |
e44192d1 | 141 | -kdfopt maxmem_bytes:10485760 SCRYPT |
c54492ec SL |
142 | |
143 | =head1 NOTES | |
144 | ||
145 | The KDF mechanisms that are available will depend on the options | |
146 | used when building OpenSSL. | |
147 | ||
148 | =head1 SEE ALSO | |
149 | ||
b6b66573 | 150 | L<openssl(1)>, |
54488bd9 | 151 | L<openssl-pkeyutl(1)>, |
b4dca029 | 152 | L<EVP_KDF(3)>, |
54488bd9 P |
153 | L<EVP_KDF-SCRYPT(7)>, |
154 | L<EVP_KDF-TLS1_PRF(7)>, | |
155 | L<EVP_KDF-PBKDF2(7)>, | |
156 | L<EVP_KDF-HKDF(7)>, | |
157 | L<EVP_KDF-SS(7)>, | |
158 | L<EVP_KDF-SSHKDF(7)>, | |
159 | L<EVP_KDF-X942(7)>, | |
160 | L<EVP_KDF-X963(7)> | |
c54492ec SL |
161 | |
162 | =head1 HISTORY | |
163 | ||
164 | Added in OpenSSL 3.0 | |
165 | ||
166 | =head1 COPYRIGHT | |
167 | ||
33388b44 | 168 | Copyright 2019-2020 The OpenSSL Project Authors. All Rights Reserved. |
c54492ec | 169 | |
a6ed19dc | 170 | Licensed under the Apache License 2.0 (the "License"). You may not use |
c54492ec SL |
171 | this file except in compliance with the License. You can obtain a copy |
172 | in the file LICENSE in the source distribution or at | |
173 | L<https://www.openssl.org/source/license.html>. | |
174 | ||
175 | =cut |