5 EVP_KDF_HKDF - The HKDF EVP_KDF implementation
9 Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
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
18 =head2 Numeric identity
20 B<EVP_KDF_HKDF> is the numeric identity for this implementation; it
21 can be used with the EVP_KDF_CTX_new_id() function.
23 =head2 Supported controls
25 The supported controls are:
29 =item B<EVP_KDF_CTRL_SET_SALT>
31 =item B<EVP_KDF_CTRL_SET_MD>
33 =item B<EVP_KDF_CTRL_SET_KEY>
35 These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
37 =item B<EVP_KDF_CTRL_RESET_HKDF_INFO>
39 This control does not expect any arguments.
41 Resets the context info buffer to zero length.
43 =item B<EVP_KDF_CTRL_ADD_HKDF_INFO>
45 This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
47 Sets the info value to the first B<infolen> bytes of the buffer B<info>. If a
48 value is already set, the contents of the buffer are appended to the existing
51 The total length of the context info buffer cannot exceed 1024 bytes;
52 this should be more than enough for any normal use of HKDF.
54 EVP_KDF_ctrl_str() takes two type strings for this control:
60 The value string is used as is.
64 The value string is expected to be a hexadecimal number, which will be
65 decoded before being passed on as the control value.
69 =item B<EVP_KDF_CTRL_SET_HKDF_MODE>
71 This control expects one argument: C<int mode>
73 Sets the mode for the HKDF operation. There are three modes that are currently
78 =item EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND
80 This is the default mode. Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set
81 up for HKDF will perform an extract followed by an expand operation in one go.
82 The derived key returned will be the result after the expand operation. The
83 intermediate fixed-length pseudorandom key K is not returned.
85 In this mode the digest, key, salt and info values must be set before a key is
86 derived otherwise an error will occur.
88 =item EVP_KDF_HKDF_MODE_EXTRACT_ONLY
90 In this mode calling L<EVP_KDF_derive(3)> will just perform the extract
91 operation. The value returned will be the intermediate fixed-length pseudorandom
92 key K. The C<keylen> parameter must match the size of K, which can be looked
93 up by calling EVP_KDF_size() after setting the mode and digest.
95 The digest, key and salt values must be set before a key is derived otherwise
98 =item EVP_KDF_HKDF_MODE_EXPAND_ONLY
100 In this mode calling L<EVP_KDF_derive(3)> will just perform the expand
101 operation. The input key should be set to the intermediate fixed-length
102 pseudorandom key K returned from a previous extract operation.
104 The digest, key and info values must be set before a key is derived otherwise
109 EVP_KDF_ctrl_str() type string: "mode"
111 The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY"
118 A context for HKDF can be obtained by calling:
120 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
122 The output length of an HKDF expand operation is specified via the C<keylen>
123 parameter to the L<EVP_KDF_derive(3)> function. When using
124 EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
125 the intermediate fixed-length pseudorandom key otherwise an error will occur.
126 For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
127 after setting the mode and digest on the C<EVP_KDF_CTX>.
131 This example derives 10 bytes using SHA-256 with the secret key "secret",
132 salt value "salt" and info value "label":
135 unsigned char out[10];
137 kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
139 if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
140 error("EVP_KDF_CTRL_SET_MD");
142 if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
143 error("EVP_KDF_CTRL_SET_SALT");
145 if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
146 error("EVP_KDF_CTRL_SET_KEY");
148 if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
149 error("EVP_KDF_CTRL_ADD_HKDF_INFO");
151 if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
152 error("EVP_KDF_derive");
155 EVP_KDF_CTX_free(kctx);
164 L<EVP_KDF_CTX_new_id(3)>,
165 L<EVP_KDF_CTX_free(3)>,
168 L<EVP_KDF_derive(3)>,
169 L<EVP_KDF_CTX(3)/CONTROLS>
173 Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
175 Licensed under the Apache License 2.0 (the "License"). You may not use
176 this file except in compliance with the License. You can obtain a copy
177 in the file LICENSE in the source distribution or at
178 L<https://www.openssl.org/source/license.html>.