1b077aed3SPierre Pronchery=pod 2b077aed3SPierre Pronchery 3b077aed3SPierre Pronchery=head1 NAME 4b077aed3SPierre Pronchery 5b077aed3SPierre ProncheryEVP_KDF-TLS13_KDF - The TLS 1.3 EVP_KDF implementation 6b077aed3SPierre Pronchery 7b077aed3SPierre Pronchery=head1 DESCRIPTION 8b077aed3SPierre Pronchery 9b077aed3SPierre ProncherySupport for computing the TLS 1.3 version of the B<HKDF> KDF through 10b077aed3SPierre Proncherythe B<EVP_KDF> API. 11b077aed3SPierre Pronchery 12b077aed3SPierre ProncheryThe EVP_KDF-TLS13_KDF algorithm implements the HKDF key derivation function 13b077aed3SPierre Proncheryas used by TLS 1.3. 14b077aed3SPierre Pronchery 15*0d0c8621SEnji CooperThe output is considered to be keying material. 16*0d0c8621SEnji Cooper 17b077aed3SPierre Pronchery=head2 Identity 18b077aed3SPierre Pronchery 19b077aed3SPierre Pronchery"TLS13-KDF" is the name for this implementation; it 20b077aed3SPierre Proncherycan be used with the EVP_KDF_fetch() function. 21b077aed3SPierre Pronchery 22b077aed3SPierre Pronchery=head2 Supported parameters 23b077aed3SPierre Pronchery 24b077aed3SPierre ProncheryThe supported parameters are: 25b077aed3SPierre Pronchery 26b077aed3SPierre Pronchery=over 4 27b077aed3SPierre Pronchery 28b077aed3SPierre Pronchery=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> 29b077aed3SPierre Pronchery 30b077aed3SPierre Pronchery=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> 31b077aed3SPierre Pronchery 32b077aed3SPierre Pronchery=item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string> 33b077aed3SPierre Pronchery 34b077aed3SPierre Pronchery=item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string> 35b077aed3SPierre Pronchery 36b077aed3SPierre ProncheryThese parameters work as described in L<EVP_KDF(3)/PARAMETERS>. 37b077aed3SPierre Pronchery 38b077aed3SPierre Pronchery=item "prefix" (B<OSSL_KDF_PARAM_PREFIX>) <octet string> 39b077aed3SPierre Pronchery 40b077aed3SPierre ProncheryThis parameter sets the label prefix on the specified TLS 1.3 KDF context. 41b077aed3SPierre ProncheryFor TLS 1.3 this should be set to the ASCII string "tls13 " without a 42b077aed3SPierre Proncherytrailing zero byte. Refer to RFC 8446 section 7.1 "Key Schedule" for details. 43b077aed3SPierre Pronchery 44b077aed3SPierre Pronchery=item "label" (B<OSSL_KDF_PARAM_LABEL>) <octet string> 45b077aed3SPierre Pronchery 46b077aed3SPierre ProncheryThis parameter sets the label on the specified TLS 1.3 KDF context. 47b077aed3SPierre ProncheryRefer to RFC 8446 section 7.1 "Key Schedule" for details. 48b077aed3SPierre Pronchery 49b077aed3SPierre Pronchery=item "data" (B<OSSL_KDF_PARAM_DATA>) <octet string> 50b077aed3SPierre Pronchery 51b077aed3SPierre ProncheryThis parameter sets the context data on the specified TLS 1.3 KDF context. 52b077aed3SPierre ProncheryRefer to RFC 8446 section 7.1 "Key Schedule" for details. 53b077aed3SPierre Pronchery 54b077aed3SPierre Pronchery=item "mode" (B<OSSL_KDF_PARAM_MODE>) <UTF8 string> or <integer> 55b077aed3SPierre Pronchery 56b077aed3SPierre ProncheryThis parameter sets the mode for the TLS 1.3 KDF operation. 57b077aed3SPierre ProncheryThere are two modes that are currently defined: 58b077aed3SPierre Pronchery 59b077aed3SPierre Pronchery=over 4 60b077aed3SPierre Pronchery 61b077aed3SPierre Pronchery=item "EXTRACT_ONLY" or B<EVP_KDF_HKDF_MODE_EXTRACT_ONLY> 62b077aed3SPierre Pronchery 63b077aed3SPierre ProncheryIn this mode calling L<EVP_KDF_derive(3)> will just perform the extract 64b077aed3SPierre Proncheryoperation. The value returned will be the intermediate fixed-length pseudorandom 65b077aed3SPierre Proncherykey K. The I<keylen> parameter must match the size of K, which can be looked 66b077aed3SPierre Proncheryup by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest. 67b077aed3SPierre Pronchery 68b077aed3SPierre ProncheryThe digest, key and salt values must be set before a key is derived otherwise 69b077aed3SPierre Proncheryan error will occur. 70b077aed3SPierre Pronchery 71b077aed3SPierre Pronchery=item "EXPAND_ONLY" or B<EVP_KDF_HKDF_MODE_EXPAND_ONLY> 72b077aed3SPierre Pronchery 73b077aed3SPierre ProncheryIn this mode calling L<EVP_KDF_derive(3)> will just perform the expand 74b077aed3SPierre Proncheryoperation. The input key should be set to the intermediate fixed-length 75b077aed3SPierre Proncherypseudorandom key K returned from a previous extract operation. 76b077aed3SPierre Pronchery 77b077aed3SPierre ProncheryThe digest, key and info values must be set before a key is derived otherwise 78b077aed3SPierre Proncheryan error will occur. 79b077aed3SPierre Pronchery 80b077aed3SPierre Pronchery=back 81b077aed3SPierre Pronchery 82b077aed3SPierre Pronchery=back 83b077aed3SPierre Pronchery 84b077aed3SPierre Pronchery=head1 NOTES 85b077aed3SPierre Pronchery 86b077aed3SPierre ProncheryThis KDF is intended for use by the TLS 1.3 implementation in libssl. 87b077aed3SPierre ProncheryIt does not support all the options and capabilities that HKDF does. 88b077aed3SPierre Pronchery 89b077aed3SPierre ProncheryThe I<OSSL_PARAM> array passed to L<EVP_KDF_derive(3)> or 90b077aed3SPierre ProncheryL<EVP_KDF_CTX_set_params(3)> must specify all of the parameters required. 91b077aed3SPierre ProncheryThis KDF does not support a piecemeal approach to providing these. 92b077aed3SPierre Pronchery 93b077aed3SPierre ProncheryA context for a TLS 1.3 KDF can be obtained by calling: 94b077aed3SPierre Pronchery 95b077aed3SPierre Pronchery EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS13-KDF", NULL); 96b077aed3SPierre Pronchery EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); 97b077aed3SPierre Pronchery 98b077aed3SPierre ProncheryThe output length of a TLS 1.3 KDF expand operation is specified via the 99b077aed3SPierre ProncheryI<keylen> parameter to the L<EVP_KDF_derive(3)> function. When using 100b077aed3SPierre ProncheryEVP_KDF_HKDF_MODE_EXTRACT_ONLY the I<keylen> parameter must equal the size of 101b077aed3SPierre Proncherythe intermediate fixed-length pseudorandom key otherwise an error will occur. 102b077aed3SPierre ProncheryFor that mode, the fixed output size can be looked up by calling 103b077aed3SPierre ProncheryEVP_KDF_CTX_get_kdf_size() after setting the mode and digest on the 104b077aed3SPierre ProncheryB<EVP_KDF_CTX>. 105b077aed3SPierre Pronchery 106b077aed3SPierre Pronchery=head1 CONFORMING TO 107b077aed3SPierre Pronchery 108b077aed3SPierre ProncheryRFC 8446 109b077aed3SPierre Pronchery 110b077aed3SPierre Pronchery=head1 SEE ALSO 111b077aed3SPierre Pronchery 112b077aed3SPierre ProncheryL<EVP_KDF(3)>, 113b077aed3SPierre ProncheryL<EVP_KDF_CTX_new(3)>, 114b077aed3SPierre ProncheryL<EVP_KDF_CTX_free(3)>, 115b077aed3SPierre ProncheryL<EVP_KDF_CTX_get_kdf_size(3)>, 116b077aed3SPierre ProncheryL<EVP_KDF_CTX_set_params(3)>, 117b077aed3SPierre ProncheryL<EVP_KDF_derive(3)>, 118b077aed3SPierre ProncheryL<EVP_KDF(3)/PARAMETERS>, 119b077aed3SPierre ProncheryL<EVP_KDF-HKDF(7)> 120b077aed3SPierre Pronchery 121b077aed3SPierre Pronchery=head1 HISTORY 122b077aed3SPierre Pronchery 123b077aed3SPierre ProncheryThis functionality was added in OpenSSL 3.0. 124b077aed3SPierre Pronchery 125b077aed3SPierre Pronchery=head1 COPYRIGHT 126b077aed3SPierre Pronchery 127b077aed3SPierre ProncheryCopyright 2021 The OpenSSL Project Authors. All Rights Reserved. 128b077aed3SPierre Pronchery 129b077aed3SPierre ProncheryLicensed under the Apache License 2.0 (the "License"). You may not use 130b077aed3SPierre Proncherythis file except in compliance with the License. You can obtain a copy 131b077aed3SPierre Proncheryin the file LICENSE in the source distribution or at 132b077aed3SPierre ProncheryL<https://www.openssl.org/source/license.html>. 133b077aed3SPierre Pronchery 134b077aed3SPierre Pronchery=cut 135