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