1=pod 2 3=head1 NAME 4 5EVP_KDF-KB - The Key-Based EVP_KDF implementation 6 7=head1 DESCRIPTION 8 9The EVP_KDF-KB algorithm implements the Key-Based key derivation function 10(KBKDF). KBKDF derives a key from repeated application of a keyed MAC to an 11input secret (and other optional values). 12 13The output is considered to be keying material. 14 15=head2 Identity 16 17"KBKDF" is the name for this implementation; it can be used with the 18EVP_KDF_fetch() function. 19 20=head2 Supported parameters 21 22The supported parameters are: 23 24=over 4 25 26=item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string> 27 28The mode parameter determines which flavor of KBKDF to use - currently the 29choices are "counter" and "feedback". "counter" is the default, and will be 30used if unspecified. 31 32=item "mac" (B<OSSL_KDF_PARAM_MAC>) <UTF8 string> 33 34The value is either CMAC, HMAC, KMAC128 or KMAC256. 35 36=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 37 38=item "cipher" (B<OSSL_KDF_PARAM_CIPHER>) <UTF8 string> 39 40=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 41 42=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 43 44=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 45 46=item "info (B<OSSL_KDF_PARAM_INFO>) <octet string> 47 48=item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string> 49 50The seed parameter is unused in counter mode. 51 52=item "use-l" (B<OSSL_KDF_PARAM_KBKDF_USE_L>) <integer> 53 54Set to B<0> to disable use of the optional Fixed Input data 'L' (see SP800-108). 55The default value of B<1> will be used if unspecified. 56 57=item "use-separator" (B<OSSL_KDF_PARAM_KBKDF_USE_SEPARATOR>) <integer> 58 59Set to B<0> to disable use of the optional Fixed Input data 'zero separator' 60(see SP800-108) that is placed between the Label and Context. 61The default value of B<1> will be used if unspecified. 62 63=item "r" (B<OSSL_KDF_PARAM_KBKDF_R>) <integer> 64 65Set the fixed value 'r', indicating the length of the counter in bits. 66 67Supported values are B<8>, B<16>, B<24>, and B<32>. 68The default value of B<32> will be used if unspecified. 69 70=back 71 72The OpenSSL FIPS provider also supports the following parameters: 73 74=over 4 75 76=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer> 77 78A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. 79This may be used after calling EVP_KDF_derive. It returns 0 if "key-check" 80is set to 0 and the check fails. 81 82=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer> 83 84The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the 85length of used key-derivation key (B<OSSL_KDF_PARAM_KEY>) is shorter than 112 86bits. 87Setting this to zero will ignore the error and set the approved 88"fips-indicator" to 0. 89This option breaks FIPS compliance if it causes the approved "fips-indicator" 90to return 0. 91 92=back 93 94Depending on whether mac is CMAC or HMAC, either digest or cipher is required 95(respectively) and the other is unused. They are unused for KMAC128 and KMAC256. 96 97The parameters key, salt, info, and seed correspond to KI, Label, Context, and 98IV (respectively) in SP800-108. As in that document, salt, info, and seed are 99optional and may be omitted. 100 101"mac", "digest", cipher" and "properties" are described in 102L<EVP_KDF(3)/PARAMETERS>. 103 104=head1 NOTES 105 106A context for KBKDF can be obtained by calling: 107 108 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); 109 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 110 111The output length of an KBKDF is specified via the C<keylen> 112parameter to the L<EVP_KDF_derive(3)> function. 113 114Note that currently OpenSSL only implements counter and feedback modes. Other 115variants may be supported in the future. 116 117=head1 EXAMPLES 118 119This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret", 120Label "label", and Context "context". 121 122 EVP_KDF *kdf; 123 EVP_KDF_CTX *kctx; 124 unsigned char out[10]; 125 OSSL_PARAM params[6], *p = params; 126 127 kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); 128 kctx = EVP_KDF_CTX_new(kdf); 129 EVP_KDF_free(kdf); 130 131 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 132 "SHA2-256", 0); 133 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, 134 "HMAC", 0); 135 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 136 "secret", strlen("secret")); 137 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 138 "label", strlen("label")); 139 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 140 "context", strlen("context")); 141 *p = OSSL_PARAM_construct_end(); 142 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) 143 error("EVP_KDF_derive"); 144 145 EVP_KDF_CTX_free(kctx); 146 147This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret", 148Label "label", and IV "sixteen bytes iv". 149 150 EVP_KDF *kdf; 151 EVP_KDF_CTX *kctx; 152 unsigned char out[10]; 153 OSSL_PARAM params[8], *p = params; 154 unsigned char *iv = "sixteen bytes iv"; 155 156 kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); 157 kctx = EVP_KDF_CTX_new(kdf); 158 EVP_KDF_free(kdf); 159 160 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CIPHER, "AES256", 0); 161 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0); 162 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0); 163 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 164 "secret", strlen("secret")); 165 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 166 "label", strlen("label")); 167 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 168 "context", strlen("context")); 169 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, 170 iv, strlen(iv)); 171 *p = OSSL_PARAM_construct_end(); 172 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) 173 error("EVP_KDF_derive"); 174 175 EVP_KDF_CTX_free(kctx); 176 177=head1 CONFORMING TO 178 179NIST SP800-108, IETF RFC 6803, IETF RFC 8009. 180 181=head1 SEE ALSO 182 183L<EVP_KDF(3)>, 184L<EVP_KDF_CTX_free(3)>, 185L<EVP_KDF_CTX_get_kdf_size(3)>, 186L<EVP_KDF_derive(3)>, 187L<EVP_KDF(3)/PARAMETERS> 188 189=head1 HISTORY 190 191This functionality was added in OpenSSL 3.0. 192 193Support for KMAC was added in OpenSSL 3.1. 194 195=head1 COPYRIGHT 196 197Copyright 2019-2024 The OpenSSL Project Authors. All Rights Reserved. 198Copyright 2019 Red Hat, Inc. 199 200Licensed under the Apache License 2.0 (the "License"). You may not use 201this file except in compliance with the License. You can obtain a copy 202in the file LICENSE in the source distribution or at 203L<https://www.openssl.org/source/license.html>. 204 205=cut 206
