xref: /freebsd/crypto/openssl/doc/man7/EVP_KDF-TLS13_KDF.pod (revision b077aed33b7b6aefca7b17ddb250cf521f938613)
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