]>
Commit | Line | Data |
---|---|---|
ccd7115a P |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
9 | Support for computing the B<TLS1> PRF through the B<EVP_KDF> API. | |
10 | ||
11 | The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to | |
12 | and including TLS 1.2. | |
13 | ||
14 | =head2 Identity | |
15 | ||
16 | "TLS1-PRF" is the name for this implementation; it | |
17 | can be used with the EVP_KDF_fetch() function. | |
18 | ||
19 | =head2 Supported parameters | |
20 | ||
21 | The supported parameters are: | |
22 | ||
23 | =over 4 | |
24 | ||
0c452a51 | 25 | =item "properties" (B<OSSL_KDF_PARAM_PROPERTIES>) <UTF8 string> |
ccd7115a | 26 | |
0c452a51 | 27 | =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string> |
ccd7115a P |
28 | |
29 | These parameters work as described in L<EVP_KDF(3)/PARAMETERS>. | |
30 | ||
dfabee82 | 31 | The B<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest |
ccd7115a P |
32 | associated with the TLS PRF. |
33 | EVP_md5_sha1() is treated as a special case which uses the | |
34 | PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. | |
35 | ||
0c452a51 | 36 | =item "secret" (B<OSSL_KDF_PARAM_SECRET>) <octet string> |
ccd7115a P |
37 | |
38 | This parameter sets the secret value of the TLS PRF. | |
39 | Any existing secret value is replaced. | |
40 | ||
0c452a51 | 41 | =item "seed" (B<OSSL_KDF_PARAM_SEED>) <octet string> |
ccd7115a P |
42 | |
43 | This parameter sets the context seed. | |
44 | The length of the context seed cannot exceed 1024 bytes; | |
45 | this should be more than enough for any normal use of the TLS PRF. | |
46 | ||
47 | =back | |
48 | ||
49 | =head1 NOTES | |
50 | ||
51 | A context for the TLS PRF can be obtained by calling: | |
52 | ||
53 | EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); | |
660c5344 | 54 | EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
55 | |
56 | The digest, secret value and seed must be set before a key is derived otherwise | |
57 | an error will occur. | |
58 | ||
dfabee82 | 59 | The output length of the PRF is specified by the I<keylen> parameter to the |
ccd7115a P |
60 | EVP_KDF_derive() function. |
61 | ||
62 | =head1 EXAMPLES | |
63 | ||
64 | This example derives 10 bytes using SHA-256 with the secret key "secret" | |
65 | and seed value "seed": | |
66 | ||
67 | EVP_KDF *kdf; | |
68 | EVP_KDF_CTX *kctx; | |
69 | unsigned char out[10]; | |
70 | OSSL_PARAM params[4], *p = params; | |
71 | ||
72 | kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL); | |
660c5344 | 73 | kctx = EVP_KDF_CTX_new(kdf); |
ccd7115a P |
74 | EVP_KDF_free(kdf); |
75 | ||
76 | *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST, | |
77 | SN_sha256, strlen(SN_sha256)); | |
78 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET, | |
79 | "secret", (size_t)6); | |
80 | *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED, | |
81 | "seed", (size_t)4); | |
82 | *p = OSSL_PARAM_construct_end(); | |
6980e36a | 83 | if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) { |
ccd7115a P |
84 | error("EVP_KDF_derive"); |
85 | } | |
660c5344 | 86 | EVP_KDF_CTX_free(kctx); |
ccd7115a P |
87 | |
88 | =head1 CONFORMING TO | |
89 | ||
90 | RFC 2246, RFC 5246 and NIST SP 800-135 r1 | |
91 | ||
92 | =head1 SEE ALSO | |
93 | ||
4c04e7b1 | 94 | L<EVP_KDF(3)>, |
660c5344 MC |
95 | L<EVP_KDF_CTX_new(3)>, |
96 | L<EVP_KDF_CTX_free(3)>, | |
97 | L<EVP_KDF_CTX_set_params(3)>, | |
4c04e7b1 P |
98 | L<EVP_KDF_derive(3)>, |
99 | L<EVP_KDF(3)/PARAMETERS> | |
ccd7115a | 100 | |
4741c80c | 101 | =head1 HISTORY |
102 | ||
103 | This functionality was added in OpenSSL 3.0. | |
104 | ||
ccd7115a P |
105 | =head1 COPYRIGHT |
106 | ||
8020d79b | 107 | Copyright 2018-2021 The OpenSSL Project Authors. All Rights Reserved. |
ccd7115a P |
108 | |
109 | Licensed under the Apache License 2.0 (the "License"). You may not use | |
110 | this file except in compliance with the License. You can obtain a copy | |
111 | in the file LICENSE in the source distribution or at | |
112 | L<https://www.openssl.org/source/license.html>. | |
113 | ||
114 | =cut |