Debian Codegraph @

upstream/debian-unstable/man3/EVP_PKEY_CTX_set_tls1_prf_md.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "EVP_PKEY_CTX_SET_TLS1_PRF_MD 3SSL"
58 .TH EVP_PKEY_CTX_SET_TLS1_PRF_MD 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 EVP_PKEY_CTX_set_tls1_prf_md,
65 EVP_PKEY_CTX_set1_tls1_prf_secret, EVP_PKEY_CTX_add1_tls1_prf_seed \-
66 TLS PRF key derivation algorithm
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/kdf.h>
71 \&
72 \& int EVP_PKEY_CTX_set_tls1_prf_md(EVP_PKEY_CTX *pctx, const EVP_MD *md);
73 \& int EVP_PKEY_CTX_set1_tls1_prf_secret(EVP_PKEY_CTX *pctx,
74 \& unsigned char *sec, int seclen);
75 \& int EVP_PKEY_CTX_add1_tls1_prf_seed(EVP_PKEY_CTX *pctx,
76 \& unsigned char *seed, int seedlen);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 The \fBEVP_PKEY_TLS1_PRF\fR algorithm implements the PRF key derivation function for
81 TLS. It has no associated private key and only implements key derivation
82 using \fBEVP_PKEY_derive\fR\|(3).
83 .PP
84 \&\fBEVP_PKEY_set_tls1_prf_md()\fR sets the message digest associated with the
85 TLS PRF. \fBEVP_md5_sha1()\fR is treated as a special case which uses the PRF
86 algorithm using both \fBMD5\fR and \fBSHA1\fR as used in TLS 1.0 and 1.1.
87 .PP
88 \&\fBEVP_PKEY_CTX_set_tls1_prf_secret()\fR sets the secret value of the TLS PRF
89 to \fBseclen\fR bytes of the buffer \fBsec\fR. Any existing secret value is replaced
90 and any seed is reset.
91 .PP
92 \&\fBEVP_PKEY_CTX_add1_tls1_prf_seed()\fR sets the seed to \fBseedlen\fR bytes of \fBseed\fR.
93 If a seed is already set it is appended to the existing value.
94 .SH "STRING CTRLS"
95 .IX Header "STRING CTRLS"
96 The TLS PRF also supports string based control operations using
97 \&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3).
98 The \fBtype\fR parameter "md" uses the supplied \fBvalue\fR as the name of the digest
99 algorithm to use.
100 The \fBtype\fR parameters "secret" and "seed" use the supplied \fBvalue\fR parameter
101 as a secret or seed value.
102 The names "hexsecret" and "hexseed" are similar except they take a hex string
103 which is converted to binary.
104 .SH NOTES
105 .IX Header "NOTES"
106 A context for the TLS PRF can be obtained by calling:
107 .PP
108 .Vb 1
109 \& EVP_PKEY_CTX *pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL);
110 .Ve
111 .PP
112 The digest, secret value and seed must be set before a key is derived or an
113 error occurs.
114 .PP
115 The total length of all seeds cannot exceed 1024 bytes in length: this should
116 be more than enough for any normal use of the TLS PRF.
117 .PP
118 The output length of the PRF is specified by the length parameter in the
119 \&\fBEVP_PKEY_derive()\fR function. Since the output length is variable, setting
120 the buffer to \fBNULL\fR is not meaningful for the TLS PRF.
121 .PP
122 Optimised versions of the TLS PRF can be implemented in an ENGINE.
123 .SH "RETURN VALUES"
124 .IX Header "RETURN VALUES"
125 All these functions return 1 for success and 0 or a negative value for failure.
126 In particular a return value of \-2 indicates the operation is not supported by
127 the public key algorithm.
128 .SH EXAMPLES
129 .IX Header "EXAMPLES"
130 This example derives 10 bytes using SHA\-256 with the secret key "secret"
131 and seed value "seed":
132 .PP
133 .Vb 3
134 \& EVP_PKEY_CTX *pctx;
135 \& unsigned char out[10];
136 \& size_t outlen = sizeof(out);
137 \&
138 \& pctx = EVP_PKEY_CTX_new_id(EVP_PKEY_TLS1_PRF, NULL);
139 \& if (EVP_PKEY_derive_init(pctx) <= 0)
140 \& /* Error */
141 \& if (EVP_PKEY_CTX_set_tls1_prf_md(pctx, EVP_sha256()) <= 0)
142 \& /* Error */
143 \& if (EVP_PKEY_CTX_set1_tls1_prf_secret(pctx, "secret", 6) <= 0)
144 \& /* Error */
145 \& if (EVP_PKEY_CTX_add1_tls1_prf_seed(pctx, "seed", 4) <= 0)
146 \& /* Error */
147 \& if (EVP_PKEY_derive(pctx, out, &outlen) <= 0)
148 \& /* Error */
149 .Ve
150 .SH "SEE ALSO"
151 .IX Header "SEE ALSO"
152 \&\fBEVP_PKEY_CTX_new\fR\|(3),
153 \&\fBEVP_PKEY_CTX_ctrl_str\fR\|(3),
154 \&\fBEVP_PKEY_derive\fR\|(3)
155 .SH HISTORY
156 .IX Header "HISTORY"
157 All of the functions described here were converted from macros to functions in
158 OpenSSL 3.0.
159 .SH COPYRIGHT
160 .IX Header "COPYRIGHT"
161 Copyright 2016\-2020 The OpenSSL Project Authors. All Rights Reserved.
162 .PP
163 Licensed under the Apache License 2.0 (the "License"). You may not use
164 this file except in compliance with the License. You can obtain a copy
165 in the file LICENSE in the source distribution or at
166 <https://www.openssl.org/source/license.html>.