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 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 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 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 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 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 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 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 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 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 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 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 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 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 */ 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 */ 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 */ 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 */ 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 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 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 */ 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 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 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 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 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 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 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