xref: /openssl/doc/man7/EVP_KDF-TLS1_PRF.pod (revision 6f08353a)
1=pod
2
3=head1 NAME
4
5EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation
6
7=head1 DESCRIPTION
8
9Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
10
11The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to
12and including TLS 1.2.
13
14The output is considered to be keying material.
15
16=head2 Identity
17
18"TLS1-PRF" is the name for this implementation; it
19can be used with the EVP_KDF_fetch() function.
20
21=head2 Supported parameters
22
23The supported parameters are:
24
25=over 4
26
27=item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string>
28
29=item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
30
31These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
32
33The B<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest
34associated with the TLS PRF.
35EVP_md5_sha1() is treated as a special case which uses the
36PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
37
38=item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string>
39
40This parameter sets the secret value of the TLS PRF.
41Any existing secret value is replaced.
42
43=item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string>
44
45This parameter sets the context seed.
46The length of the context seed cannot exceed 1024 bytes;
47this should be more than enough for any normal use of the TLS PRF.
48
49=back
50
51The OpenSSL FIPS provider also supports the following parameters:
52
53=over 4
54
55=item "fips-indicator" (B<OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR>) <integer>
56
57A getter that returns 1 if the operation is FIPS approved, or 0 otherwise.
58This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check"
59related parameter is set to 0 and the check fails.
60
61=item "ems_check" (B<OSSL_KDF_PARAM_FIPS_EMS_CHECK>) <integer>
62
63The default value of 1 causes an error during EVP_KDF_derive() if
64"master secret" is used instead of "extended master secret" Setting this to zero
65will ignore the error and set the approved "fips-indicator" to 0.
66This option breaks FIPS compliance if it causes the approved "fips-indicator"
67to return 0.
68
69=item "digest-check" (B<OSSL_KDF_PARAM_FIPS_DIGEST_CHECK>) <integer>
70
71The default value of 1 causes an error during EVP_KDF_CTX_set_params() if
72used digest is not approved.
73Setting this to zero will ignore the error and set the approved
74"fips-indicator" to 0.
75This option breaks FIPS compliance if it causes the approved "fips-indicator"
76to return 0.
77
78According to SP 800-135r1, the following are approved digest algorithms:
79SHA2-256, SHA2-384, SHA2-512.
80
81=item "key-check" (B<OSSL_KDF_PARAM_FIPS_KEY_CHECK>) <integer>
82
83The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the
84length of used key-derivation key (B<OSSL_KDF_PARAM_SECRET>) is shorter than 112
85bits.
86Setting this to zero will ignore the error and set the approved
87"fips-indicator" to 0.
88This option breaks FIPS compliance if it causes the approved "fips-indicator"
89to return 0.
90
91=back
92
93=head1 NOTES
94
95A context for the TLS PRF can be obtained by calling:
96
97 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
98 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
99
100The digest, secret value and seed must be set before a key is derived otherwise
101an error will occur.
102
103The output length of the PRF is specified by the I<keylen> parameter to the
104EVP_KDF_derive() function.
105
106=head1 EXAMPLES
107
108This example derives 10 bytes using SHA-256 with the secret key "secret"
109and seed value "seed":
110
111 EVP_KDF *kdf;
112 EVP_KDF_CTX *kctx;
113 unsigned char out[10];
114 OSSL_PARAM params[4], *p = params;
115
116 kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
117 kctx = EVP_KDF_CTX_new(kdf);
118 EVP_KDF_free(kdf);
119
120 *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
121                                         SN_sha256, strlen(SN_sha256));
122 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
123                                          "secret", (size_t)6);
124 *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
125                                          "seed", (size_t)4);
126 *p = OSSL_PARAM_construct_end();
127 if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
128     error("EVP_KDF_derive");
129 }
130 EVP_KDF_CTX_free(kctx);
131
132=head1 CONFORMING TO
133
134RFC 2246, RFC 5246 and NIST SP 800-135 r1
135
136=head1 SEE ALSO
137
138L<EVP_KDF(3)>,
139L<EVP_KDF_CTX_new(3)>,
140L<EVP_KDF_CTX_free(3)>,
141L<EVP_KDF_CTX_set_params(3)>,
142L<EVP_KDF_derive(3)>,
143L<EVP_KDF(3)/PARAMETERS>
144
145=head1 HISTORY
146
147This functionality was added in OpenSSL 3.0.
148
149=head1 COPYRIGHT
150
151Copyright 2018-2024 The OpenSSL Project Authors. All Rights Reserved.
152
153Licensed under the Apache License 2.0 (the "License").  You may not use
154this file except in compliance with the License.  You can obtain a copy
155in the file LICENSE in the source distribution or at
156L<https://www.openssl.org/source/license.html>.
157
158=cut
159