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