Debian Codegraph @

upstream/debian-unstable/man3/SSL_export_keying_material.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 "SSL_EXPORT_KEYING_MATERIAL 3SSL"
58 .TH SSL_EXPORT_KEYING_MATERIAL 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 SSL_export_keying_material,
65 SSL_export_keying_material_early
66 \&\- obtain keying material for application use
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/ssl.h>
71 \&
72 \& int SSL_export_keying_material(SSL *s, unsigned char *out, size_t olen,
73 \& const char *label, size_t llen,
74 \& const unsigned char *context,
75 \& size_t contextlen, int use_context);
76 \&
77 \& int SSL_export_keying_material_early(SSL *s, unsigned char *out, size_t olen,
78 \& const char *label, size_t llen,
79 \& const unsigned char *context,
80 \& size_t contextlen);
81 .Ve
82 .SH DESCRIPTION
83 .IX Header "DESCRIPTION"
84 During the creation of a TLS or DTLS connection shared keying material is
85 established between the two endpoints. The functions
86 \&\fBSSL_export_keying_material()\fR and \fBSSL_export_keying_material_early()\fR enable an
87 application to use some of this keying material for its own purposes in
88 accordance with RFC5705 (for TLSv1.2 and below) or RFC8446 (for TLSv1.3).
89 .PP
90 \&\fBSSL_export_keying_material()\fR derives keying material using
91 the \fIexporter_master_secret\fR established in the handshake.
92 .PP
93 \&\fBSSL_export_keying_material_early()\fR is only usable with TLSv1.3, and derives
94 keying material using the \fIearly_exporter_master_secret\fR (as defined in the
95 TLS 1.3 RFC). For the client, the \fIearly_exporter_master_secret\fR is only
96 available when the client attempts to send 0\-RTT data. For the server, it is
97 only available when the server accepts 0\-RTT data.
98 .PP
99 An application may need to securely establish the context within which this
100 keying material will be used. For example this may include identifiers for the
101 application session, application algorithms or parameters, or the lifetime of
102 the context. The context value is left to the application but must be the same
103 on both sides of the communication.
104 .PP
105 For a given SSL connection \fBs\fR, \fBolen\fR bytes of data will be written to
106 \&\fBout\fR. The application specific context should be supplied in the location
107 pointed to by \fBcontext\fR and should be \fBcontextlen\fR bytes long. Provision of
108 a context is optional. If the context should be omitted entirely then
109 \&\fBuse_context\fR should be set to 0. Otherwise it should be any other value. If
110 \&\fBuse_context\fR is 0 then the values of \fBcontext\fR and \fBcontextlen\fR are ignored.
111 Note that in TLSv1.2 and below a zero length context is treated differently from
112 no context at all, and will result in different keying material being returned.
113 In TLSv1.3 a zero length context is that same as no context at all and will
114 result in the same keying material being returned.
115 .PP
116 An application specific label should be provided in the location pointed to by
117 \&\fBlabel\fR and should be \fBllen\fR bytes long. Typically this will be a value from
118 the IANA Exporter Label Registry
119 (<https://www.iana.org/assignments/tls\-parameters/tls\-parameters.xhtml#exporter\-labels>).
120 Alternatively labels beginning with "EXPERIMENTAL" are permitted by the standard
121 to be used without registration. TLSv1.3 imposes a maximum label length of
122 249 bytes.
123 .PP
124 Note that this function is only defined for TLSv1.0 and above, and DTLSv1.0 and
125 above. Attempting to use it in SSLv3 will result in an error.
126 .SH "RETURN VALUES"
127 .IX Header "RETURN VALUES"
128 \&\fBSSL_export_keying_material()\fR returns 0 or \-1 on failure or 1 on success.
129 .PP
130 \&\fBSSL_export_keying_material_early()\fR returns 0 on failure or 1 on success.
131 .SH "SEE ALSO"
132 .IX Header "SEE ALSO"
133 \&\fBssl\fR\|(7)
134 .SH HISTORY
135 .IX Header "HISTORY"
136 The \fBSSL_export_keying_material_early()\fR function was added in OpenSSL 1.1.1.
137 .SH COPYRIGHT
138 .IX Header "COPYRIGHT"
139 Copyright 2017\-2018 The OpenSSL Project Authors. All Rights Reserved.
140 .PP
141 Licensed under the Apache License 2.0 (the "License"). You may not use
142 this file except in compliance with the License. You can obtain a copy
143 in the file LICENSE in the source distribution or at
144 <https://www.openssl.org/source/license.html>.