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 or HMAC. 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=back 64 65Depending on whether mac is CMAC or HMAC, either digest or cipher is required 66(respectively) and the other is unused. 67 68The parameters key, salt, info, and seed correspond to KI, Label, Context, and 69IV (respectively) in SP800-108. As in that document, salt, info, and seed are 70optional and may be omitted. 71 72"mac", "digest", cipher" and "properties" are described in 73L<EVP_KDF(3)/PARAMETERS>. 74 75=head1 NOTES 76 77A context for KBKDF can be obtained by calling: 78 79 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); 80 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 81 82The output length of an KBKDF is specified via the C<keylen> 83parameter to the L<EVP_KDF_derive(3)> function. 84 85Note that currently OpenSSL only implements counter and feedback modes. Other 86variants may be supported in the future. 87 88=head1 EXAMPLES 89 90This example derives 10 bytes using COUNTER-HMAC-SHA256, with KI "secret", 91Label "label", and Context "context". 92 93 EVP_KDF *kdf; 94 EVP_KDF_CTX *kctx; 95 unsigned char out[10]; 96 OSSL_PARAM params[6], *p = params; 97 98 kdf = EVP_KDF_fetch(NULL, "KBKDF", NULL); 99 kctx = EVP_KDF_CTX_new(kdf); 100 EVP_KDF_free(kdf); 101 102 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 103 "SHA2-256", 0); 104 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, 105 "HMAC", 0); 106 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 107 "secret", strlen("secret")); 108 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 109 "label", strlen("label")); 110 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 111 "context", strlen("context")); 112 *p = OSSL_PARAM_construct_end(); 113 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) 114 error("EVP_KDF_derive"); 115 116 EVP_KDF_CTX_free(kctx); 117 118This example derives 10 bytes using FEEDBACK-CMAC-AES256, with KI "secret", 119Label "label", and IV "sixteen bytes iv". 120 121 EVP_KDF *kdf; 122 EVP_KDF_CTX *kctx; 123 unsigned char out[10]; 124 OSSL_PARAM params[8], *p = params; 125 unsigned char *iv = "sixteen bytes iv"; 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_CIPHER, "AES256", 0); 132 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC, "CMAC", 0); 133 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MODE, "FEEDBACK", 0); 134 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 135 "secret", strlen("secret")); 136 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 137 "label", strlen("label")); 138 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 139 "context", strlen("context")); 140 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, 141 iv, strlen(iv)); 142 *p = OSSL_PARAM_construct_end(); 143 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) 144 error("EVP_KDF_derive"); 145 146 EVP_KDF_CTX_free(kctx); 147 148=head1 CONFORMING TO 149 150NIST SP800-108, IETF RFC 6803, IETF RFC 8009. 151 152=head1 SEE ALSO 153 154L<EVP_KDF(3)>, 155L<EVP_KDF_CTX_free(3)>, 156L<EVP_KDF_CTX_get_kdf_size(3)>, 157L<EVP_KDF_derive(3)>, 158L<EVP_KDF(3)/PARAMETERS> 159 160=head1 HISTORY 161 162This functionality was added in OpenSSL 3.0. 163 164=head1 COPYRIGHT 165 166Copyright 2019-2021 The OpenSSL Project Authors. All Rights Reserved. 167Copyright 2019 Red Hat, Inc. 168 169Licensed under the Apache License 2.0 (the "License"). You may not use 170this file except in compliance with the License. You can obtain a copy 171in the file LICENSE in the source distribution or at 172L<https://www.openssl.org/source/license.html>. 173 174=cut 175