1EVP_KDF_TLS1_PRF(7)                 OpenSSL                EVP_KDF_TLS1_PRF(7)
2
3
4

NAME

6       EVP_KDF_TLS1_PRF - The TLS1 PRF EVP_KDF implementation
7

DESCRIPTION

9       Support for computing the TLS1 PRF through the EVP_KDF API.
10
11       The EVP_KDF_TLS1_PRF algorithm implements the PRF used by TLS versions
12       up to and including TLS 1.2.
13
14   Numeric identity
15       EVP_KDF_TLS1_PRF is the numeric identity for this implementation; it
16       can be used with the EVP_KDF_CTX_new_id() function.
17
18   Supported controls
19       The supported controls are:
20
21       EVP_KDF_CTRL_SET_MD
22           This control works as described in "CONTROLS" in EVP_KDF_CTX(3).
23
24           The "EVP_KDF_CTRL_SET_MD" control is used to set the message digest
25           associated with the TLS PRF.  EVP_md5_sha1() is treated as a
26           special case which uses the PRF algorithm using both MD5 and SHA1
27           as used in TLS 1.0 and 1.1.
28
29       EVP_KDF_CTRL_SET_TLS_SECRET
30           This control expects two arguments: "unsigned char *sec", "size_t
31           seclen"
32
33           Sets the secret value of the TLS PRF to seclen bytes of the buffer
34           sec.  Any existing secret value is replaced.
35
36           EVP_KDF_ctrl_str() takes two type strings for this control:
37
38           "secret"
39               The value string is used as is.
40
41           "hexsecret"
42               The value string is expected to be a hexadecimal number, which
43               will be decoded before being passed on as the control value.
44
45       EVP_KDF_CTRL_RESET_TLS_SEED
46           This control does not expect any arguments.
47
48           Resets the context seed buffer to zero length.
49
50       EVP_KDF_CTRL_ADD_TLS_SEED
51           This control expects two arguments: "unsigned char *seed", "size_t
52           seedlen"
53
54           Sets the seed to seedlen bytes of seed.  If a seed is already set
55           it is appended to the existing value.
56
57           The total length of the context seed buffer cannot exceed 1024
58           bytes; this should be more than enough for any normal use of the
59           TLS PRF.
60
61           EVP_KDF_ctrl_str() takes two type strings for this control:
62
63           "seed"
64               The value string is used as is.
65
66           "hexseed"
67               The value string is expected to be a hexadecimal number, which
68               will be decoded before being passed on as the control value.
69

NOTES

71       A context for the TLS PRF can be obtained by calling:
72
73        EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL);
74
75       The digest, secret value and seed must be set before a key is derived
76       otherwise an error will occur.
77
78       The output length of the PRF is specified by the "keylen" parameter to
79       the EVP_KDF_derive() function.
80

EXAMPLE

82       This example derives 10 bytes using SHA-256 with the secret key
83       "secret" and seed value "seed":
84
85        EVP_KDF_CTX *kctx;
86        unsigned char out[10];
87
88        kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF);
89        if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
90            error("EVP_KDF_CTRL_SET_MD");
91        }
92        if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_TLS_SECRET,
93                         "secret", (size_t)6) <= 0) {
94            error("EVP_KDF_CTRL_SET_TLS_SECRET");
95        }
96        if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) {
97            error("EVP_KDF_CTRL_ADD_TLS_SEED");
98        }
99        if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
100            error("EVP_KDF_derive");
101        }
102        EVP_KDF_CTX_free(kctx);
103

SEE ALSO

105       EVP_KDF_CTX, EVP_KDF_CTX_new_id(3), EVP_KDF_CTX_free(3),
106       EVP_KDF_ctrl(3), EVP_KDF_derive(3), "CONTROLS" in EVP_KDF_CTX(3)
107

109       Copyright 2018 The OpenSSL Project Authors. All Rights Reserved.
110
111       Licensed under the Apache License 2.0 (the "License").  You may not use
112       this file except in compliance with the License.  You can obtain a copy
113       in the file LICENSE in the source distribution or at
114       <https://www.openssl.org/source/license.html>.
115
116
117
1181.1.1l                            2021-09-15               EVP_KDF_TLS1_PRF(7)
Impressum