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