]>
Commit | Line | Data |
---|---|---|
9537fe57 SL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF_SS - The Single Step / One Step EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | The EVP_KDF_SS algorithm implements the Single Step key derivation function (SSKDF). | |
10 | SSKDF derives a key using input such as a shared secret key (that was generated | |
11 | during the execution of a key establishment scheme) and fixedinfo. | |
12 | SSKDF is also informally referred to as 'Concat KDF'. | |
13 | ||
c2969ff6 | 14 | =head2 Auxiliary function |
9537fe57 SL |
15 | |
16 | The implementation uses a selectable auxiliary function H, which can be one of: | |
17 | ||
18 | =over 4 | |
19 | ||
20 | =item B<H(x) = hash(x, digest=md)> | |
21 | ||
22 | =item B<H(x) = HMAC_hash(x, key=salt, digest=md)> | |
23 | ||
24 | =item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)> | |
25 | ||
26 | =back | |
27 | ||
28 | Both the HMAC and KMAC implementations set the key using the 'salt' value. | |
29 | The hash and HMAC also require the digest to be set. | |
30 | ||
31 | =head2 Numeric identity | |
32 | ||
33 | B<EVP_KDF_SS> is the numeric identity for this implementation; it | |
34 | can be used with the EVP_KDF_CTX_new_id() function. | |
35 | ||
36 | =head2 Supported controls | |
37 | ||
38 | The supported controls are: | |
39 | ||
40 | =over 4 | |
41 | ||
42 | =item B<EVP_KDF_CTRL_SET_MD> | |
43 | ||
44 | =item B<EVP_KDF_CTRL_SET_MAC> | |
45 | ||
46 | =item B<EVP_MAC_CTRL_SET_MAC_SIZE> | |
47 | ||
48 | =item B<EVP_KDF_CTRL_SET_SALT> | |
49 | ||
50 | These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>. | |
51 | ||
52 | =item B<EVP_KDF_CTRL_SET_KEY> | |
53 | ||
54 | This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen> | |
55 | ||
56 | The shared secret used for key derivation. This control sets the secret. | |
57 | ||
58 | EVP_KDF_ctrl_str() takes two type strings for this control: | |
59 | ||
60 | =over 4 | |
61 | ||
62 | =item "secret" | |
63 | ||
64 | The value string is used as is. | |
65 | ||
66 | =item "hexsecret" | |
67 | ||
68 | The value string is expected to be a hexadecimal number, which will be | |
69 | decoded before being passed on as the control value. | |
70 | ||
71 | =back | |
72 | ||
73 | =item B<EVP_KDF_CTRL_SET_SSKDF_INFO> | |
74 | ||
75 | This control expects two arguments: C<unsigned char *info>, C<size_t infolen> | |
76 | ||
77 | An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo. | |
78 | ||
79 | EVP_KDF_ctrl_str() takes two type strings for this control: | |
80 | ||
81 | =over 4 | |
82 | ||
83 | =item "info" | |
84 | ||
85 | The value string is used as is. | |
86 | ||
87 | =item "hexinfo" | |
88 | ||
89 | The value string is expected to be a hexadecimal number, which will be | |
90 | decoded before being passed on as the control value. | |
91 | ||
92 | =back | |
93 | ||
94 | =back | |
95 | ||
96 | =head1 NOTES | |
97 | ||
98 | A context for SSKDF can be obtained by calling: | |
99 | ||
100 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); | |
101 | ||
102 | The output length of an SSKDF is specified via the C<keylen> | |
103 | parameter to the L<EVP_KDF_derive(3)> function. | |
104 | ||
105 | =head1 EXAMPLE | |
106 | ||
107 | This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret" | |
108 | and fixedinfo value "label": | |
109 | ||
110 | EVP_KDF_CTX *kctx; | |
111 | unsigned char out[10]; | |
112 | ||
113 | kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); | |
114 | ||
115 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { | |
116 | error("EVP_KDF_CTRL_SET_MD"); | |
117 | } | |
118 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { | |
119 | error("EVP_KDF_CTRL_SET_KEY"); | |
120 | } | |
121 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) { | |
122 | error("EVP_KDF_CTRL_SET_SSKDF_INFO"); | |
123 | } | |
124 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
125 | error("EVP_KDF_derive"); | |
126 | } | |
127 | ||
128 | EVP_KDF_CTX_free(kctx); | |
129 | ||
130 | =head1 EXAMPLE | |
131 | ||
132 | This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret", | |
133 | fixedinfo value "label" and salt "salt": | |
134 | ||
135 | EVP_KDF_CTX *kctx; | |
136 | unsigned char out[10]; | |
137 | ||
138 | kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); | |
139 | ||
140 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) { | |
141 | error("EVP_KDF_CTRL_SET_MAC"); | |
142 | } | |
143 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { | |
144 | error("EVP_KDF_CTRL_SET_MD"); | |
145 | } | |
146 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { | |
147 | error("EVP_KDF_CTRL_SET_KEY"); | |
148 | } | |
149 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) { | |
150 | error("EVP_KDF_CTRL_SET_SSKDF_INFO"); | |
151 | } | |
152 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) { | |
153 | error("EVP_KDF_CTRL_SET_SALT"); | |
154 | } | |
155 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
156 | error("EVP_KDF_derive"); | |
157 | } | |
158 | ||
159 | EVP_KDF_CTX_free(kctx); | |
160 | ||
161 | =head1 EXAMPLE | |
162 | ||
163 | This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret" | |
164 | fixedinfo value "label", salt of "salt" and KMAC outlen of 20: | |
165 | ||
166 | EVP_KDF_CTX *kctx; | |
167 | unsigned char out[10]; | |
168 | ||
169 | kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS); | |
170 | ||
171 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) { | |
172 | error("EVP_KDF_CTRL_SET_MAC"); | |
173 | } | |
174 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) { | |
175 | error("EVP_KDF_CTRL_SET_MD"); | |
176 | } | |
177 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) { | |
178 | error("EVP_KDF_CTRL_SET_KEY"); | |
179 | } | |
180 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) { | |
181 | error("EVP_KDF_CTRL_SET_SSKDF_INFO"); | |
182 | } | |
183 | /* If not specified the salt will be set to a default value */ | |
184 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) { | |
185 | error("EVP_KDF_CTRL_SET_SALT"); | |
186 | } | |
187 | /* If not specified the default size will be the size of the derived key */ | |
188 | if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) { | |
189 | error("EVP_KDF_CTRL_SET_MAC_SIZE"); | |
190 | } | |
191 | if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) { | |
192 | error("EVP_KDF_derive"); | |
193 | } | |
194 | ||
195 | EVP_KDF_CTX_free(kctx); | |
196 | ||
197 | ||
198 | =head1 CONFORMING TO | |
199 | ||
200 | NIST SP800-56Cr1. | |
201 | ||
202 | =head1 SEE ALSO | |
203 | ||
204 | L<EVP_KDF_CTX>, | |
205 | L<EVP_KDF_CTX_new_id(3)>, | |
206 | L<EVP_KDF_CTX_free(3)>, | |
207 | L<EVP_KDF_ctrl(3)>, | |
208 | L<EVP_KDF_size(3)>, | |
209 | L<EVP_KDF_derive(3)>, | |
210 | L<EVP_KDF_CTX(3)/CONTROLS> | |
211 | ||
212 | =head1 HISTORY | |
213 | ||
4674aaf4 | 214 | This functionality was added to OpenSSL 3.0. |
9537fe57 SL |
215 | |
216 | =head1 COPYRIGHT | |
217 | ||
218 | Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. Copyright | |
219 | (c) 2019, Oracle and/or its affiliates. All rights reserved. | |
220 | ||
221 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
222 | this file except in compliance with the License. You can obtain a copy | |
223 | in the file LICENSE in the source distribution or at | |
224 | L<https://www.openssl.org/source/license.html>. | |
225 | ||
226 | =cut |