1 /*
2 * Copyright 2016-2025 The OpenSSL Project Authors. All Rights Reserved.
3 *
4 * Licensed under the Apache License 2.0 (the "License"). You may not use
5 * this file except in compliance with the License. You can obtain a copy
6 * in the file LICENSE in the source distribution or at
7 * https://www.openssl.org/source/license.html
8 */
9
10 /*
11 * HMAC low level APIs are deprecated for public use, but still ok for internal
12 * use.
13 */
14 #include "internal/deprecated.h"
15
16 #include <stdlib.h>
17 #include <stdarg.h>
18 #include <string.h>
19 #include <openssl/hmac.h>
20 #include <openssl/evp.h>
21 #include <openssl/kdf.h>
22 #include <openssl/core_names.h>
23 #include <openssl/proverr.h>
24 #include "internal/cryptlib.h"
25 #include "internal/numbers.h"
26 #include "internal/packet.h"
27 #include "crypto/evp.h"
28 #include "prov/provider_ctx.h"
29 #include "prov/providercommon.h"
30 #include "prov/implementations.h"
31 #include "prov/provider_util.h"
32 #include "prov/securitycheck.h"
33 #include "internal/e_os.h"
34 #include "internal/params.h"
35
36 #define HKDF_MAXBUF 2048
37 #define HKDF_MAXINFO (32*1024)
38
39 static OSSL_FUNC_kdf_newctx_fn kdf_hkdf_new;
40 static OSSL_FUNC_kdf_dupctx_fn kdf_hkdf_dup;
41 static OSSL_FUNC_kdf_freectx_fn kdf_hkdf_free;
42 static OSSL_FUNC_kdf_reset_fn kdf_hkdf_reset;
43 static OSSL_FUNC_kdf_derive_fn kdf_hkdf_derive;
44 static OSSL_FUNC_kdf_settable_ctx_params_fn kdf_hkdf_settable_ctx_params;
45 static OSSL_FUNC_kdf_set_ctx_params_fn kdf_hkdf_set_ctx_params;
46 static OSSL_FUNC_kdf_gettable_ctx_params_fn kdf_hkdf_gettable_ctx_params;
47 static OSSL_FUNC_kdf_get_ctx_params_fn kdf_hkdf_get_ctx_params;
48 static OSSL_FUNC_kdf_derive_fn kdf_tls1_3_derive;
49 static OSSL_FUNC_kdf_settable_ctx_params_fn kdf_tls1_3_settable_ctx_params;
50 static OSSL_FUNC_kdf_set_ctx_params_fn kdf_tls1_3_set_ctx_params;
51 static OSSL_FUNC_kdf_gettable_ctx_params_fn kdf_tls1_3_gettable_ctx_params;
52 static OSSL_FUNC_kdf_get_ctx_params_fn kdf_tls1_3_get_ctx_params;
53
54 static int HKDF(OSSL_LIB_CTX *libctx, const EVP_MD *evp_md,
55 const unsigned char *salt, size_t salt_len,
56 const unsigned char *key, size_t key_len,
57 const unsigned char *info, size_t info_len,
58 unsigned char *okm, size_t okm_len);
59 static int HKDF_Extract(OSSL_LIB_CTX *libctx, const EVP_MD *evp_md,
60 const unsigned char *salt, size_t salt_len,
61 const unsigned char *ikm, size_t ikm_len,
62 unsigned char *prk, size_t prk_len);
63 static int HKDF_Expand(const EVP_MD *evp_md,
64 const unsigned char *prk, size_t prk_len,
65 const unsigned char *info, size_t info_len,
66 unsigned char *okm, size_t okm_len);
67
68 /* Settable context parameters that are common across HKDF and the TLS KDF */
69 #define HKDF_COMMON_SETTABLES \
70 OSSL_PARAM_utf8_string(OSSL_KDF_PARAM_MODE, NULL, 0), \
71 OSSL_PARAM_int(OSSL_KDF_PARAM_MODE, NULL), \
72 OSSL_PARAM_utf8_string(OSSL_KDF_PARAM_PROPERTIES, NULL, 0), \
73 OSSL_PARAM_utf8_string(OSSL_KDF_PARAM_DIGEST, NULL, 0), \
74 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_KEY, NULL, 0), \
75 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_SALT, NULL, 0)
76
77 /* Gettable context parameters that are common across HKDF and the TLS KDF */
78 #define HKDF_COMMON_GETTABLES \
79 OSSL_PARAM_size_t(OSSL_KDF_PARAM_SIZE, NULL), \
80 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_INFO, NULL, 0)
81
82 typedef struct {
83 void *provctx;
84 int mode;
85 PROV_DIGEST digest;
86 unsigned char *salt;
87 size_t salt_len;
88 unsigned char *key;
89 size_t key_len;
90 unsigned char *prefix;
91 size_t prefix_len;
92 unsigned char *label;
93 size_t label_len;
94 unsigned char *data;
95 size_t data_len;
96 unsigned char *info;
97 size_t info_len;
98 OSSL_FIPS_IND_DECLARE
99 } KDF_HKDF;
100
kdf_hkdf_new(void * provctx)101 static void *kdf_hkdf_new(void *provctx)
102 {
103 KDF_HKDF *ctx;
104
105 if (!ossl_prov_is_running())
106 return NULL;
107
108 if ((ctx = OPENSSL_zalloc(sizeof(*ctx))) != NULL) {
109 ctx->provctx = provctx;
110 OSSL_FIPS_IND_INIT(ctx)
111 }
112 return ctx;
113 }
114
kdf_hkdf_free(void * vctx)115 static void kdf_hkdf_free(void *vctx)
116 {
117 KDF_HKDF *ctx = (KDF_HKDF *)vctx;
118
119 if (ctx != NULL) {
120 kdf_hkdf_reset(ctx);
121 OPENSSL_free(ctx);
122 }
123 }
124
kdf_hkdf_reset(void * vctx)125 static void kdf_hkdf_reset(void *vctx)
126 {
127 KDF_HKDF *ctx = (KDF_HKDF *)vctx;
128 void *provctx = ctx->provctx;
129
130 ossl_prov_digest_reset(&ctx->digest);
131 #ifdef OPENSSL_PEDANTIC_ZEROIZATION
132 OPENSSL_clear_free(ctx->salt, ctx->salt_len);
133 #else
134 OPENSSL_free(ctx->salt);
135 #endif
136 OPENSSL_free(ctx->prefix);
137 OPENSSL_free(ctx->label);
138 OPENSSL_clear_free(ctx->data, ctx->data_len);
139 OPENSSL_clear_free(ctx->key, ctx->key_len);
140 OPENSSL_clear_free(ctx->info, ctx->info_len);
141 memset(ctx, 0, sizeof(*ctx));
142 ctx->provctx = provctx;
143 }
144
kdf_hkdf_dup(void * vctx)145 static void *kdf_hkdf_dup(void *vctx)
146 {
147 const KDF_HKDF *src = (const KDF_HKDF *)vctx;
148 KDF_HKDF *dest;
149
150 dest = kdf_hkdf_new(src->provctx);
151 if (dest != NULL) {
152 if (!ossl_prov_memdup(src->salt, src->salt_len, &dest->salt,
153 &dest->salt_len)
154 || !ossl_prov_memdup(src->key, src->key_len,
155 &dest->key , &dest->key_len)
156 || !ossl_prov_memdup(src->prefix, src->prefix_len,
157 &dest->prefix, &dest->prefix_len)
158 || !ossl_prov_memdup(src->label, src->label_len,
159 &dest->label, &dest->label_len)
160 || !ossl_prov_memdup(src->data, src->data_len,
161 &dest->data, &dest->data_len)
162 || !ossl_prov_memdup(src->info, src->info_len,
163 &dest->info, &dest->info_len)
164 || !ossl_prov_digest_copy(&dest->digest, &src->digest))
165 goto err;
166 dest->mode = src->mode;
167 OSSL_FIPS_IND_COPY(dest, src)
168 }
169 return dest;
170
171 err:
172 kdf_hkdf_free(dest);
173 return NULL;
174 }
175
kdf_hkdf_size(KDF_HKDF * ctx)176 static size_t kdf_hkdf_size(KDF_HKDF *ctx)
177 {
178 int sz;
179 const EVP_MD *md = ossl_prov_digest_md(&ctx->digest);
180
181 if (ctx->mode != EVP_KDF_HKDF_MODE_EXTRACT_ONLY)
182 return SIZE_MAX;
183
184 if (md == NULL) {
185 ERR_raise(ERR_LIB_PROV, PROV_R_MISSING_MESSAGE_DIGEST);
186 return 0;
187 }
188 sz = EVP_MD_get_size(md);
189 if (sz <= 0)
190 return 0;
191
192 return sz;
193 }
194
195 #ifdef FIPS_MODULE
fips_hkdf_key_check_passed(KDF_HKDF * ctx)196 static int fips_hkdf_key_check_passed(KDF_HKDF *ctx)
197 {
198 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(ctx->provctx);
199 int key_approved = ossl_kdf_check_key_size(ctx->key_len);
200
201 if (!key_approved) {
202 if (!OSSL_FIPS_IND_ON_UNAPPROVED(ctx, OSSL_FIPS_IND_SETTABLE0,
203 libctx, "HKDF", "Key size",
204 ossl_fips_config_hkdf_key_check)) {
205 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH);
206 return 0;
207 }
208 }
209 return 1;
210 }
211 #endif
212
kdf_hkdf_derive(void * vctx,unsigned char * key,size_t keylen,const OSSL_PARAM params[])213 static int kdf_hkdf_derive(void *vctx, unsigned char *key, size_t keylen,
214 const OSSL_PARAM params[])
215 {
216 KDF_HKDF *ctx = (KDF_HKDF *)vctx;
217 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(ctx->provctx);
218 const EVP_MD *md;
219
220 if (!ossl_prov_is_running() || !kdf_hkdf_set_ctx_params(ctx, params))
221 return 0;
222
223 md = ossl_prov_digest_md(&ctx->digest);
224 if (md == NULL) {
225 ERR_raise(ERR_LIB_PROV, PROV_R_MISSING_MESSAGE_DIGEST);
226 return 0;
227 }
228 if (ctx->key == NULL) {
229 ERR_raise(ERR_LIB_PROV, PROV_R_MISSING_KEY);
230 return 0;
231 }
232 if (keylen == 0) {
233 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH);
234 return 0;
235 }
236
237 switch (ctx->mode) {
238 case EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND:
239 default:
240 return HKDF(libctx, md, ctx->salt, ctx->salt_len,
241 ctx->key, ctx->key_len, ctx->info, ctx->info_len, key, keylen);
242
243 case EVP_KDF_HKDF_MODE_EXTRACT_ONLY:
244 return HKDF_Extract(libctx, md, ctx->salt, ctx->salt_len,
245 ctx->key, ctx->key_len, key, keylen);
246
247 case EVP_KDF_HKDF_MODE_EXPAND_ONLY:
248 return HKDF_Expand(md, ctx->key, ctx->key_len, ctx->info,
249 ctx->info_len, key, keylen);
250 }
251 }
252
hkdf_common_set_ctx_params(KDF_HKDF * ctx,const OSSL_PARAM params[])253 static int hkdf_common_set_ctx_params(KDF_HKDF *ctx, const OSSL_PARAM params[])
254 {
255 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(ctx->provctx);
256 const OSSL_PARAM *p;
257 int n;
258
259 if (ossl_param_is_empty(params))
260 return 1;
261
262 if (OSSL_PARAM_locate_const(params, OSSL_ALG_PARAM_DIGEST) != NULL) {
263 const EVP_MD *md = NULL;
264
265 if (!ossl_prov_digest_load_from_params(&ctx->digest, params, libctx))
266 return 0;
267
268 md = ossl_prov_digest_md(&ctx->digest);
269 if (EVP_MD_xof(md)) {
270 ERR_raise(ERR_LIB_PROV, PROV_R_XOF_DIGESTS_NOT_ALLOWED);
271 return 0;
272 }
273 }
274
275 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_MODE)) != NULL) {
276 if (p->data_type == OSSL_PARAM_UTF8_STRING) {
277 if (OPENSSL_strcasecmp(p->data, "EXTRACT_AND_EXPAND") == 0) {
278 ctx->mode = EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND;
279 } else if (OPENSSL_strcasecmp(p->data, "EXTRACT_ONLY") == 0) {
280 ctx->mode = EVP_KDF_HKDF_MODE_EXTRACT_ONLY;
281 } else if (OPENSSL_strcasecmp(p->data, "EXPAND_ONLY") == 0) {
282 ctx->mode = EVP_KDF_HKDF_MODE_EXPAND_ONLY;
283 } else {
284 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_MODE);
285 return 0;
286 }
287 } else if (OSSL_PARAM_get_int(p, &n)) {
288 if (n != EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND
289 && n != EVP_KDF_HKDF_MODE_EXTRACT_ONLY
290 && n != EVP_KDF_HKDF_MODE_EXPAND_ONLY) {
291 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_MODE);
292 return 0;
293 }
294 ctx->mode = n;
295 } else {
296 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_MODE);
297 return 0;
298 }
299 }
300
301 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_KEY)) != NULL) {
302 OPENSSL_clear_free(ctx->key, ctx->key_len);
303 ctx->key = NULL;
304 if (!OSSL_PARAM_get_octet_string(p, (void **)&ctx->key, 0,
305 &ctx->key_len))
306 return 0;
307 }
308
309 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_SALT)) != NULL) {
310 OPENSSL_free(ctx->salt);
311 ctx->salt = NULL;
312 if (!OSSL_PARAM_get_octet_string(p, (void **)&ctx->salt, 0,
313 &ctx->salt_len))
314 return 0;
315 }
316
317 return 1;
318 }
319
kdf_hkdf_set_ctx_params(void * vctx,const OSSL_PARAM params[])320 static int kdf_hkdf_set_ctx_params(void *vctx, const OSSL_PARAM params[])
321 {
322 KDF_HKDF *ctx = vctx;
323
324 if (ossl_param_is_empty(params))
325 return 1;
326
327 if (!OSSL_FIPS_IND_SET_CTX_PARAM(ctx, OSSL_FIPS_IND_SETTABLE0, params,
328 OSSL_KDF_PARAM_FIPS_KEY_CHECK))
329 return 0;
330
331 if (!hkdf_common_set_ctx_params(ctx, params))
332 return 0;
333
334 if (ossl_param_get1_concat_octet_string(params, OSSL_KDF_PARAM_INFO,
335 &ctx->info, &ctx->info_len,
336 HKDF_MAXINFO) == 0)
337 return 0;
338
339 #ifdef FIPS_MODULE
340 if (OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_KEY) != NULL)
341 if (!fips_hkdf_key_check_passed(ctx))
342 return 0;
343 #endif
344
345 return 1;
346 }
347
kdf_hkdf_settable_ctx_params(ossl_unused void * ctx,ossl_unused void * provctx)348 static const OSSL_PARAM *kdf_hkdf_settable_ctx_params(ossl_unused void *ctx,
349 ossl_unused void *provctx)
350 {
351 static const OSSL_PARAM known_settable_ctx_params[] = {
352 HKDF_COMMON_SETTABLES,
353 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_INFO, NULL, 0),
354 OSSL_FIPS_IND_SETTABLE_CTX_PARAM(OSSL_KDF_PARAM_FIPS_KEY_CHECK)
355 OSSL_PARAM_END
356 };
357 return known_settable_ctx_params;
358 }
359
hkdf_common_get_ctx_params(KDF_HKDF * ctx,OSSL_PARAM params[])360 static int hkdf_common_get_ctx_params(KDF_HKDF *ctx, OSSL_PARAM params[])
361 {
362 OSSL_PARAM *p;
363
364 if (ossl_param_is_empty(params))
365 return 1;
366
367 if ((p = OSSL_PARAM_locate(params, OSSL_KDF_PARAM_SIZE)) != NULL) {
368 size_t sz = kdf_hkdf_size(ctx);
369
370 if (sz == 0)
371 return 0;
372 if (!OSSL_PARAM_set_size_t(p, sz))
373 return 0;
374 }
375
376 if ((p = OSSL_PARAM_locate(params, OSSL_KDF_PARAM_INFO)) != NULL) {
377 if (ctx->info == NULL || ctx->info_len == 0)
378 p->return_size = 0;
379 else if (!OSSL_PARAM_set_octet_string(p, ctx->info, ctx->info_len))
380 return 0;
381 }
382
383 return 1;
384 }
385
kdf_hkdf_get_ctx_params(void * vctx,OSSL_PARAM params[])386 static int kdf_hkdf_get_ctx_params(void *vctx, OSSL_PARAM params[])
387 {
388 KDF_HKDF *ctx = (KDF_HKDF *)vctx;
389
390 if (ossl_param_is_empty(params))
391 return 1;
392
393 if (!hkdf_common_get_ctx_params(ctx, params))
394 return 0;
395
396 if (!OSSL_FIPS_IND_GET_CTX_PARAM(ctx, params))
397 return 0;
398
399 return 1;
400 }
401
kdf_hkdf_gettable_ctx_params(ossl_unused void * ctx,ossl_unused void * provctx)402 static const OSSL_PARAM *kdf_hkdf_gettable_ctx_params(ossl_unused void *ctx,
403 ossl_unused void *provctx)
404 {
405 static const OSSL_PARAM known_gettable_ctx_params[] = {
406 HKDF_COMMON_GETTABLES,
407 OSSL_FIPS_IND_GETTABLE_CTX_PARAM()
408 OSSL_PARAM_END
409 };
410 return known_gettable_ctx_params;
411 }
412
413 const OSSL_DISPATCH ossl_kdf_hkdf_functions[] = {
414 { OSSL_FUNC_KDF_NEWCTX, (void(*)(void))kdf_hkdf_new },
415 { OSSL_FUNC_KDF_DUPCTX, (void(*)(void))kdf_hkdf_dup },
416 { OSSL_FUNC_KDF_FREECTX, (void(*)(void))kdf_hkdf_free },
417 { OSSL_FUNC_KDF_RESET, (void(*)(void))kdf_hkdf_reset },
418 { OSSL_FUNC_KDF_DERIVE, (void(*)(void))kdf_hkdf_derive },
419 { OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS,
420 (void(*)(void))kdf_hkdf_settable_ctx_params },
421 { OSSL_FUNC_KDF_SET_CTX_PARAMS, (void(*)(void))kdf_hkdf_set_ctx_params },
422 { OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS,
423 (void(*)(void))kdf_hkdf_gettable_ctx_params },
424 { OSSL_FUNC_KDF_GET_CTX_PARAMS, (void(*)(void))kdf_hkdf_get_ctx_params },
425 OSSL_DISPATCH_END
426 };
427
428 /*
429 * Refer to "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)"
430 * Section 2 (https://tools.ietf.org/html/rfc5869#section-2) and
431 * "Cryptographic Extraction and Key Derivation: The HKDF Scheme"
432 * Section 4.2 (https://eprint.iacr.org/2010/264.pdf).
433 *
434 * From the paper:
435 * The scheme HKDF is specified as:
436 * HKDF(XTS, SKM, CTXinfo, L) = K(1) | K(2) | ... | K(t)
437 *
438 * where:
439 * SKM is source key material
440 * XTS is extractor salt (which may be null or constant)
441 * CTXinfo is context information (may be null)
442 * L is the number of key bits to be produced by KDF
443 * k is the output length in bits of the hash function used with HMAC
444 * t = ceil(L/k)
445 * the value K(t) is truncated to its first d = L mod k bits.
446 *
447 * From RFC 5869:
448 * 2.2. Step 1: Extract
449 * HKDF-Extract(salt, IKM) -> PRK
450 * 2.3. Step 2: Expand
451 * HKDF-Expand(PRK, info, L) -> OKM
452 */
HKDF(OSSL_LIB_CTX * libctx,const EVP_MD * evp_md,const unsigned char * salt,size_t salt_len,const unsigned char * ikm,size_t ikm_len,const unsigned char * info,size_t info_len,unsigned char * okm,size_t okm_len)453 static int HKDF(OSSL_LIB_CTX *libctx, const EVP_MD *evp_md,
454 const unsigned char *salt, size_t salt_len,
455 const unsigned char *ikm, size_t ikm_len,
456 const unsigned char *info, size_t info_len,
457 unsigned char *okm, size_t okm_len)
458 {
459 unsigned char prk[EVP_MAX_MD_SIZE];
460 int ret, sz;
461 size_t prk_len;
462
463 sz = EVP_MD_get_size(evp_md);
464 if (sz <= 0)
465 return 0;
466 prk_len = (size_t)sz;
467
468 /* Step 1: HKDF-Extract(salt, IKM) -> PRK */
469 if (!HKDF_Extract(libctx, evp_md,
470 salt, salt_len, ikm, ikm_len, prk, prk_len))
471 return 0;
472
473 /* Step 2: HKDF-Expand(PRK, info, L) -> OKM */
474 ret = HKDF_Expand(evp_md, prk, prk_len, info, info_len, okm, okm_len);
475 OPENSSL_cleanse(prk, sizeof(prk));
476
477 return ret;
478 }
479
480 /*
481 * Refer to "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)"
482 * Section 2.2 (https://tools.ietf.org/html/rfc5869#section-2.2).
483 *
484 * 2.2. Step 1: Extract
485 *
486 * HKDF-Extract(salt, IKM) -> PRK
487 *
488 * Options:
489 * Hash a hash function; HashLen denotes the length of the
490 * hash function output in octets
491 *
492 * Inputs:
493 * salt optional salt value (a non-secret random value);
494 * if not provided, it is set to a string of HashLen zeros.
495 * IKM input keying material
496 *
497 * Output:
498 * PRK a pseudorandom key (of HashLen octets)
499 *
500 * The output PRK is calculated as follows:
501 *
502 * PRK = HMAC-Hash(salt, IKM)
503 */
HKDF_Extract(OSSL_LIB_CTX * libctx,const EVP_MD * evp_md,const unsigned char * salt,size_t salt_len,const unsigned char * ikm,size_t ikm_len,unsigned char * prk,size_t prk_len)504 static int HKDF_Extract(OSSL_LIB_CTX *libctx, const EVP_MD *evp_md,
505 const unsigned char *salt, size_t salt_len,
506 const unsigned char *ikm, size_t ikm_len,
507 unsigned char *prk, size_t prk_len)
508 {
509 int sz = EVP_MD_get_size(evp_md);
510
511 if (sz <= 0)
512 return 0;
513 if (prk_len != (size_t)sz) {
514 ERR_raise(ERR_LIB_PROV, PROV_R_WRONG_OUTPUT_BUFFER_SIZE);
515 return 0;
516 }
517 /* calc: PRK = HMAC-Hash(salt, IKM) */
518 return
519 EVP_Q_mac(libctx, "HMAC", NULL, EVP_MD_get0_name(evp_md), NULL, salt,
520 salt_len, ikm, ikm_len, prk, EVP_MD_get_size(evp_md), NULL)
521 != NULL;
522 }
523
524 /*
525 * Refer to "HMAC-based Extract-and-Expand Key Derivation Function (HKDF)"
526 * Section 2.3 (https://tools.ietf.org/html/rfc5869#section-2.3).
527 *
528 * 2.3. Step 2: Expand
529 *
530 * HKDF-Expand(PRK, info, L) -> OKM
531 *
532 * Options:
533 * Hash a hash function; HashLen denotes the length of the
534 * hash function output in octets
535 *
536 * Inputs:
537 * PRK a pseudorandom key of at least HashLen octets
538 * (usually, the output from the extract step)
539 * info optional context and application specific information
540 * (can be a zero-length string)
541 * L length of output keying material in octets
542 * (<= 255*HashLen)
543 *
544 * Output:
545 * OKM output keying material (of L octets)
546 *
547 * The output OKM is calculated as follows:
548 *
549 * N = ceil(L/HashLen)
550 * T = T(1) | T(2) | T(3) | ... | T(N)
551 * OKM = first L octets of T
552 *
553 * where:
554 * T(0) = empty string (zero length)
555 * T(1) = HMAC-Hash(PRK, T(0) | info | 0x01)
556 * T(2) = HMAC-Hash(PRK, T(1) | info | 0x02)
557 * T(3) = HMAC-Hash(PRK, T(2) | info | 0x03)
558 * ...
559 *
560 * (where the constant concatenated to the end of each T(n) is a
561 * single octet.)
562 */
HKDF_Expand(const EVP_MD * evp_md,const unsigned char * prk,size_t prk_len,const unsigned char * info,size_t info_len,unsigned char * okm,size_t okm_len)563 static int HKDF_Expand(const EVP_MD *evp_md,
564 const unsigned char *prk, size_t prk_len,
565 const unsigned char *info, size_t info_len,
566 unsigned char *okm, size_t okm_len)
567 {
568 HMAC_CTX *hmac;
569 int ret = 0, sz;
570 unsigned int i;
571 unsigned char prev[EVP_MAX_MD_SIZE];
572 size_t done_len = 0, dig_len, n;
573
574 sz = EVP_MD_get_size(evp_md);
575 if (sz <= 0)
576 return 0;
577 dig_len = (size_t)sz;
578
579 /* calc: N = ceil(L/HashLen) */
580 n = okm_len / dig_len;
581 if (okm_len % dig_len)
582 n++;
583
584 if (n > 255 || okm == NULL)
585 return 0;
586
587 if ((hmac = HMAC_CTX_new()) == NULL)
588 return 0;
589
590 if (!HMAC_Init_ex(hmac, prk, prk_len, evp_md, NULL))
591 goto err;
592
593 for (i = 1; i <= n; i++) {
594 size_t copy_len;
595 const unsigned char ctr = i;
596
597 /* calc: T(i) = HMAC-Hash(PRK, T(i - 1) | info | i) */
598 if (i > 1) {
599 if (!HMAC_Init_ex(hmac, NULL, 0, NULL, NULL))
600 goto err;
601
602 if (!HMAC_Update(hmac, prev, dig_len))
603 goto err;
604 }
605
606 if (!HMAC_Update(hmac, info, info_len))
607 goto err;
608
609 if (!HMAC_Update(hmac, &ctr, 1))
610 goto err;
611
612 if (!HMAC_Final(hmac, prev, NULL))
613 goto err;
614
615 copy_len = (dig_len > okm_len - done_len) ?
616 okm_len - done_len :
617 dig_len;
618
619 memcpy(okm + done_len, prev, copy_len);
620
621 done_len += copy_len;
622 }
623 ret = 1;
624
625 err:
626 OPENSSL_cleanse(prev, sizeof(prev));
627 HMAC_CTX_free(hmac);
628 return ret;
629 }
630
631 /*
632 * TLS uses slight variations of the above and for FIPS validation purposes,
633 * they need to be present here.
634 * Refer to RFC 8446 section 7 for specific details.
635 */
636
637 /*
638 * Given a |secret|; a |label| of length |labellen|; and |data| of length
639 * |datalen| (e.g. typically a hash of the handshake messages), derive a new
640 * secret |outlen| bytes long and store it in the location pointed to be |out|.
641 * The |data| value may be zero length. Returns 1 on success and 0 on failure.
642 */
prov_tls13_hkdf_expand(const EVP_MD * md,const unsigned char * key,size_t keylen,const unsigned char * prefix,size_t prefixlen,const unsigned char * label,size_t labellen,const unsigned char * data,size_t datalen,unsigned char * out,size_t outlen)643 static int prov_tls13_hkdf_expand(const EVP_MD *md,
644 const unsigned char *key, size_t keylen,
645 const unsigned char *prefix, size_t prefixlen,
646 const unsigned char *label, size_t labellen,
647 const unsigned char *data, size_t datalen,
648 unsigned char *out, size_t outlen)
649 {
650 size_t hkdflabellen;
651 unsigned char hkdflabel[HKDF_MAXBUF];
652 WPACKET pkt;
653
654 /*
655 * 2 bytes for length of derived secret + 1 byte for length of combined
656 * prefix and label + bytes for the label itself + 1 byte length of hash
657 * + bytes for the hash itself. We've got the maximum the KDF can handle
658 * which should always be sufficient.
659 */
660 if (!WPACKET_init_static_len(&pkt, hkdflabel, sizeof(hkdflabel), 0)
661 || !WPACKET_put_bytes_u16(&pkt, outlen)
662 || !WPACKET_start_sub_packet_u8(&pkt)
663 || !WPACKET_memcpy(&pkt, prefix, prefixlen)
664 || !WPACKET_memcpy(&pkt, label, labellen)
665 || !WPACKET_close(&pkt)
666 || !WPACKET_sub_memcpy_u8(&pkt, data, (data == NULL) ? 0 : datalen)
667 || !WPACKET_get_total_written(&pkt, &hkdflabellen)
668 || !WPACKET_finish(&pkt)) {
669 WPACKET_cleanup(&pkt);
670 return 0;
671 }
672
673 return HKDF_Expand(md, key, keylen, hkdflabel, hkdflabellen,
674 out, outlen);
675 }
676
prov_tls13_hkdf_generate_secret(OSSL_LIB_CTX * libctx,const EVP_MD * md,const unsigned char * prevsecret,size_t prevsecretlen,const unsigned char * insecret,size_t insecretlen,const unsigned char * prefix,size_t prefixlen,const unsigned char * label,size_t labellen,unsigned char * out,size_t outlen)677 static int prov_tls13_hkdf_generate_secret(OSSL_LIB_CTX *libctx,
678 const EVP_MD *md,
679 const unsigned char *prevsecret,
680 size_t prevsecretlen,
681 const unsigned char *insecret,
682 size_t insecretlen,
683 const unsigned char *prefix,
684 size_t prefixlen,
685 const unsigned char *label,
686 size_t labellen,
687 unsigned char *out, size_t outlen)
688 {
689 size_t mdlen;
690 int ret;
691 unsigned char preextractsec[EVP_MAX_MD_SIZE];
692 /* Always filled with zeros */
693 static const unsigned char default_zeros[EVP_MAX_MD_SIZE];
694
695 ret = EVP_MD_get_size(md);
696 /* Ensure cast to size_t is safe */
697 if (ret <= 0)
698 return 0;
699 mdlen = (size_t)ret;
700
701 if (insecret == NULL) {
702 insecret = default_zeros;
703 insecretlen = mdlen;
704 }
705 if (prevsecret == NULL) {
706 prevsecret = default_zeros;
707 prevsecretlen = mdlen;
708 } else {
709 EVP_MD_CTX *mctx = EVP_MD_CTX_new();
710 unsigned char hash[EVP_MAX_MD_SIZE];
711
712 /* The pre-extract derive step uses a hash of no messages */
713 if (mctx == NULL
714 || EVP_DigestInit_ex(mctx, md, NULL) <= 0
715 || EVP_DigestFinal_ex(mctx, hash, NULL) <= 0) {
716 EVP_MD_CTX_free(mctx);
717 return 0;
718 }
719 EVP_MD_CTX_free(mctx);
720
721 /* Generate the pre-extract secret */
722 if (!prov_tls13_hkdf_expand(md, prevsecret, prevsecretlen,
723 prefix, prefixlen, label, labellen,
724 hash, mdlen, preextractsec, mdlen))
725 return 0;
726 prevsecret = preextractsec;
727 prevsecretlen = mdlen;
728 }
729
730 ret = HKDF_Extract(libctx, md, prevsecret, prevsecretlen,
731 insecret, insecretlen, out, outlen);
732
733 if (prevsecret == preextractsec)
734 OPENSSL_cleanse(preextractsec, mdlen);
735 return ret;
736 }
737
738 #ifdef FIPS_MODULE
fips_tls1_3_digest_check_passed(KDF_HKDF * ctx,const EVP_MD * md)739 static int fips_tls1_3_digest_check_passed(KDF_HKDF *ctx, const EVP_MD *md)
740 {
741 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(ctx->provctx);
742 /*
743 * Perform digest check
744 *
745 * According to RFC 8446 appendix B.4, the valid hash functions are
746 * specified in FIPS 180-4. However, it only lists SHA2-256 and SHA2-384 in
747 * the table. ACVP also only lists the same set of hash functions.
748 */
749 int digest_unapproved = !EVP_MD_is_a(md, SN_sha256)
750 && !EVP_MD_is_a(md, SN_sha384);
751
752 if (digest_unapproved) {
753 if (!OSSL_FIPS_IND_ON_UNAPPROVED(ctx, OSSL_FIPS_IND_SETTABLE0,
754 libctx, "TLS13 KDF", "Digest",
755 ossl_fips_config_tls13_kdf_digest_check)) {
756 ERR_raise(ERR_LIB_PROV, PROV_R_DIGEST_NOT_ALLOWED);
757 return 0;
758 }
759 }
760 return 1;
761 }
762
763 /*
764 * Calculate the correct length of the secret key.
765 *
766 * RFC 8446:
767 * If a given secret is not available, then the 0-value consisting of a
768 * string of Hash.length bytes set to zeros is used.
769 */
fips_tls1_3_key_size(KDF_HKDF * ctx)770 static size_t fips_tls1_3_key_size(KDF_HKDF *ctx)
771 {
772 const EVP_MD *md = ossl_prov_digest_md(&ctx->digest);
773 size_t key_size = 0;
774
775 if (ctx->key != NULL)
776 key_size = ctx->key_len;
777 else if (md != NULL)
778 key_size = EVP_MD_size(md);
779
780 return key_size;
781 }
782
fips_tls1_3_key_check_passed(KDF_HKDF * ctx)783 static int fips_tls1_3_key_check_passed(KDF_HKDF *ctx)
784 {
785 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(ctx->provctx);
786 int key_approved = ossl_kdf_check_key_size(fips_tls1_3_key_size(ctx));
787
788 if (!key_approved) {
789 if (!OSSL_FIPS_IND_ON_UNAPPROVED(ctx, OSSL_FIPS_IND_SETTABLE1,
790 libctx, "TLS13 KDF", "Key size",
791 ossl_fips_config_tls13_kdf_key_check)) {
792 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH);
793 return 0;
794 }
795 }
796 return 1;
797 }
798 #endif
799
kdf_tls1_3_derive(void * vctx,unsigned char * key,size_t keylen,const OSSL_PARAM params[])800 static int kdf_tls1_3_derive(void *vctx, unsigned char *key, size_t keylen,
801 const OSSL_PARAM params[])
802 {
803 KDF_HKDF *ctx = (KDF_HKDF *)vctx;
804 const EVP_MD *md;
805
806 if (!ossl_prov_is_running() || !kdf_tls1_3_set_ctx_params(ctx, params))
807 return 0;
808
809 md = ossl_prov_digest_md(&ctx->digest);
810 if (md == NULL) {
811 ERR_raise(ERR_LIB_PROV, PROV_R_MISSING_MESSAGE_DIGEST);
812 return 0;
813 }
814
815 switch (ctx->mode) {
816 default:
817 return 0;
818
819 case EVP_KDF_HKDF_MODE_EXTRACT_ONLY:
820 return prov_tls13_hkdf_generate_secret(PROV_LIBCTX_OF(ctx->provctx),
821 md,
822 ctx->salt, ctx->salt_len,
823 ctx->key, ctx->key_len,
824 ctx->prefix, ctx->prefix_len,
825 ctx->label, ctx->label_len,
826 key, keylen);
827
828 case EVP_KDF_HKDF_MODE_EXPAND_ONLY:
829 return prov_tls13_hkdf_expand(md, ctx->key, ctx->key_len,
830 ctx->prefix, ctx->prefix_len,
831 ctx->label, ctx->label_len,
832 ctx->data, ctx->data_len,
833 key, keylen);
834 }
835 }
836
kdf_tls1_3_set_ctx_params(void * vctx,const OSSL_PARAM params[])837 static int kdf_tls1_3_set_ctx_params(void *vctx, const OSSL_PARAM params[])
838 {
839 const OSSL_PARAM *p;
840 KDF_HKDF *ctx = vctx;
841
842 if (ossl_param_is_empty(params))
843 return 1;
844
845 if (!OSSL_FIPS_IND_SET_CTX_PARAM(ctx, OSSL_FIPS_IND_SETTABLE0, params,
846 OSSL_KDF_PARAM_FIPS_DIGEST_CHECK))
847 return 0;
848 if (!OSSL_FIPS_IND_SET_CTX_PARAM(ctx, OSSL_FIPS_IND_SETTABLE1, params,
849 OSSL_KDF_PARAM_FIPS_KEY_CHECK))
850 return 0;
851
852 if (!hkdf_common_set_ctx_params(ctx, params))
853 return 0;
854
855 if (ctx->mode == EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND) {
856 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_MODE);
857 return 0;
858 }
859
860 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_PREFIX)) != NULL) {
861 OPENSSL_free(ctx->prefix);
862 ctx->prefix = NULL;
863 if (!OSSL_PARAM_get_octet_string(p, (void **)&ctx->prefix, 0,
864 &ctx->prefix_len))
865 return 0;
866 }
867
868 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_LABEL)) != NULL) {
869 OPENSSL_free(ctx->label);
870 ctx->label = NULL;
871 if (!OSSL_PARAM_get_octet_string(p, (void **)&ctx->label, 0,
872 &ctx->label_len))
873 return 0;
874 }
875
876 OPENSSL_clear_free(ctx->data, ctx->data_len);
877 ctx->data = NULL;
878 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_DATA)) != NULL
879 && !OSSL_PARAM_get_octet_string(p, (void **)&ctx->data, 0,
880 &ctx->data_len))
881 return 0;
882
883 #ifdef FIPS_MODULE
884 if (OSSL_PARAM_locate_const(params, OSSL_ALG_PARAM_DIGEST) != NULL) {
885 const EVP_MD *md = ossl_prov_digest_md(&ctx->digest);
886
887 if (!fips_tls1_3_digest_check_passed(ctx, md))
888 return 0;
889 }
890
891 if ((p = OSSL_PARAM_locate_const(params, OSSL_KDF_PARAM_KEY)) != NULL)
892 if (!fips_tls1_3_key_check_passed(ctx))
893 return 0;
894 #endif
895
896 return 1;
897 }
898
kdf_tls1_3_settable_ctx_params(ossl_unused void * ctx,ossl_unused void * provctx)899 static const OSSL_PARAM *kdf_tls1_3_settable_ctx_params(ossl_unused void *ctx,
900 ossl_unused void *provctx)
901 {
902 static const OSSL_PARAM known_settable_ctx_params[] = {
903 HKDF_COMMON_SETTABLES,
904 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_PREFIX, NULL, 0),
905 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_LABEL, NULL, 0),
906 OSSL_PARAM_octet_string(OSSL_KDF_PARAM_DATA, NULL, 0),
907 OSSL_FIPS_IND_SETTABLE_CTX_PARAM(OSSL_KDF_PARAM_FIPS_DIGEST_CHECK)
908 OSSL_FIPS_IND_SETTABLE_CTX_PARAM(OSSL_KDF_PARAM_FIPS_KEY_CHECK)
909 OSSL_PARAM_END
910 };
911 return known_settable_ctx_params;
912 }
913
kdf_tls1_3_get_ctx_params(void * vctx,OSSL_PARAM params[])914 static int kdf_tls1_3_get_ctx_params(void *vctx, OSSL_PARAM params[])
915 {
916 KDF_HKDF *ctx = (KDF_HKDF *)vctx;
917
918 if (ossl_param_is_empty(params))
919 return 1;
920
921 if (!hkdf_common_get_ctx_params(ctx, params))
922 return 0;
923
924 if (!OSSL_FIPS_IND_GET_CTX_PARAM(ctx, params))
925 return 0;
926
927 return 1;
928 }
929
kdf_tls1_3_gettable_ctx_params(ossl_unused void * ctx,ossl_unused void * provctx)930 static const OSSL_PARAM *kdf_tls1_3_gettable_ctx_params(ossl_unused void *ctx,
931 ossl_unused void *provctx)
932 {
933 static const OSSL_PARAM known_gettable_ctx_params[] = {
934 HKDF_COMMON_GETTABLES,
935 OSSL_FIPS_IND_GETTABLE_CTX_PARAM()
936 OSSL_PARAM_END
937 };
938 return known_gettable_ctx_params;
939 }
940
941 const OSSL_DISPATCH ossl_kdf_tls1_3_kdf_functions[] = {
942 { OSSL_FUNC_KDF_NEWCTX, (void(*)(void))kdf_hkdf_new },
943 { OSSL_FUNC_KDF_DUPCTX, (void(*)(void))kdf_hkdf_dup },
944 { OSSL_FUNC_KDF_FREECTX, (void(*)(void))kdf_hkdf_free },
945 { OSSL_FUNC_KDF_RESET, (void(*)(void))kdf_hkdf_reset },
946 { OSSL_FUNC_KDF_DERIVE, (void(*)(void))kdf_tls1_3_derive },
947 { OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS,
948 (void(*)(void))kdf_tls1_3_settable_ctx_params },
949 { OSSL_FUNC_KDF_SET_CTX_PARAMS, (void(*)(void))kdf_tls1_3_set_ctx_params },
950 { OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS,
951 (void(*)(void))kdf_tls1_3_gettable_ctx_params },
952 { OSSL_FUNC_KDF_GET_CTX_PARAMS, (void(*)(void))kdf_tls1_3_get_ctx_params },
953 OSSL_DISPATCH_END
954 };
955