1249997Swkoszek=pod 2249997Swkoszek 3249997Swkoszek=head1 NAME 4249997Swkoszek 5249997SwkoszekEVP_KDF-HKDF - The HKDF EVP_KDF implementation 6249997Swkoszek 7249997Swkoszek=head1 DESCRIPTION 8249997Swkoszek 9249997SwkoszekSupport for computing the B<HKDF> KDF through the B<EVP_KDF> API. 10249997Swkoszek 11249997SwkoszekThe EVP_KDF-HKDF algorithm implements the HKDF key derivation function. 12249997SwkoszekHKDF follows the "extract-then-expand" paradigm, where the KDF logically 13249997Swkoszekconsists of two modules. The first stage takes the input keying material 14249997Swkoszekand "extracts" from it a fixed-length pseudorandom key K. The second stage 15249997Swkoszek"expands" the key K into several additional pseudorandom keys (the output 16249997Swkoszekof the KDF). 17249997Swkoszek 18249997Swkoszek=head2 Identity 19249997Swkoszek 20249997Swkoszek"HKDF" is the name for this implementation; it 21249997Swkoszekcan be used with the EVP_KDF_fetch() function. 22249997Swkoszek 23249997Swkoszek=head2 Supported parameters 24249997Swkoszek 25249997SwkoszekThe supported parameters are: 26249997Swkoszek 27249997Swkoszek=over 4 28249997Swkoszek 29249997Swkoszek=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 30249997Swkoszek 31249997Swkoszek=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 32249997Swkoszek 33249997Swkoszek=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 34249997Swkoszek 35249997Swkoszek=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 36249997Swkoszek 37249997SwkoszekThese parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 38249997Swkoszek 39249997Swkoszek=item "info" (B<OSSL_KDF_PARAM_INFO>) <octet string> 40249997Swkoszek 41249997SwkoszekThis parameter sets the info value. 42249997SwkoszekThe length of the context info buffer cannot exceed 1024 bytes; 43249997Swkoszekthis should be more than enough for any normal use of HKDF. 44249997Swkoszek 45249997Swkoszek=item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string> or <integer> 46249997Swkoszek 47249997SwkoszekThis parameter sets the mode for the HKDF operation. 48249997SwkoszekThere are three modes that are currently defined: 49249997Swkoszek 50249997Swkoszek=over 4 51249997Swkoszek 52249997Swkoszek=item "EXTRACT_AND_EXPAND" or B<EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND> 53249997Swkoszek 54249997SwkoszekThis is the default mode. Calling L<EVP_KDF_derive(3)> on an EVP_KDF_CTX set 55249997Swkoszekup for HKDF will perform an extract followed by an expand operation in one go. 56249997SwkoszekThe derived key returned will be the result after the expand operation. The 57249997Swkoszekintermediate fixed-length pseudorandom key K is not returned. 58249997Swkoszek 59249997SwkoszekIn this mode the digest, key, salt and info values must be set before a key is 60249997Swkoszekderived otherwise an error will occur. 61249997Swkoszek 62249997Swkoszek=item "EXTRACT_ONLY" or B<EVP_KDF_HKDF_MODE_EXTRACT_ONLY> 63249997Swkoszek 64249997SwkoszekIn this mode calling L<EVP_KDF_derive(3)> will just perform the extract 65249997Swkoszekoperation. The value returned will be the intermediate fixed-length pseudorandom 66249997Swkoszekkey K. The I<keylen> parameter must match the size of K, which can be looked 67249997Swkoszekup by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest. 68249997Swkoszek 69249997SwkoszekThe digest, key and salt values must be set before a key is derived otherwise 70249997Swkoszekan error will occur. 71249997Swkoszek 72249997Swkoszek=item "EXPAND_ONLY" or B<EVP_KDF_HKDF_MODE_EXPAND_ONLY> 73249997Swkoszek 74249997SwkoszekIn this mode calling L<EVP_KDF_derive(3)> will just perform the expand 75249997Swkoszekoperation. The input key should be set to the intermediate fixed-length 76249997Swkoszekpseudorandom key K returned from a previous extract operation. 77249997Swkoszek 78249997SwkoszekThe digest, key and info values must be set before a key is derived otherwise 79249997Swkoszekan error will occur. 80249997Swkoszek 81249997Swkoszek=back 82249997Swkoszek 83249997Swkoszek=back 84249997Swkoszek 85249997Swkoszek=head1 NOTES 86249997Swkoszek 87249997SwkoszekA context for HKDF can be obtained by calling: 88249997Swkoszek 89249997Swkoszek EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); 90249997Swkoszek EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 91249997Swkoszek 92249997SwkoszekThe output length of an HKDF expand operation is specified via the I<keylen> 93249997Swkoszekparameter to the L<EVP_KDF_derive(3)> function. When using 94249997SwkoszekEVP_KDF_HKDF_MODE_EXTRACT_ONLY the I<keylen> parameter must equal the size of 95249997Swkoszekthe intermediate fixed-length pseudorandom key otherwise an error will occur. 96249997SwkoszekFor that mode, the fixed output size can be looked up by calling EVP_KDF_CTX_get_kdf_size() 97249997Swkoszekafter setting the mode and digest on the B<EVP_KDF_CTX>. 98249997Swkoszek 99249997Swkoszek=head1 EXAMPLES 100249997Swkoszek 101249997SwkoszekThis example derives 10 bytes using SHA-256 with the secret key "secret", 102249997Swkoszeksalt value "salt" and info value "label": 103249997Swkoszek 104249997Swkoszek EVP_KDF *kdf; 105249997Swkoszek EVP_KDF_CTX *kctx; 106249997Swkoszek unsigned char out[10]; 107249997Swkoszek OSSL_PARAM params[5], *p = params; 108249997Swkoszek 109249997Swkoszek kdf = EVP_KDF_fetch(NULL, "HKDF", NULL); 110249997Swkoszek kctx = EVP_KDF_CTX_new(kdf); 111249997Swkoszek EVP_KDF_free(kdf); 112249997Swkoszek 113249997Swkoszek *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, 114249997Swkoszek SN_sha256, strlen(SN_sha256)); 115249997Swkoszek *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY, 116249997Swkoszek "secret", (size_t)6); 117249997Swkoszek *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO, 118249997Swkoszek "label", (size_t)5); 119249997Swkoszek *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT, 120249997Swkoszek "salt", (size_t)4); 121249997Swkoszek *p = OSSL_PARAM_construct_end(); 122249997Swkoszek if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { 123249997Swkoszek error("EVP_KDF_derive"); 124249997Swkoszek } 125249997Swkoszek 126249997Swkoszek EVP_KDF_CTX_free(kctx); 127249997Swkoszek 128249997Swkoszek=head1 CONFORMING TO 129249997Swkoszek 130249997SwkoszekRFC 5869 131249997Swkoszek 132249997Swkoszek=head1 SEE ALSO 133249997Swkoszek 134249997SwkoszekL<EVP_KDF(3)>, 135249997SwkoszekL<EVP_KDF_CTX_new(3)>, 136249997SwkoszekL<EVP_KDF_CTX_free(3)>, 137249997SwkoszekL<EVP_KDF_CTX_get_kdf_size(3)>, 138249997SwkoszekL<EVP_KDF_CTX_set_params(3)>, 139249997SwkoszekL<EVP_KDF_derive(3)>, 140249997SwkoszekL<EVP_KDF(3)/PARAMETERS>, 141249997SwkoszekL<EVP_KDF-TLS13_KDF(7)> 142249997Swkoszek 143249997Swkoszek=head1 HISTORY 144249997Swkoszek 145249997SwkoszekThis functionality was added in OpenSSL 3.0. 146249997Swkoszek 147249997Swkoszek=head1 COPYRIGHT 148249997Swkoszek 149249997SwkoszekCopyright 2016-2021 The OpenSSL Project Authors. All Rights Reserved. 150249997Swkoszek 151249997SwkoszekLicensed under the Apache License 2.0 (the "License"). You may not use 152249997Swkoszekthis file except in compliance with the License. You can obtain a copy 153249997Swkoszekin the file LICENSE in the source distribution or at 154249997SwkoszekL<https://www.openssl.org/source/license.html>. 155249997Swkoszek 156249997Swkoszek=cut 157249997Swkoszek