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