1/* 2 * Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 3 * Copyright 2019 Red Hat, Inc. 4 * 5 * Licensed under the Apache License 2.0 (the "License"). You may not use 6 * this file except in compliance with the License. You can obtain a copy 7 * in the file LICENSE in the source distribution or at 8 * https://www.openssl.org/source/license.html 9 */ 10{- 11use OpenSSL::paramnames qw(produce_param_decoder); 12-} 13 14/* 15 * This implements https://csrc.nist.gov/publications/detail/sp/800-108/final 16 * section 5.1 ("counter mode") and section 5.2 ("feedback mode") in both HMAC 17 * and CMAC. That document does not name the KDFs it defines; the name is 18 * derived from 19 * https://csrc.nist.gov/Projects/Cryptographic-Algorithm-Validation-Program/Key-Derivation 20 * 21 * Note that section 5.3 ("double-pipeline mode") is not implemented, though 22 * it would be possible to do so in the future. 23 * 24 * These versions all assume the counter is used. It would be relatively 25 * straightforward to expose a configuration handle should the need arise. 26 * 27 * Variable names attempt to match those of SP800-108. 28 */ 29 30#include <stdarg.h> 31#include <stdlib.h> 32#include <string.h> 33 34#include <openssl/core_names.h> 35#include <openssl/evp.h> 36#include <openssl/hmac.h> 37#include <openssl/kdf.h> 38#include <openssl/params.h> 39#include <openssl/proverr.h> 40 41#include "internal/cryptlib.h" 42#include "crypto/evp.h" 43#include "internal/numbers.h" 44#include "internal/endian.h" 45#include "prov/implementations.h" 46#include "prov/provider_ctx.h" 47#include "prov/provider_util.h" 48#include "prov/providercommon.h" 49#include "prov/securitycheck.h" 50#include "internal/e_os.h" 51#include "internal/params.h" 52 53#define ossl_min(a, b) ((a) < (b)) ? (a) : (b) 54 55#define KBKDF_MAX_INFOS 5 56 57typedef enum { 58 COUNTER = 0, 59 FEEDBACK 60} kbkdf_mode; 61 62/* Our context structure. */ 63typedef struct { 64 void *provctx; 65 kbkdf_mode mode; 66 EVP_MAC_CTX *ctx_init; 67 68 /* Names are lowercased versions of those found in SP800-108. */ 69 int r; 70 unsigned char *ki; 71 size_t ki_len; 72 unsigned char *label; 73 size_t label_len; 74 unsigned char *context; 75 size_t context_len; 76 unsigned char *iv; 77 size_t iv_len; 78 int use_l; 79 int is_kmac; 80 int use_separator; 81 OSSL_FIPS_IND_DECLARE 82} KBKDF; 83 84/* Definitions needed for typechecking. */ 85static OSSL_FUNC_kdf_newctx_fn kbkdf_new; 86static OSSL_FUNC_kdf_dupctx_fn kbkdf_dup; 87static OSSL_FUNC_kdf_freectx_fn kbkdf_free; 88static OSSL_FUNC_kdf_reset_fn kbkdf_reset; 89static OSSL_FUNC_kdf_derive_fn kbkdf_derive; 90static OSSL_FUNC_kdf_settable_ctx_params_fn kbkdf_settable_ctx_params; 91static OSSL_FUNC_kdf_set_ctx_params_fn kbkdf_set_ctx_params; 92static OSSL_FUNC_kdf_gettable_ctx_params_fn kbkdf_gettable_ctx_params; 93static OSSL_FUNC_kdf_get_ctx_params_fn kbkdf_get_ctx_params; 94 95/* Not all platforms have htobe32(). */ 96static uint32_t be32(uint32_t host) 97{ 98 uint32_t big = 0; 99 DECLARE_IS_ENDIAN; 100 101 if (!IS_LITTLE_ENDIAN) 102 return host; 103 104 big |= (host & 0xff000000) >> 24; 105 big |= (host & 0x00ff0000) >> 8; 106 big |= (host & 0x0000ff00) << 8; 107 big |= (host & 0x000000ff) << 24; 108 return big; 109} 110 111static void init(KBKDF *ctx) 112{ 113 ctx->r = 32; 114 ctx->use_l = 1; 115 ctx->use_separator = 1; 116 ctx->is_kmac = 0; 117} 118 119static void *kbkdf_new(void *provctx) 120{ 121 KBKDF *ctx; 122 123 if (!ossl_prov_is_running()) 124 return NULL; 125 126 ctx = OPENSSL_zalloc(sizeof(*ctx)); 127 if (ctx == NULL) 128 return NULL; 129 130 ctx->provctx = provctx; 131 OSSL_FIPS_IND_INIT(ctx) 132 init(ctx); 133 return ctx; 134} 135 136static void kbkdf_free(void *vctx) 137{ 138 KBKDF *ctx = (KBKDF *)vctx; 139 140 if (ctx != NULL) { 141 kbkdf_reset(ctx); 142 OPENSSL_free(ctx); 143 } 144} 145 146static void kbkdf_reset(void *vctx) 147{ 148 KBKDF *ctx = (KBKDF *)vctx; 149 void *provctx = ctx->provctx; 150 151 EVP_MAC_CTX_free(ctx->ctx_init); 152 OPENSSL_clear_free(ctx->context, ctx->context_len); 153 OPENSSL_clear_free(ctx->label, ctx->label_len); 154 OPENSSL_clear_free(ctx->ki, ctx->ki_len); 155 OPENSSL_clear_free(ctx->iv, ctx->iv_len); 156 memset(ctx, 0, sizeof(*ctx)); 157 ctx->provctx = provctx; 158 init(ctx); 159} 160 161static void *kbkdf_dup(void *vctx) 162{ 163 const KBKDF *src = (const KBKDF *)vctx; 164 KBKDF *dest; 165 166 dest = kbkdf_new(src->provctx); 167 if (dest != NULL) { 168 dest->ctx_init = EVP_MAC_CTX_dup(src->ctx_init); 169 if (dest->ctx_init == NULL 170 || !ossl_prov_memdup(src->ki, src->ki_len, 171 &dest->ki, &dest->ki_len) 172 || !ossl_prov_memdup(src->label, src->label_len, 173 &dest->label, &dest->label_len) 174 || !ossl_prov_memdup(src->context, src->context_len, 175 &dest->context, &dest->context_len) 176 || !ossl_prov_memdup(src->iv, src->iv_len, 177 &dest->iv, &dest->iv_len)) 178 goto err; 179 dest->mode = src->mode; 180 dest->r = src->r; 181 dest->use_l = src->use_l; 182 dest->use_separator = src->use_separator; 183 dest->is_kmac = src->is_kmac; 184 OSSL_FIPS_IND_COPY(dest, src) 185 } 186 return dest; 187 188 err: 189 kbkdf_free(dest); 190 return NULL; 191} 192 193#ifdef FIPS_MODULE 194static int fips_kbkdf_key_check_passed(KBKDF *ctx) 195{ 196 OSSL_LIB_CTX *libctx = PROV_LIBCTX_OF(ctx->provctx); 197 int key_approved = ossl_kdf_check_key_size(ctx->ki_len); 198 199 if (!key_approved) { 200 if (!OSSL_FIPS_IND_ON_UNAPPROVED(ctx, OSSL_FIPS_IND_SETTABLE0, 201 libctx, "KBKDF", "Key size", 202 ossl_fips_config_kbkdf_key_check)) { 203 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH); 204 return 0; 205 } 206 } 207 return 1; 208} 209#endif 210 211/* SP800-108 section 5.1 or section 5.2 depending on mode. */ 212static int derive(EVP_MAC_CTX *ctx_init, kbkdf_mode mode, unsigned char *iv, 213 size_t iv_len, unsigned char *label, size_t label_len, 214 unsigned char *context, size_t context_len, 215 unsigned char *k_i, size_t h, uint32_t l, int has_separator, 216 unsigned char *ko, size_t ko_len, int r) 217{ 218 int ret = 0; 219 EVP_MAC_CTX *ctx = NULL; 220 size_t written = 0, to_write, k_i_len = iv_len; 221 const unsigned char zero = 0; 222 uint32_t counter, i; 223 /* 224 * From SP800-108: 225 * The fixed input data is a concatenation of a Label, 226 * a separation indicator 0x00, the Context, and L. 227 * One or more of these fixed input data fields may be omitted. 228 * 229 * has_separator == 0 means that the separator is omitted. 230 * Passing a value of l == 0 means that L is omitted. 231 * The Context and L are omitted automatically if a NULL buffer is passed. 232 */ 233 int has_l = (l != 0); 234 235 /* Setup K(0) for feedback mode. */ 236 if (iv_len > 0) 237 memcpy(k_i, iv, iv_len); 238 239 for (counter = 1; written < ko_len; counter++) { 240 i = be32(counter); 241 242 ctx = EVP_MAC_CTX_dup(ctx_init); 243 if (ctx == NULL) 244 goto done; 245 246 /* Perform feedback, if appropriate. */ 247 if (mode == FEEDBACK && !EVP_MAC_update(ctx, k_i, k_i_len)) 248 goto done; 249 250 if (!EVP_MAC_update(ctx, 4 - (r / 8) + (unsigned char *)&i, r / 8) 251 || !EVP_MAC_update(ctx, label, label_len) 252 || (has_separator && !EVP_MAC_update(ctx, &zero, 1)) 253 || !EVP_MAC_update(ctx, context, context_len) 254 || (has_l && !EVP_MAC_update(ctx, (unsigned char *)&l, 4)) 255 || !EVP_MAC_final(ctx, k_i, NULL, h)) 256 goto done; 257 258 to_write = ko_len - written; 259 memcpy(ko + written, k_i, ossl_min(to_write, h)); 260 written += h; 261 262 k_i_len = h; 263 EVP_MAC_CTX_free(ctx); 264 ctx = NULL; 265 } 266 267 ret = 1; 268done: 269 EVP_MAC_CTX_free(ctx); 270 return ret; 271} 272 273/* This must be run before the key is set */ 274static int kmac_init(EVP_MAC_CTX *ctx, const unsigned char *custom, size_t customlen) 275{ 276 OSSL_PARAM params[2]; 277 278 if (custom == NULL || customlen == 0) 279 return 1; 280 params[0] = OSSL_PARAM_construct_octet_string(OSSL_MAC_PARAM_CUSTOM, 281 (void *)custom, customlen); 282 params[1] = OSSL_PARAM_construct_end(); 283 return EVP_MAC_CTX_set_params(ctx, params) > 0; 284} 285 286static int kmac_derive(EVP_MAC_CTX *ctx, unsigned char *out, size_t outlen, 287 const unsigned char *context, size_t contextlen) 288{ 289 OSSL_PARAM params[2]; 290 291 params[0] = OSSL_PARAM_construct_size_t(OSSL_MAC_PARAM_SIZE, &outlen); 292 params[1] = OSSL_PARAM_construct_end(); 293 return EVP_MAC_CTX_set_params(ctx, params) > 0 294 && EVP_MAC_update(ctx, context, contextlen) 295 && EVP_MAC_final(ctx, out, NULL, outlen); 296} 297 298static int kbkdf_derive(void *vctx, unsigned char *key, size_t keylen, 299 const OSSL_PARAM params[]) 300{ 301 KBKDF *ctx = (KBKDF *)vctx; 302 int ret = 0; 303 unsigned char *k_i = NULL; 304 uint32_t l = 0; 305 size_t h = 0; 306 uint64_t counter_max; 307 308 if (!ossl_prov_is_running() || !kbkdf_set_ctx_params(ctx, params)) 309 return 0; 310 311 /* label, context, and iv are permitted to be empty. Check everything 312 * else. */ 313 if (ctx->ctx_init == NULL) { 314 if (ctx->ki_len == 0 || ctx->ki == NULL) { 315 ERR_raise(ERR_LIB_PROV, PROV_R_NO_KEY_SET); 316 return 0; 317 } 318 /* Could either be missing MAC or missing message digest or missing 319 * cipher - arbitrarily, I pick this one. */ 320 ERR_raise(ERR_LIB_PROV, PROV_R_MISSING_MAC); 321 return 0; 322 } 323 324 /* Fail if the output length is zero */ 325 if (keylen == 0) { 326 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH); 327 return 0; 328 } 329 330 if (ctx->is_kmac) { 331 ret = kmac_derive(ctx->ctx_init, key, keylen, 332 ctx->context, ctx->context_len); 333 goto done; 334 } 335 336 h = EVP_MAC_CTX_get_mac_size(ctx->ctx_init); 337 if (h == 0) 338 goto done; 339 340 if (ctx->iv_len != 0 && ctx->iv_len != h) { 341 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_SEED_LENGTH); 342 goto done; 343 } 344 345 if (ctx->mode == COUNTER) { 346 /* Fail if keylen is too large for r */ 347 counter_max = (uint64_t)1 << (uint64_t)ctx->r; 348 if ((uint64_t)(keylen / h) >= counter_max) { 349 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_KEY_LENGTH); 350 goto done; 351 } 352 } 353 354 if (ctx->use_l != 0) 355 l = be32((uint32_t)(keylen * 8)); 356 357 k_i = OPENSSL_zalloc(h); 358 if (k_i == NULL) 359 goto done; 360 361 ret = derive(ctx->ctx_init, ctx->mode, ctx->iv, ctx->iv_len, ctx->label, 362 ctx->label_len, ctx->context, ctx->context_len, k_i, h, l, 363 ctx->use_separator, key, keylen, ctx->r); 364done: 365 if (ret != 1) 366 OPENSSL_cleanse(key, keylen); 367 OPENSSL_clear_free(k_i, h); 368 return ret; 369} 370 371{- produce_param_decoder('kbkdf_set_ctx_params', 372 (['KDF_PARAM_INFO', 'info', 'octet_string', KBKDF_MAX_INFOS], 373 ['KDF_PARAM_SALT', 'salt', 'octet_string'], 374 ['KDF_PARAM_KEY', 'key', 'octet_string'], 375 ['KDF_PARAM_SEED', 'seed', 'octet_string'], 376 ['KDF_PARAM_DIGEST', 'digest', 'utf8_string'], 377 ['KDF_PARAM_CIPHER', 'cipher', 'utf8_string'], 378 ['KDF_PARAM_MAC', 'mac', 'utf8_string'], 379 ['KDF_PARAM_MODE', 'mode', 'utf8_string'], 380 ['KDF_PARAM_PROPERTIES', 'propq', 'utf8_string'], 381 ['ALG_PARAM_ENGINE', 'engine', 'utf8_string', 'hidden'], 382 ['KDF_PARAM_KBKDF_USE_L', 'use_l', 'int'], 383 ['KDF_PARAM_KBKDF_USE_SEPARATOR', 'sep', 'int'], 384 ['KDF_PARAM_KBKDF_R', 'r', 'int'], 385 ['KDF_PARAM_FIPS_KEY_CHECK', 'ind_k', 'int', 'fips'], 386 )); -} 387 388static int kbkdf_set_ctx_params(void *vctx, const OSSL_PARAM params[]) 389{ 390 KBKDF *ctx = (KBKDF *)vctx; 391 OSSL_LIB_CTX *libctx; 392 struct kbkdf_set_ctx_params_st p; 393 const char *s; 394 395 if (ctx == NULL || !kbkdf_set_ctx_params_decoder(params, &p)) 396 return 0; 397 398 libctx = PROV_LIBCTX_OF(ctx->provctx); 399 400 if (!OSSL_FIPS_IND_SET_CTX_FROM_PARAM(ctx, OSSL_FIPS_IND_SETTABLE0, p.ind_k)) 401 return 0; 402 403 if (!ossl_prov_macctx_load(&ctx->ctx_init, p.mac, p.cipher, 404 p.digest, p.propq, p.engine, 405 NULL, NULL, NULL, libctx)) 406 return 0; 407 408 if (ctx->ctx_init != NULL) { 409 ctx->is_kmac = 0; 410 if (EVP_MAC_is_a(EVP_MAC_CTX_get0_mac(ctx->ctx_init), 411 OSSL_MAC_NAME_KMAC128) 412 || EVP_MAC_is_a(EVP_MAC_CTX_get0_mac(ctx->ctx_init), 413 OSSL_MAC_NAME_KMAC256)) { 414 ctx->is_kmac = 1; 415 } else if (!EVP_MAC_is_a(EVP_MAC_CTX_get0_mac(ctx->ctx_init), 416 OSSL_MAC_NAME_HMAC) 417 && !EVP_MAC_is_a(EVP_MAC_CTX_get0_mac(ctx->ctx_init), 418 OSSL_MAC_NAME_CMAC)) { 419 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_MAC); 420 return 0; 421 } 422 } 423 424 if (p.mode != NULL) { 425 if (!OSSL_PARAM_get_utf8_string_ptr(p.mode, &s)) 426 return 0; 427 if (OPENSSL_strncasecmp("counter", s, p.mode->data_size) == 0) { 428 ctx->mode = COUNTER; 429 } else if (OPENSSL_strncasecmp("feedback", s, p.mode->data_size) == 0) { 430 ctx->mode = FEEDBACK; 431 } else { 432 ERR_raise(ERR_LIB_PROV, PROV_R_INVALID_MODE); 433 return 0; 434 } 435 } 436 437 if (ossl_param_get1_octet_string_from_param(p.key, &ctx->ki, 438 &ctx->ki_len) == 0) 439 return 0; 440#ifdef FIPS_MODULE 441 if (p.key != NULL && !fips_kbkdf_key_check_passed(ctx)) 442 return 0; 443#endif 444 445 if (ossl_param_get1_octet_string_from_param(p.salt, &ctx->label, 446 &ctx->label_len) == 0) 447 return 0; 448 449 if (ossl_param_get1_concat_octet_string(p.num_info, p.info, &ctx->context, 450 &ctx->context_len) == 0) 451 return 0; 452 453 if (ossl_param_get1_octet_string_from_param(p.seed, &ctx->iv, 454 &ctx->iv_len) == 0) 455 return 0; 456 457 if (p.use_l != NULL && !OSSL_PARAM_get_int(p.use_l, &ctx->use_l)) 458 return 0; 459 460 if (p.r != NULL) { 461 int new_r = 0; 462 463 if (!OSSL_PARAM_get_int(p.r, &new_r)) 464 return 0; 465 if (new_r != 8 && new_r != 16 && new_r != 24 && new_r != 32) 466 return 0; 467 ctx->r = new_r; 468 } 469 470 if (p.sep != NULL && !OSSL_PARAM_get_int(p.sep, &ctx->use_separator)) 471 return 0; 472 473 /* Set up digest context, if we can. */ 474 if (ctx->ctx_init != NULL && ctx->ki_len != 0) { 475 if ((ctx->is_kmac && !kmac_init(ctx->ctx_init, ctx->label, ctx->label_len)) 476 || !EVP_MAC_init(ctx->ctx_init, ctx->ki, ctx->ki_len, NULL)) 477 return 0; 478 } 479 return 1; 480} 481 482static const OSSL_PARAM *kbkdf_settable_ctx_params(ossl_unused void *ctx, 483 ossl_unused void *provctx) 484{ 485 return kbkdf_set_ctx_params_list; 486} 487 488{- produce_param_decoder('kbkdf_get_ctx_params', 489 (['KDF_PARAM_SIZE', 'size', 'size_t'], 490 ['KDF_PARAM_FIPS_APPROVED_INDICATOR', 'ind', 'int', 'fips'], 491 )); -} 492 493static int kbkdf_get_ctx_params(void *vctx, OSSL_PARAM params[]) 494{ 495 struct kbkdf_get_ctx_params_st p; 496 KBKDF *ctx = (KBKDF *)vctx; 497 498 if (ctx == NULL || !kbkdf_get_ctx_params_decoder(params, &p)) 499 return 0; 500 501 /* KBKDF can produce results as large as you like. */ 502 if (p.size != NULL && !OSSL_PARAM_set_size_t(p.size, SIZE_MAX)) 503 return 0; 504 505 if (!OSSL_FIPS_IND_GET_CTX_FROM_PARAM(ctx, p.ind)) 506 return 0; 507 return 1; 508} 509 510static const OSSL_PARAM *kbkdf_gettable_ctx_params(ossl_unused void *ctx, 511 ossl_unused void *provctx) 512{ 513 return kbkdf_get_ctx_params_list; 514} 515 516const OSSL_DISPATCH ossl_kdf_kbkdf_functions[] = { 517 { OSSL_FUNC_KDF_NEWCTX, (void(*)(void))kbkdf_new }, 518 { OSSL_FUNC_KDF_DUPCTX, (void(*)(void))kbkdf_dup }, 519 { OSSL_FUNC_KDF_FREECTX, (void(*)(void))kbkdf_free }, 520 { OSSL_FUNC_KDF_RESET, (void(*)(void))kbkdf_reset }, 521 { OSSL_FUNC_KDF_DERIVE, (void(*)(void))kbkdf_derive }, 522 { OSSL_FUNC_KDF_SETTABLE_CTX_PARAMS, 523 (void(*)(void))kbkdf_settable_ctx_params }, 524 { OSSL_FUNC_KDF_SET_CTX_PARAMS, (void(*)(void))kbkdf_set_ctx_params }, 525 { OSSL_FUNC_KDF_GETTABLE_CTX_PARAMS, 526 (void(*)(void))kbkdf_gettable_ctx_params }, 527 { OSSL_FUNC_KDF_GET_CTX_PARAMS, (void(*)(void))kbkdf_get_ctx_params }, 528 OSSL_DISPATCH_END, 529}; 530