Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_alpn_select_cb.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_CTX_SET_ALPN_SELECT_CB 3SSL"
58 .TH SSL_CTX_SET_ALPN_SELECT_CB 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_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
65 SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb,
66 SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated
67 \&\- handle application layer protocol negotiation (ALPN)
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/ssl.h>
72 \&
73 \& int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
74 \& unsigned int protos_len);
75 \& int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
76 \& unsigned int protos_len);
77 \& void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
78 \& int (*cb) (SSL *ssl,
79 \& const unsigned char **out,
80 \& unsigned char *outlen,
81 \& const unsigned char *in,
82 \& unsigned int inlen,
83 \& void *arg), void *arg);
84 \& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
85 \& unsigned int *len);
86 \&
87 \& void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx,
88 \& int (*cb)(SSL *ssl,
89 \& const unsigned char **out,
90 \& unsigned int *outlen,
91 \& void *arg),
92 \& void *arg);
93 \& void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx,
94 \& int (*cb)(SSL *s,
95 \& unsigned char **out,
96 \& unsigned char *outlen,
97 \& const unsigned char *in,
98 \& unsigned int inlen,
99 \& void *arg),
100 \& void *arg);
101 \& int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
102 \& const unsigned char *server,
103 \& unsigned int server_len,
104 \& const unsigned char *client,
105 \& unsigned int client_len);
106 \& void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
107 \& unsigned *len);
108 .Ve
109 .SH DESCRIPTION
110 .IX Header "DESCRIPTION"
111 \&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR are used by the client to
112 set the list of protocols available to be negotiated. The \fBprotos\fR must be in
113 protocol-list format, described below. The length of \fBprotos\fR is specified in
114 \&\fBprotos_len\fR. Setting \fBprotos_len\fR to 0 clears any existing list of ALPN
115 protocols and no ALPN extension will be sent to the server.
116 .PP
117 \&\fBSSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a
118 server to select which protocol to use for the incoming connection. When \fBcb\fR
119 is NULL, ALPN is not used. The \fBarg\fR value is a pointer which is passed to
120 the application callback.
121 .PP
122 \&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a
123 vector in protocol-list format. The value of the \fBout\fR, \fBoutlen\fR vector
124 should be set to the value of a single protocol selected from the \fBin\fR,
125 \&\fBinlen\fR vector. The \fBout\fR buffer may point directly into \fBin\fR, or to a
126 buffer that outlives the handshake. The \fBarg\fR parameter is the pointer set via
127 \&\fBSSL_CTX_set_alpn_select_cb()\fR.
128 .PP
129 \&\fBSSL_select_next_proto()\fR is a helper function used to select protocols. It
130 implements the standard protocol selection. It is expected that this function
131 is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR,
132 \&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol-list format
133 described below. The first item in the \fBserver\fR, \fBserver_len\fR list that
134 matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned
135 in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or
136 \&\fBclient\fR, so it should be copied immediately. The client list must include at
137 least one valid (nonempty) protocol entry in the list.
138 .PP
139 The \fBSSL_select_next_proto()\fR helper function can be useful from either the ALPN
140 callback or the NPN callback (described below). If no match is found, the first
141 item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR and
142 \&\fBOPENSSL_NPN_NO_OVERLAP\fR is returned. This can be useful when implementing
143 the NPN callback. In the ALPN case, the value returned in \fBout\fR and \fBoutlen\fR
144 must be ignored if \fBOPENSSL_NPN_NO_OVERLAP\fR has been returned from
145 \&\fBSSL_select_next_proto()\fR.
146 .PP
147 \&\fBSSL_CTX_set_next_proto_select_cb()\fR sets a callback \fBcb\fR that is called when a
148 client needs to select a protocol from the server's provided list, and a
149 user-defined pointer argument \fBarg\fR which will be passed to this callback.
150 For the callback itself, \fBout\fR
151 must be set to point to the selected protocol (which may be within \fBin\fR).
152 The length of the protocol name must be written into \fBoutlen\fR. The
153 server's advertised protocols are provided in \fBin\fR and \fBinlen\fR. The
154 callback can assume that \fBin\fR is syntactically valid. The client must
155 select a protocol (although it may be an empty, zero length protocol). It is
156 fatal to the connection if this callback returns a value other than
157 \&\fBSSL_TLSEXT_ERR_OK\fR or if the zero length protocol is selected. The \fBarg\fR
158 parameter is the pointer set via \fBSSL_CTX_set_next_proto_select_cb()\fR.
159 .PP
160 \&\fBSSL_CTX_set_next_protos_advertised_cb()\fR sets a callback \fBcb\fR that is called
161 when a TLS server needs a list of supported protocols for Next Protocol
162 Negotiation. The returned list must be in protocol-list format, described
163 below. The list is
164 returned by setting \fBout\fR to point to it and \fBoutlen\fR to its length. This
165 memory will not be modified, but the \fBSSL\fR does keep a
166 reference to it. The callback should return \fBSSL_TLSEXT_ERR_OK\fR if it
167 wishes to advertise. Otherwise, no such extension will be included in the
168 ServerHello.
169 .PP
170 \&\fBSSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR
171 with length \fBlen\fR. It is not NUL-terminated. \fBdata\fR is set to NULL and \fBlen\fR
172 is set to 0 if no protocol has been selected. \fBdata\fR must not be freed.
173 .PP
174 \&\fBSSL_get0_next_proto_negotiated()\fR sets \fBdata\fR and \fBlen\fR to point to the
175 client's requested protocol for this connection. If the client did not
176 request any protocol or NPN is not enabled, then \fBdata\fR is set to NULL and
177 \&\fBlen\fR to 0. Note that
178 the client can request any protocol it chooses. The value returned from
179 this function need not be a member of the list of supported protocols
180 provided by the callback.
181 .PP
182 NPN functionality cannot be used with QUIC SSL objects. Use of ALPN is mandatory
183 when using QUIC SSL objects. \fBSSL_CTX_set_next_protos_advertised_cb()\fR and
184 \&\fBSSL_CTX_set_next_proto_select_cb()\fR have no effect if called on a QUIC SSL
185 context.
186 .SH NOTES
187 .IX Header "NOTES"
188 The protocol-lists must be in wire-format, which is defined as a vector of
189 nonempty, 8\-bit length-prefixed, byte strings. The length-prefix byte is not
190 included in the length. Each string is limited to 255 bytes. A byte-string
191 length of 0 is invalid. A truncated byte-string is invalid. The length of the
192 vector is not in the vector itself, but in a separate variable.
193 .PP
194 Example:
195 .PP
196 .Vb 5
197 \& unsigned char vector[] = {
198 \& 6, \*(Aqs\*(Aq, \*(Aqp\*(Aq, \*(Aqd\*(Aq, \*(Aqy\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq,
199 \& 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq1\*(Aq
200 \& };
201 \& unsigned int length = sizeof(vector);
202 .Ve
203 .PP
204 The ALPN callback is executed after the servername callback; as that servername
205 callback may update the SSL_CTX, and subsequently, the ALPN callback.
206 .PP
207 If there is no ALPN proposed in the ClientHello, the ALPN callback is not
208 invoked.
209 .SH "RETURN VALUES"
210 .IX Header "RETURN VALUES"
211 \&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR return 0 on success, and
212 non\-0 on failure. WARNING: these functions reverse the return value convention.
213 .PP
214 \&\fBSSL_select_next_proto()\fR returns one of the following:
215 .IP OPENSSL_NPN_NEGOTIATED 4
216 .IX Item "OPENSSL_NPN_NEGOTIATED"
217 A match was found and is returned in \fBout\fR, \fBoutlen\fR.
218 .IP OPENSSL_NPN_NO_OVERLAP 4
219 .IX Item "OPENSSL_NPN_NO_OVERLAP"
220 No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in
221 \&\fBout\fR, \fBoutlen\fR (or \fBNULL\fR and 0 in the case where the first entry in
222 \&\fBclient\fR is invalid).
223 .PP
224 The ALPN select callback \fBcb\fR, must return one of the following:
225 .IP SSL_TLSEXT_ERR_OK 4
226 .IX Item "SSL_TLSEXT_ERR_OK"
227 ALPN protocol selected.
228 .IP SSL_TLSEXT_ERR_ALERT_FATAL 4
229 .IX Item "SSL_TLSEXT_ERR_ALERT_FATAL"
230 There was no overlap between the client's supplied list and the server
231 configuration.
232 .IP SSL_TLSEXT_ERR_NOACK 4
233 .IX Item "SSL_TLSEXT_ERR_NOACK"
234 ALPN protocol not selected, e.g., because no ALPN protocols are configured for
235 this connection.
236 .PP
237 The callback set using \fBSSL_CTX_set_next_proto_select_cb()\fR should return
238 \&\fBSSL_TLSEXT_ERR_OK\fR if successful. Any other value is fatal to the connection.
239 .PP
240 The callback set using \fBSSL_CTX_set_next_protos_advertised_cb()\fR should return
241 \&\fBSSL_TLSEXT_ERR_OK\fR if it wishes to advertise. Otherwise, no such extension
242 will be included in the ServerHello.
243 .SH "SEE ALSO"
244 .IX Header "SEE ALSO"
245 \&\fBssl\fR\|(7), \fBSSL_CTX_set_tlsext_servername_callback\fR\|(3),
246 \&\fBSSL_CTX_set_tlsext_servername_arg\fR\|(3)
247 .SH COPYRIGHT
248 .IX Header "COPYRIGHT"
249 Copyright 2016\-2024 The OpenSSL Project Authors. All Rights Reserved.
250 .PP
251 Licensed under the Apache License 2.0 (the "License"). You may not use
252 this file except in compliance with the License. You can obtain a copy
253 in the file LICENSE in the source distribution or at
254 <https://www.openssl.org/source/license.html>.