]>
Commit | Line | Data |
---|---|---|
aacfb134 AG |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
c952780c | 5 | EVP_PKEY_CTX_set_hkdf_md, EVP_PKEY_CTX_set1_hkdf_salt, |
327c1627 MC |
6 | EVP_PKEY_CTX_set1_hkdf_key, EVP_PKEY_CTX_add1_hkdf_info, |
7 | EVP_PKEY_CTX_hkdf_mode - | |
aacfb134 AG |
8 | HMAC-based Extract-and-Expand key derivation algorithm |
9 | ||
10 | =head1 SYNOPSIS | |
11 | ||
12 | #include <openssl/kdf.h> | |
13 | ||
327c1627 MC |
14 | int EVP_PKEY_CTX_hkdf_mode(EVP_PKEY_CTX *pctx, int mode); |
15 | ||
aacfb134 AG |
16 | int EVP_PKEY_CTX_set_hkdf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); |
17 | ||
18 | int EVP_PKEY_CTX_set1_hkdf_salt(EVP_PKEY_CTX *pctx, unsigned char *salt, | |
19 | int saltlen); | |
20 | ||
21 | int EVP_PKEY_CTX_set1_hkdf_key(EVP_PKEY_CTX *pctx, unsigned char *key, | |
22 | int keylen); | |
23 | ||
24 | int EVP_PKEY_CTX_add1_hkdf_info(EVP_PKEY_CTX *pctx, unsigned char *info, | |
25 | int infolen); | |
26 | ||
27 | =head1 DESCRIPTION | |
28 | ||
f04abe7d | 29 | The EVP_PKEY_HKDF algorithm implements the HKDF key derivation function. |
aacfb134 AG |
30 | HKDF follows the "extract-then-expand" paradigm, where the KDF logically |
31 | consists of two modules. The first stage takes the input keying material | |
32 | and "extracts" from it a fixed-length pseudorandom key K. The second stage | |
33 | "expands" the key K into several additional pseudorandom keys (the output | |
34 | of the KDF). | |
35 | ||
327c1627 MC |
36 | EVP_PKEY_CTX_hkdf_mode() sets the mode for the HKDF operation. There are three |
37 | modes that are currently defined: | |
38 | ||
39 | =over 4 | |
40 | ||
41 | =item EVP_PKEY_HKDEF_MODE_EXTRACT_AND_EXPAND | |
42 | ||
43 | This is the default mode. Calling L<EVP_PKEY_derive(3)> on an EVP_PKEY_CTX set | |
44 | up for HKDF will perform an extract followed by an expand operation in one go. | |
45 | The derived key returned will be the result after the expand operation. The | |
46 | intermediate fixed-length pseudorandom key K is not returned. | |
47 | ||
48 | In this mode the digest, key, salt and info values must be set before a key is | |
49 | derived or an error occurs. | |
50 | ||
51 | =item EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY | |
52 | ||
53 | In this mode calling L<EVP_PKEY_derive(3)> will just perform the extract | |
54 | operation. The value returned will be the intermediate fixed-length pseudorandom | |
55 | key K. | |
56 | ||
57 | The digest, key and salt values must be set before a key is derived or an | |
58 | error occurs. | |
59 | ||
60 | =item EVP_PKEY_HKDEF_MODE_EXPAND_ONLY | |
61 | ||
62 | In this mode calling L<EVP_PKEY_derive(3)> will just perform the expand | |
63 | operation. The input key should be set to the intermediate fixed-length | |
64 | pseudorandom key K returned from a previous extract operation. | |
65 | ||
66 | The digest, key and info values must be set before a key is derived or an | |
67 | error occurs. | |
68 | ||
69 | =back | |
70 | ||
aacfb134 AG |
71 | EVP_PKEY_set_hkdf_md() sets the message digest associated with the HKDF. |
72 | ||
73 | EVP_PKEY_CTX_set1_hkdf_salt() sets the salt to B<saltlen> bytes of the | |
74 | buffer B<salt>. Any existing value is replaced. | |
75 | ||
76 | EVP_PKEY_CTX_set_hkdf_key() sets the key to B<keylen> bytes of the buffer | |
77 | B<key>. Any existing value is replaced. | |
78 | ||
79 | EVP_PKEY_CTX_add1_hkdf_info() sets the info value to B<infolen> bytes of the | |
80 | buffer B<info>. If a value is already set, it is appended to the existing | |
81 | value. | |
82 | ||
f04abe7d VD |
83 | =head1 STRING CTRLS |
84 | ||
85 | HKDF also supports string based control operations via | |
86 | L<EVP_PKEY_CTX_ctrl_str(3)>. | |
87 | The B<type> parameter "md" uses the supplied B<value> as the name of the digest | |
88 | algorithm to use. | |
327c1627 MC |
89 | The B<type> parameter "mode" uses the values "EXTRACT_AND_EXPAND", |
90 | "EXTRACT_ONLY" and "EXPAND_ONLY" to determine the mode to use. | |
f04abe7d VD |
91 | The B<type> parameters "salt", "key" and "info" use the supplied B<value> |
92 | parameter as a B<seed>, B<key> or B<info> value. | |
93 | The names "hexsalt", "hexkey" and "hexinfo" are similar except they take a hex | |
94 | string which is converted to binary. | |
95 | ||
aacfb134 AG |
96 | =head1 NOTES |
97 | ||
98 | All these functions are implemented as macros. | |
99 | ||
100 | A context for HKDF can be obtained by calling: | |
101 | ||
c16ab9dc | 102 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); |
aacfb134 | 103 | |
aacfb134 AG |
104 | The total length of the info buffer cannot exceed 1024 bytes in length: this |
105 | should be more than enough for any normal use of HKDF. | |
106 | ||
327c1627 MC |
107 | The output length of an HKDF expand operation is specified via the length |
108 | parameter to the L<EVP_PKEY_derive(3)> function. | |
f04abe7d | 109 | Since the HKDF output length is variable, passing a B<NULL> buffer as a means |
327c1627 MC |
110 | to obtain the requisite length is not meaningful with HKDF in any mode that |
111 | performs an expand operation. Instead, the caller must allocate a buffer of the | |
112 | desired length, and pass that buffer to L<EVP_PKEY_derive(3)> along with (a | |
113 | pointer initialized to) the desired length. Passing a B<NULL> buffer to obtain | |
114 | the length is allowed when using EVP_PKEY_HKDEF_MODE_EXTRACT_ONLY. | |
aacfb134 AG |
115 | |
116 | Optimised versions of HKDF can be implemented in an ENGINE. | |
117 | ||
118 | =head1 RETURN VALUES | |
119 | ||
120 | All these functions return 1 for success and 0 or a negative value for failure. | |
121 | In particular a return value of -2 indicates the operation is not supported by | |
122 | the public key algorithm. | |
123 | ||
124 | =head1 EXAMPLE | |
125 | ||
126 | This example derives 10 bytes using SHA-256 with the secret key "secret", | |
127 | salt value "salt" and info value "label": | |
128 | ||
129 | EVP_PKEY_CTX *pctx; | |
130 | unsigned char out[10]; | |
131 | size_t outlen = sizeof(out); | |
132 | pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_HKDF, NULL); | |
133 | ||
134 | if (EVP_PKEY_derive_init(pctx) <= 0) | |
2947af32 | 135 | /* Error */ |
aacfb134 | 136 | if (EVP_PKEY_CTX_set_hkdf_md(pctx, EVP_sha256()) <= 0) |
2947af32 | 137 | /* Error */ |
d2139cf8 | 138 | if (EVP_PKEY_CTX_set1_hkdf_salt(pctx, "salt", 4) <= 0) |
2947af32 | 139 | /* Error */ |
d2139cf8 | 140 | if (EVP_PKEY_CTX_set1_hkdf_key(pctx, "secret", 6) <= 0) |
2947af32 | 141 | /* Error */ |
c67a2f80 | 142 | if (EVP_PKEY_CTX_add1_hkdf_info(pctx, "label", 5) <= 0) |
2947af32 | 143 | /* Error */ |
aacfb134 | 144 | if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) |
2947af32 | 145 | /* Error */ |
aacfb134 AG |
146 | |
147 | =head1 CONFORMING TO | |
148 | ||
149 | RFC 5869 | |
150 | ||
151 | =head1 SEE ALSO | |
152 | ||
153 | L<EVP_PKEY_CTX_new(3)>, | |
f04abe7d VD |
154 | L<EVP_PKEY_CTX_ctrl_str(3)>, |
155 | L<EVP_PKEY_derive(3)> | |
aacfb134 | 156 | |
e2f92610 RS |
157 | =head1 COPYRIGHT |
158 | ||
159 | Copyright 2016 The OpenSSL Project Authors. All Rights Reserved. | |
160 | ||
161 | Licensed under the OpenSSL license (the "License"). You may not use | |
162 | this file except in compliance with the License. You can obtain a copy | |
163 | in the file LICENSE in the source distribution or at | |
164 | L<https://www.openssl.org/source/license.html>. | |
165 | ||
166 | =cut |