]>
Commit | Line | Data |
---|---|---|
9537fe57 SL |
1 | /* |
2 | * Copyright 2019 The OpenSSL Project Authors. All Rights Reserved. | |
3 | * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. | |
4 | * | |
5 | * Licensed under the Apache License 2.0 (the "License"). You may not use | |
6 | * this file except in compliance with the License. You can obtain a copy | |
7 | * in the file LICENSE in the source distribution or at | |
8 | * https://www.openssl.org/source/license.html | |
9 | */ | |
10 | ||
11 | /* | |
12 | * Refer to https://csrc.nist.gov/publications/detail/sp/800-56c/rev-1/final | |
13 | * Section 4.1. | |
14 | * | |
15 | * The Single Step KDF algorithm is given by: | |
16 | * | |
17 | * Result(0) = empty bit string (i.e., the null string). | |
18 | * For i = 1 to reps, do the following: | |
19 | * Increment counter by 1. | |
20 | * Result(i) = Result(i – 1) || H(counter || Z || FixedInfo). | |
21 | * DKM = LeftmostBits(Result(reps), L)) | |
22 | * | |
23 | * NOTES: | |
24 | * Z is a shared secret required to produce the derived key material. | |
25 | * counter is a 4 byte buffer. | |
26 | * FixedInfo is a bit string containing context specific data. | |
27 | * DKM is the output derived key material. | |
28 | * L is the required size of the DKM. | |
29 | * reps = [L / H_outputBits] | |
30 | * H(x) is the auxiliary function that can be either a hash, HMAC or KMAC. | |
31 | * H_outputBits is the length of the output of the auxiliary function H(x). | |
32 | * | |
33 | * Currently there is not a comprehensive list of test vectors for this | |
34 | * algorithm, especially for H(x) = HMAC and H(x) = KMAC. | |
35 | * Test vectors for H(x) = Hash are indirectly used by CAVS KAS tests. | |
36 | */ | |
37 | #include <stdlib.h> | |
38 | #include <stdarg.h> | |
39 | #include <string.h> | |
40 | #include <openssl/hmac.h> | |
41 | #include <openssl/evp.h> | |
42 | #include <openssl/kdf.h> | |
43 | #include "internal/cryptlib.h" | |
44 | #include "internal/evp_int.h" | |
45 | #include "kdf_local.h" | |
46 | ||
47 | struct evp_kdf_impl_st { | |
48 | const EVP_MAC *mac; /* H(x) = HMAC_hash OR H(x) = KMAC */ | |
49 | const EVP_MD *md; /* H(x) = hash OR when H(x) = HMAC_hash */ | |
50 | unsigned char *secret; | |
51 | size_t secret_len; | |
52 | unsigned char *info; | |
53 | size_t info_len; | |
54 | unsigned char *salt; | |
55 | size_t salt_len; | |
56 | size_t out_len; /* optional KMAC parameter */ | |
57 | }; | |
58 | ||
59 | #define SSKDF_MAX_INLEN (1<<30) | |
60 | #define SSKDF_KMAC128_DEFAULT_SALT_SIZE (168 - 4) | |
61 | #define SSKDF_KMAC256_DEFAULT_SALT_SIZE (136 - 4) | |
62 | ||
63 | /* KMAC uses a Customisation string of 'KDF' */ | |
64 | static const unsigned char kmac_custom_str[] = { 0x4B, 0x44, 0x46 }; | |
65 | ||
66 | /* | |
67 | * Refer to https://csrc.nist.gov/publications/detail/sp/800-56c/rev-1/final | |
68 | * Section 4. One-Step Key Derivation using H(x) = hash(x) | |
69 | */ | |
70 | static int SSKDF_hash_kdm(const EVP_MD *kdf_md, | |
71 | const unsigned char *z, size_t z_len, | |
72 | const unsigned char *info, size_t info_len, | |
73 | unsigned char *derived_key, size_t derived_key_len) | |
74 | { | |
75 | int ret = 0, hlen; | |
76 | size_t counter, out_len, len = derived_key_len; | |
77 | unsigned char c[4]; | |
78 | unsigned char mac[EVP_MAX_MD_SIZE]; | |
79 | unsigned char *out = derived_key; | |
80 | EVP_MD_CTX *ctx = NULL, *ctx_init = NULL; | |
81 | ||
82 | if (z_len > SSKDF_MAX_INLEN || info_len > SSKDF_MAX_INLEN | |
83 | || derived_key_len > SSKDF_MAX_INLEN | |
84 | || derived_key_len == 0) | |
85 | return 0; | |
86 | ||
87 | hlen = EVP_MD_size(kdf_md); | |
88 | if (hlen <= 0) | |
89 | return 0; | |
90 | out_len = (size_t)hlen; | |
91 | ||
92 | ctx = EVP_MD_CTX_create(); | |
93 | ctx_init = EVP_MD_CTX_create(); | |
94 | if (ctx == NULL || ctx_init == NULL) | |
95 | goto end; | |
96 | ||
97 | if (!EVP_DigestInit(ctx_init, kdf_md)) | |
98 | goto end; | |
99 | ||
100 | for (counter = 1;; counter++) { | |
101 | c[0] = (unsigned char)((counter >> 24) & 0xff); | |
102 | c[1] = (unsigned char)((counter >> 16) & 0xff); | |
103 | c[2] = (unsigned char)((counter >> 8) & 0xff); | |
104 | c[3] = (unsigned char)(counter & 0xff); | |
105 | ||
106 | if (!(EVP_MD_CTX_copy_ex(ctx, ctx_init) | |
107 | && EVP_DigestUpdate(ctx, c, sizeof(c)) | |
108 | && EVP_DigestUpdate(ctx, z, z_len) | |
109 | && EVP_DigestUpdate(ctx, info, info_len))) | |
110 | goto end; | |
111 | if (len >= out_len) { | |
112 | if (!EVP_DigestFinal_ex(ctx, out, NULL)) | |
113 | goto end; | |
114 | out += out_len; | |
115 | len -= out_len; | |
116 | if (len == 0) | |
117 | break; | |
118 | } else { | |
119 | if (!EVP_DigestFinal_ex(ctx, mac, NULL)) | |
120 | goto end; | |
121 | memcpy(out, mac, len); | |
122 | break; | |
123 | } | |
124 | } | |
125 | ret = 1; | |
126 | end: | |
127 | EVP_MD_CTX_destroy(ctx); | |
128 | EVP_MD_CTX_destroy(ctx_init); | |
129 | OPENSSL_cleanse(mac, sizeof(mac)); | |
130 | return ret; | |
131 | } | |
132 | ||
133 | static int kmac_init(EVP_MAC_CTX *ctx, const unsigned char *custom, | |
134 | size_t custom_len, size_t kmac_out_len, | |
135 | size_t derived_key_len, unsigned char **out) | |
136 | { | |
137 | /* Only KMAC has custom data - so return if not KMAC */ | |
138 | if (custom == NULL) | |
139 | return 1; | |
140 | ||
17838470 | 141 | if (EVP_MAC_ctrl(ctx, EVP_MAC_CTRL_SET_CUSTOM, custom, custom_len) <= 0) |
9537fe57 SL |
142 | return 0; |
143 | ||
144 | /* By default only do one iteration if kmac_out_len is not specified */ | |
145 | if (kmac_out_len == 0) | |
146 | kmac_out_len = derived_key_len; | |
147 | /* otherwise check the size is valid */ | |
148 | else if (!(kmac_out_len == derived_key_len | |
149 | || kmac_out_len == 20 | |
150 | || kmac_out_len == 28 | |
151 | || kmac_out_len == 32 | |
152 | || kmac_out_len == 48 | |
153 | || kmac_out_len == 64)) | |
154 | return 0; | |
155 | ||
17838470 | 156 | if (EVP_MAC_ctrl(ctx, EVP_MAC_CTRL_SET_SIZE, kmac_out_len) <= 0) |
9537fe57 SL |
157 | return 0; |
158 | ||
159 | /* | |
160 | * For kmac the output buffer can be larger than EVP_MAX_MD_SIZE: so | |
161 | * alloc a buffer for this case. | |
162 | */ | |
163 | if (kmac_out_len > EVP_MAX_MD_SIZE) { | |
164 | *out = OPENSSL_zalloc(kmac_out_len); | |
165 | if (*out == NULL) | |
166 | return 0; | |
167 | } | |
168 | return 1; | |
169 | } | |
170 | ||
171 | /* | |
172 | * Refer to https://csrc.nist.gov/publications/detail/sp/800-56c/rev-1/final | |
173 | * Section 4. One-Step Key Derivation using MAC: i.e either | |
174 | * H(x) = HMAC-hash(salt, x) OR | |
175 | * H(x) = KMAC#(salt, x, outbits, CustomString='KDF') | |
176 | */ | |
177 | static int SSKDF_mac_kdm(const EVP_MAC *kdf_mac, const EVP_MD *hmac_md, | |
178 | const unsigned char *kmac_custom, | |
179 | size_t kmac_custom_len, size_t kmac_out_len, | |
180 | const unsigned char *salt, size_t salt_len, | |
181 | const unsigned char *z, size_t z_len, | |
182 | const unsigned char *info, size_t info_len, | |
183 | unsigned char *derived_key, size_t derived_key_len) | |
184 | { | |
185 | int ret = 0; | |
186 | size_t counter, out_len, len; | |
187 | unsigned char c[4]; | |
188 | unsigned char mac_buf[EVP_MAX_MD_SIZE]; | |
189 | unsigned char *out = derived_key; | |
190 | EVP_MAC_CTX *ctx = NULL, *ctx_init = NULL; | |
191 | unsigned char *mac = mac_buf, *kmac_buffer = NULL; | |
192 | ||
193 | if (z_len > SSKDF_MAX_INLEN || info_len > SSKDF_MAX_INLEN | |
194 | || derived_key_len > SSKDF_MAX_INLEN | |
195 | || derived_key_len == 0) | |
196 | return 0; | |
197 | ||
198 | ctx = EVP_MAC_CTX_new(kdf_mac); | |
199 | ctx_init = EVP_MAC_CTX_new(kdf_mac); | |
200 | if (ctx == NULL || ctx_init == NULL) | |
201 | goto end; | |
202 | if (hmac_md != NULL && | |
17838470 | 203 | EVP_MAC_ctrl(ctx_init, EVP_MAC_CTRL_SET_MD, hmac_md) <= 0) |
9537fe57 SL |
204 | goto end; |
205 | ||
17838470 | 206 | if (EVP_MAC_ctrl(ctx_init, EVP_MAC_CTRL_SET_KEY, salt, salt_len) <= 0) |
9537fe57 SL |
207 | goto end; |
208 | ||
209 | if (!kmac_init(ctx_init, kmac_custom, kmac_custom_len, kmac_out_len, | |
210 | derived_key_len, &kmac_buffer)) | |
211 | goto end; | |
212 | if (kmac_buffer != NULL) | |
213 | mac = kmac_buffer; | |
214 | ||
215 | if (!EVP_MAC_init(ctx_init)) | |
216 | goto end; | |
217 | ||
218 | out_len = EVP_MAC_size(ctx_init); /* output size */ | |
219 | if (out_len <= 0) | |
220 | goto end; | |
221 | len = derived_key_len; | |
222 | ||
223 | for (counter = 1;; counter++) { | |
224 | c[0] = (unsigned char)((counter >> 24) & 0xff); | |
225 | c[1] = (unsigned char)((counter >> 16) & 0xff); | |
226 | c[2] = (unsigned char)((counter >> 8) & 0xff); | |
227 | c[3] = (unsigned char)(counter & 0xff); | |
228 | ||
229 | if (!(EVP_MAC_CTX_copy(ctx, ctx_init) | |
230 | && EVP_MAC_update(ctx, c, sizeof(c)) | |
231 | && EVP_MAC_update(ctx, z, z_len) | |
232 | && EVP_MAC_update(ctx, info, info_len))) | |
233 | goto end; | |
234 | if (len >= out_len) { | |
235 | if (!EVP_MAC_final(ctx, out, NULL)) | |
236 | goto end; | |
237 | out += out_len; | |
238 | len -= out_len; | |
239 | if (len == 0) | |
240 | break; | |
241 | } else { | |
242 | if (!EVP_MAC_final(ctx, mac, NULL)) | |
243 | goto end; | |
244 | memcpy(out, mac, len); | |
245 | break; | |
246 | } | |
247 | } | |
248 | ret = 1; | |
249 | end: | |
250 | OPENSSL_free(kmac_buffer); | |
251 | EVP_MAC_CTX_free(ctx); | |
252 | EVP_MAC_CTX_free(ctx_init); | |
253 | OPENSSL_cleanse(mac, sizeof(mac)); | |
254 | return ret; | |
255 | } | |
256 | ||
257 | static EVP_KDF_IMPL *sskdf_new(void) | |
258 | { | |
259 | EVP_KDF_IMPL *impl; | |
260 | ||
261 | if ((impl = OPENSSL_zalloc(sizeof(*impl))) == NULL) | |
262 | KDFerr(KDF_F_SSKDF_NEW, ERR_R_MALLOC_FAILURE); | |
263 | return impl; | |
264 | } | |
265 | ||
266 | static void sskdf_reset(EVP_KDF_IMPL *impl) | |
267 | { | |
268 | OPENSSL_clear_free(impl->secret, impl->secret_len); | |
269 | OPENSSL_clear_free(impl->info, impl->info_len); | |
270 | OPENSSL_clear_free(impl->salt, impl->salt_len); | |
271 | memset(impl, 0, sizeof(*impl)); | |
272 | } | |
273 | ||
274 | static void sskdf_free(EVP_KDF_IMPL *impl) | |
275 | { | |
276 | sskdf_reset(impl); | |
277 | OPENSSL_free(impl); | |
278 | } | |
279 | ||
280 | static int sskdf_set_buffer(va_list args, unsigned char **out, size_t *out_len) | |
281 | { | |
282 | const unsigned char *p; | |
283 | size_t len; | |
284 | ||
285 | p = va_arg(args, const unsigned char *); | |
286 | len = va_arg(args, size_t); | |
287 | if (len == 0 || p == NULL) | |
288 | return 1; | |
289 | ||
290 | OPENSSL_free(*out); | |
291 | *out = OPENSSL_memdup(p, len); | |
292 | if (*out == NULL) | |
293 | return 0; | |
294 | ||
295 | *out_len = len; | |
296 | return 1; | |
297 | } | |
298 | ||
299 | static int sskdf_ctrl(EVP_KDF_IMPL *impl, int cmd, va_list args) | |
300 | { | |
301 | const EVP_MD *md; | |
302 | const EVP_MAC *mac; | |
303 | ||
304 | switch (cmd) { | |
305 | case EVP_KDF_CTRL_SET_KEY: | |
306 | return sskdf_set_buffer(args, &impl->secret, &impl->secret_len); | |
307 | ||
308 | case EVP_KDF_CTRL_SET_SSKDF_INFO: | |
309 | return sskdf_set_buffer(args, &impl->info, &impl->info_len); | |
310 | ||
311 | case EVP_KDF_CTRL_SET_MD: | |
312 | md = va_arg(args, const EVP_MD *); | |
313 | if (md == NULL) | |
314 | return 0; | |
315 | ||
316 | impl->md = md; | |
317 | return 1; | |
318 | ||
319 | case EVP_KDF_CTRL_SET_MAC: | |
320 | mac = va_arg(args, const EVP_MAC *); | |
321 | if (mac == NULL) | |
322 | return 0; | |
323 | ||
324 | impl->mac = mac; | |
325 | return 1; | |
326 | ||
327 | case EVP_KDF_CTRL_SET_SALT: | |
328 | return sskdf_set_buffer(args, &impl->salt, &impl->salt_len); | |
329 | ||
330 | case EVP_KDF_CTRL_SET_MAC_SIZE: | |
331 | impl->out_len = va_arg(args, size_t); | |
332 | return 1; | |
333 | ||
334 | default: | |
335 | return -2; | |
336 | } | |
337 | } | |
338 | ||
339 | /* Pass a mac to a ctrl */ | |
340 | static int sskdf_mac2ctrl(EVP_KDF_IMPL *impl, | |
341 | int (*ctrl)(EVP_KDF_IMPL *impl, int cmd, va_list args), | |
342 | int cmd, const char *mac_name) | |
343 | { | |
344 | const EVP_MAC *mac; | |
345 | ||
346 | if (mac_name == NULL || (mac = EVP_get_macbyname(mac_name)) == NULL) { | |
347 | KDFerr(KDF_F_SSKDF_MAC2CTRL, KDF_R_INVALID_MAC_TYPE); | |
348 | return 0; | |
349 | } | |
350 | return call_ctrl(ctrl, impl, cmd, mac); | |
351 | } | |
352 | ||
353 | static int sskdf_ctrl_str(EVP_KDF_IMPL *impl, const char *type, | |
354 | const char *value) | |
355 | { | |
356 | if (strcmp(type, "secret") == 0 || strcmp(type, "key") == 0) | |
357 | return kdf_str2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_KEY, | |
358 | value); | |
359 | ||
360 | if (strcmp(type, "hexsecret") == 0 || strcmp(type, "hexkey") == 0) | |
361 | return kdf_hex2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_KEY, | |
362 | value); | |
363 | ||
364 | if (strcmp(type, "info") == 0) | |
365 | return kdf_str2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_SSKDF_INFO, | |
366 | value); | |
367 | ||
368 | if (strcmp(type, "hexinfo") == 0) | |
369 | return kdf_hex2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_SSKDF_INFO, | |
370 | value); | |
371 | ||
372 | if (strcmp(type, "digest") == 0) | |
373 | return kdf_md2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_MD, value); | |
374 | ||
375 | if (strcmp(type, "mac") == 0) | |
376 | return sskdf_mac2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_MAC, value); | |
377 | ||
378 | if (strcmp(type, "salt") == 0) | |
379 | return kdf_str2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_SALT, value); | |
380 | ||
381 | if (strcmp(type, "hexsalt") == 0) | |
382 | return kdf_hex2ctrl(impl, sskdf_ctrl, EVP_KDF_CTRL_SET_SALT, value); | |
383 | ||
384 | ||
385 | if (strcmp(type, "maclen") == 0) { | |
386 | int val = atoi(value); | |
387 | if (val < 0) { | |
388 | KDFerr(KDF_F_SSKDF_CTRL_STR, KDF_R_VALUE_ERROR); | |
389 | return 0; | |
390 | } | |
391 | return call_ctrl(sskdf_ctrl, impl, EVP_KDF_CTRL_SET_MAC_SIZE, | |
392 | (size_t)val); | |
393 | } | |
394 | return -2; | |
395 | } | |
396 | ||
397 | static size_t sskdf_size(EVP_KDF_IMPL *impl) | |
398 | { | |
399 | int len; | |
400 | ||
401 | if (impl->md == NULL) { | |
402 | KDFerr(KDF_F_SSKDF_SIZE, KDF_R_MISSING_MESSAGE_DIGEST); | |
403 | return 0; | |
404 | } | |
405 | len = EVP_MD_size(impl->md); | |
406 | return (len <= 0) ? 0 : (size_t)len; | |
407 | } | |
408 | ||
409 | static int sskdf_derive(EVP_KDF_IMPL *impl, unsigned char *key, size_t keylen) | |
410 | { | |
411 | if (impl->secret == NULL) { | |
412 | KDFerr(KDF_F_SSKDF_DERIVE, KDF_R_MISSING_SECRET); | |
413 | return 0; | |
414 | } | |
415 | ||
416 | if (impl->mac != NULL) { | |
417 | /* H(x) = KMAC or H(x) = HMAC */ | |
418 | int ret; | |
419 | const unsigned char *custom = NULL; | |
420 | size_t custom_len = 0; | |
421 | int nid; | |
422 | int default_salt_len; | |
423 | ||
424 | nid = EVP_MAC_nid(impl->mac); | |
425 | if (nid == EVP_MAC_HMAC) { | |
426 | /* H(x) = HMAC(x, salt, hash) */ | |
427 | if (impl->md == NULL) { | |
428 | KDFerr(KDF_F_SSKDF_DERIVE, KDF_R_MISSING_MESSAGE_DIGEST); | |
429 | return 0; | |
430 | } | |
431 | default_salt_len = EVP_MD_block_size(impl->md); | |
432 | if (default_salt_len <= 0) | |
433 | return 0; | |
434 | } else if (nid == EVP_MAC_KMAC128 || nid == EVP_MAC_KMAC256) { | |
435 | /* H(x) = KMACzzz(x, salt, custom) */ | |
436 | custom = kmac_custom_str; | |
437 | custom_len = sizeof(kmac_custom_str); | |
438 | if (nid == EVP_MAC_KMAC128) | |
439 | default_salt_len = SSKDF_KMAC128_DEFAULT_SALT_SIZE; | |
440 | else | |
441 | default_salt_len = SSKDF_KMAC256_DEFAULT_SALT_SIZE; | |
442 | } else { | |
443 | KDFerr(KDF_F_SSKDF_DERIVE, KDF_R_UNSUPPORTED_MAC_TYPE); | |
444 | return 0; | |
445 | } | |
446 | /* If no salt is set then use a default_salt of zeros */ | |
447 | if (impl->salt == NULL || impl->salt_len <= 0) { | |
448 | impl->salt = OPENSSL_zalloc(default_salt_len); | |
449 | if (impl->salt == NULL) { | |
450 | KDFerr(KDF_F_SSKDF_DERIVE, ERR_R_MALLOC_FAILURE); | |
451 | return 0; | |
452 | } | |
453 | impl->salt_len = default_salt_len; | |
454 | } | |
455 | ret = SSKDF_mac_kdm(impl->mac, impl->md, | |
456 | custom, custom_len, impl->out_len, | |
457 | impl->salt, impl->salt_len, | |
458 | impl->secret, impl->secret_len, | |
459 | impl->info, impl->info_len, key, keylen); | |
460 | return ret; | |
461 | } else { | |
462 | /* H(x) = hash */ | |
463 | if (impl->md == NULL) { | |
464 | KDFerr(KDF_F_SSKDF_DERIVE, KDF_R_MISSING_MESSAGE_DIGEST); | |
465 | return 0; | |
466 | } | |
467 | return SSKDF_hash_kdm(impl->md, impl->secret, impl->secret_len, | |
468 | impl->info, impl->info_len, key, keylen); | |
469 | } | |
470 | } | |
471 | ||
472 | const EVP_KDF_METHOD ss_kdf_meth = { | |
473 | EVP_KDF_SS, | |
474 | sskdf_new, | |
475 | sskdf_free, | |
476 | sskdf_reset, | |
477 | sskdf_ctrl, | |
478 | sskdf_ctrl_str, | |
479 | sskdf_size, | |
480 | sskdf_derive | |
481 | }; |