]>
Commit | Line | Data |
---|---|---|
ccd7115a P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF-HKDF - The HKDF EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | Support for computing the B<HKDF> KDF through the B<EVP_KDF> API. | |
10 | ||
11 | The EVP_KDF-HKDF algorithm implements the HKDF key derivation function. | |
12 | HKDF follows the "extract-then-expand" paradigm, where the KDF logically | |
13 | consists of two modules. The first stage takes the input keying material | |
14 | and "extracts" from it a fixed-length pseudorandom key K. The second stage | |
15 | "expands" the key K into several additional pseudorandom keys (the output | |
16 | of the KDF). | |
17 | ||
18 | =head2 Identity | |
19 | ||
20 | "HKDF" is the name for this implementation; it | |
21 | can be used with the EVP_KDF_fetch() function. | |
22 | ||
23 | =head2 Supported parameters | |
24 | ||
25 | The supported parameters are: | |
26 | ||
27 | =over 4 | |
28 | ||
0c452a51 | 29 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> |
ccd7115a | 30 | |
0c452a51 | 31 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
ccd7115a | 32 | |
0c452a51 | 33 | =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> |
ccd7115a | 34 | |
0c452a51 | 35 | =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> |
ccd7115a P |
36 | |
37 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. | |
38 | ||
0c452a51 | 39 | =item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> |
ccd7115a P |
40 | |
41 | This parameter sets the info value. | |
42 | The length of the context info buffer cannot exceed 1024 bytes; | |
43 | this should be more than enough for any normal use of HKDF. | |
44 | ||
0c452a51 | 45 | =item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string> or <integer> |
ccd7115a P |
46 | |
47 | This parameter sets the mode for the HKDF operation. | |
48 | There are three modes that are currently defined: | |
49 | ||
50 | =over 4 | |
51 | ||
52 | =item B<EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND> "EXTRACT_AND_EXPAND" | |
53 | ||
86913ef7 | 54 | This is the default mode. Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set |
ccd7115a P |
55 | up for HKDF will perform an extract followed by an expand operation in one go. |
56 | The derived key returned will be the result after the expand operation. The | |
57 | intermediate fixed-length pseudorandom key K is not returned. | |
58 | ||
59 | In this mode the digest, key, salt and info values must be set before a key is | |
60 | derived otherwise an error will occur. | |
61 | ||
62 | =item B<EVP_KDF_HKDF_MODE_EXTRACT_ONLY> "EXTRACT_ONLY" | |
63 | ||
86913ef7 | 64 | In this mode calling L<EVP_KDF_derive(3)> will just perform the extract |
ccd7115a | 65 | operation. The value returned will be the intermediate fixed-length pseudorandom |
dfabee82 | 66 | key K. The I<keylen> parameter must match the size of K, which can be looked |
ccd7115a P |
67 | up by calling EVP_KDF_size() after setting the mode and digest. |
68 | ||
69 | The digest, key and salt values must be set before a key is derived otherwise | |
70 | an error will occur. | |
71 | ||
72 | =item B<EVP_KDF_HKDF_MODE_EXPAND_ONLY> "EXPAND_ONLY" | |
73 | ||
86913ef7 | 74 | In this mode calling L<EVP_KDF_derive(3)> will just perform the expand |
ccd7115a P |
75 | operation. The input key should be set to the intermediate fixed-length |
76 | pseudorandom key K returned from a previous extract operation. | |
77 | ||
78 | The digest, key and info values must be set before a key is derived otherwise | |
79 | an error will occur. | |
80 | ||
81 | =back | |
82 | ||
83 | =back | |
84 | ||
85 | =head1 NOTES | |
86 | ||
87 | A context for HKDF can be obtained by calling: | |
88 | ||
89 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); | |
660c5344 | 90 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a | 91 | |
dfabee82 | 92 | The output length of an HKDF expand operation is specified via the I<keylen> |
86913ef7 | 93 | parameter to the L<EVP_KDF_derive(3)> function. When using |
dfabee82 | 94 | EVP_KDF_HKDF_MODE_EXTRACT_ONLY the I<keylen> parameter must equal the size of |
ccd7115a P |
95 | the intermediate fixed-length pseudorandom key otherwise an error will occur. |
96 | For that mode, the fixed output size can be looked up by calling EVP_KDF_size() | |
dfabee82 | 97 | after setting the mode and digest on the B<EVP_KDF_CTX>. |
ccd7115a P |
98 | |
99 | =head1 EXAMPLES | |
100 | ||
101 | This example derives 10 bytes using SHA-256 with the secret key "secret", | |
102 | salt value "salt" and info value "label": | |
103 | ||
104 | EVP_KDF *kdf; | |
105 | EVP_KDF_CTX *kctx; | |
106 | unsigned char out[10]; | |
107 | OSSL_PARAM params[5], *p = params; | |
108 | ||
109 | kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); | |
660c5344 | 110 | kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
111 | EVP_KDF_free(kdf); |
112 | ||
113 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
114 | SN_sha256, strlen(SN_sha256)); | |
115 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, | |
116 | "secret", (size_t)6); | |
117 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, | |
118 | "label", (size_t)5); | |
119 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, | |
120 | "salt", (size_t)4); | |
121 | *p = OSSL_PARAM_construct_end(); | |
660c5344 MC |
122 | if (EVP_KDF_CTX_set_params(kctx, params) <= 0) { |
123 | error("EVP_KDF_CTX_set_params"); | |
ccd7115a P |
124 | } |
125 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
126 | error("EVP_KDF_derive"); | |
127 | } | |
128 | ||
660c5344 | 129 | EVP_KDF_CTX_free(kctx); |
ccd7115a P |
130 | |
131 | =head1 CONFORMING TO | |
132 | ||
133 | RFC 5869 | |
134 | ||
135 | =head1 SEE ALSO | |
136 | ||
4c04e7b1 | 137 | L<EVP_KDF(3)>, |
660c5344 MC |
138 | L<EVP_KDF_CTX_new(3)>, |
139 | L<EVP_KDF_CTX_free(3)>, | |
4c04e7b1 | 140 | L<EVP_KDF_size(3)>, |
660c5344 | 141 | L<EVP_KDF_CTX_set_params(3)>, |
4c04e7b1 P |
142 | L<EVP_KDF_derive(3)>, |
143 | L<EVP_KDF(3)/PARAMETERS> | |
ccd7115a P |
144 | |
145 | =head1 COPYRIGHT | |
146 | ||
fbd2ece1 | 147 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. |
ccd7115a P |
148 | |
149 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
150 | this file except in compliance with the License. You can obtain a copy | |
151 | in the file LICENSE in the source distribution or at | |
152 | L<https://www.openssl.org/source/license.html>. | |
153 | ||
154 | =cut |