]>
Commit | Line | Data |
---|---|---|
6ada465f DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
91da5e77 | 5 | EVP_PKEY_CTX_set_tls1_prf_md, |
6ada465f DSH |
6 | EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed - |
7 | TLS PRF key derivation algorithm | |
8 | ||
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/kdf.h> | |
12 | ||
13 | int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md); | |
14 | int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx, | |
15 | unsigned char *sec, int seclen); | |
27ed73a9 | 16 | int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx, |
6ada465f DSH |
17 | unsigned char *seed, int seedlen); |
18 | ||
19 | =head1 DESCRIPTION | |
20 | ||
91da5e77 | 21 | The B<EVP_PKEY_TLS1_PRF> algorithm implements the PRF key derivation function for |
6ada465f | 22 | TLS. It has no associated private key and only implements key derivation |
27ed73a9 | 23 | using L<EVP_PKEY_derive(3)>. |
6ada465f DSH |
24 | |
25 | EVP_PKEY_set_tls1_prf_md() sets the message digest associated with the | |
26 | TLS PRF. EVP_md5_sha1() is treated as a special case which uses the PRF | |
27 | algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1. | |
28 | ||
29 | EVP_PKEY_CTX_set_tls1_prf_secret() sets the secret value of the TLS PRF | |
30 | to B<seclen> bytes of the buffer B<sec>. Any existing secret value is replaced | |
31 | and any seed is reset. | |
32 | ||
33 | EVP_PKEY_CTX_add1_tls1_prf_seed() sets the seed to B<seedlen> bytes of B<seed>. | |
34 | If a seed is already set it is appended to the existing value. | |
35 | ||
4e8cb45c DSH |
36 | =head1 STRING CTRLS |
37 | ||
38 | The TLS PRF also supports string based control operations using | |
f04abe7d VD |
39 | L<EVP_PKEY_CTX_ctrl_str(3)>. |
40 | The B<type> parameter "md" uses the supplied B<value> as the name of the digest | |
41 | algorithm to use. | |
42 | The B<type> parameters "secret" and "seed" use the supplied B<value> parameter | |
43 | as a secret or seed value. | |
44 | The names "hexsecret" and "hexseed" are similar except they take a hex string | |
45 | which is converted to binary. | |
4e8cb45c | 46 | |
6ada465f DSH |
47 | =head1 NOTES |
48 | ||
49 | All these functions are implemented as macros. | |
50 | ||
51 | A context for the TLS PRF can be obtained by calling: | |
52 | ||
0af8fd60 | 53 | EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); |
6ada465f DSH |
54 | |
55 | The digest, secret value and seed must be set before a key is derived or an | |
56 | error occurs. | |
57 | ||
58 | The total length of all seeds cannot exceed 1024 bytes in length: this should | |
59 | be more than enough for any normal use of the TLS PRF. | |
60 | ||
61 | The output length of the PRF is specified by the length parameter in the | |
62 | EVP_PKEY_derive() function. Since the output length is variable, setting | |
63 | the buffer to B<NULL> is not meaningful for the TLS PRF. | |
64 | ||
65 | Optimised versions of the TLS PRF can be implemented in an ENGINE. | |
66 | ||
67 | =head1 RETURN VALUES | |
68 | ||
69 | All these functions return 1 for success and 0 or a negative value for failure. | |
70 | In particular a return value of -2 indicates the operation is not supported by | |
71 | the public key algorithm. | |
72 | ||
40cb2be7 | 73 | =head1 EXAMPLES |
6ada465f DSH |
74 | |
75 | This example derives 10 bytes using SHA-256 with the secret key "secret" | |
76 | and seed value "seed": | |
77 | ||
78 | EVP_PKEY_CTX *pctx; | |
79 | unsigned char out[10]; | |
80 | size_t outlen = sizeof(out); | |
e9b77246 | 81 | |
6ada465f DSH |
82 | pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL); |
83 | if (EVP_PKEY_derive_init(pctx) <= 0) | |
2947af32 | 84 | /* Error */ |
6ada465f | 85 | if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0) |
2947af32 | 86 | /* Error */ |
6ada465f | 87 | if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0) |
2947af32 | 88 | /* Error */ |
6ada465f | 89 | if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0) |
2947af32 | 90 | /* Error */ |
6ada465f | 91 | if (EVP_PKEY_derive(pctx, out, &outlen) <= 0) |
2947af32 | 92 | /* Error */ |
6ada465f DSH |
93 | |
94 | =head1 SEE ALSO | |
95 | ||
96 | L<EVP_PKEY_CTX_new(3)>, | |
f04abe7d | 97 | L<EVP_PKEY_CTX_ctrl_str(3)>, |
4e8cb45c | 98 | L<EVP_PKEY_derive(3)> |
6ada465f | 99 | |
e2f92610 RS |
100 | =head1 COPYRIGHT |
101 | ||
1cb7eff4 | 102 | Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
103 | |
104 | Licensed under the OpenSSL license (the "License"). You may not use | |
105 | this file except in compliance with the License. You can obtain a copy | |
106 | in the file LICENSE in the source distribution or at | |
107 | L<https://www.openssl.org/source/license.html>. | |
108 | ||
109 | =cut |