1=pod
2
3=head1 NAME
4
5SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
6SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb,
7SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated
8- handle application layer protocol negotiation (ALPN)
9
10=head1 SYNOPSIS
11
12 #include <openssl/ssl.h>
13
14 int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
15                             unsigned int protos_len);
16 int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
17                         unsigned int protos_len);
18 void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
19                                 int (*cb) (SSL *ssl,
20                                            const unsigned char **out,
21                                            unsigned char *outlen,
22                                            const unsigned char *in,
23                                            unsigned int inlen,
24                                            void *arg), void *arg);
25 void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
26                             unsigned int *len);
27
28 void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx,
29                                            int (*cb)(SSL *ssl,
30                                                      const unsigned char **out,
31                                                      unsigned int *outlen,
32                                                      void *arg),
33                                            void *arg);
34 void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx,
35                               int (*cb)(SSL *s,
36                                         unsigned char **out,
37                                         unsigned char *outlen,
38                                         const unsigned char *in,
39                                         unsigned int inlen,
40                                         void *arg),
41                               void *arg);
42 int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
43                           const unsigned char *server,
44                           unsigned int server_len,
45                           const unsigned char *client,
46                           unsigned int client_len);
47 void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
48                             unsigned *len);
49
50=head1 DESCRIPTION
51
52SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the client to
53set the list of protocols available to be negotiated. The B<protos> must be in
54protocol-list format, described below. The length of B<protos> is specified in
55B<protos_len>. Setting B<protos_len> to 0 clears any existing list of ALPN
56protocols and no ALPN extension will be sent to the server.
57
58SSL_CTX_set_alpn_select_cb() sets the application callback B<cb> used by a
59server to select which protocol to use for the incoming connection. When B<cb>
60is NULL, ALPN is not used. The B<arg> value is a pointer which is passed to
61the application callback.
62
63B<cb> is the application defined callback. The B<in>, B<inlen> parameters are a
64vector in protocol-list format. The value of the B<out>, B<outlen> vector
65should be set to the value of a single protocol selected from the B<in>,
66B<inlen> vector. The B<out> buffer may point directly into B<in>, or to a
67buffer that outlives the handshake. The B<arg> parameter is the pointer set via
68SSL_CTX_set_alpn_select_cb().
69
70SSL_select_next_proto() is a helper function used to select protocols. It
71implements the standard protocol selection. It is expected that this function
72is called from the application callback B<cb>. The protocol data in B<server>,
73B<server_len> and B<client>, B<client_len> must be in the protocol-list format
74described below. The first item in the B<server>, B<server_len> list that
75matches an item in the B<client>, B<client_len> list is selected, and returned
76in B<out>, B<outlen>. The B<out> value will point into either B<server> or
77B<client>, so it should be copied immediately. The client list must include at
78least one valid (nonempty) protocol entry in the list.
79
80The SSL_select_next_proto() helper function can be useful from either the ALPN
81callback or the NPN callback (described below). If no match is found, the first
82item in B<client>, B<client_len> is returned in B<out>, B<outlen> and
83B<OPENSSL_NPN_NO_OVERLAP> is returned. This can be useful when implementing
84the NPN callback. In the ALPN case, the value returned in B<out> and B<outlen>
85must be ignored if B<OPENSSL_NPN_NO_OVERLAP> has been returned from
86SSL_select_next_proto().
87
88SSL_CTX_set_next_proto_select_cb() sets a callback B<cb> that is called when a
89client needs to select a protocol from the server's provided list, and a
90user-defined pointer argument B<arg> which will be passed to this callback.
91For the callback itself, B<out>
92must be set to point to the selected protocol (which may be within B<in>).
93The length of the protocol name must be written into B<outlen>. The
94server's advertised protocols are provided in B<in> and B<inlen>. The
95callback can assume that B<in> is syntactically valid. The client must
96select a protocol (although it may be an empty, zero length protocol). It is
97fatal to the connection if this callback returns a value other than
98B<SSL_TLSEXT_ERR_OK> or if the zero length protocol is selected. The B<arg>
99parameter is the pointer set via SSL_CTX_set_next_proto_select_cb().
100
101SSL_CTX_set_next_protos_advertised_cb() sets a callback B<cb> that is called
102when a TLS server needs a list of supported protocols for Next Protocol
103Negotiation. The returned list must be in protocol-list format, described
104below.  The list is
105returned by setting B<out> to point to it and B<outlen> to its length. This
106memory will not be modified, but the B<SSL> does keep a
107reference to it. The callback should return B<SSL_TLSEXT_ERR_OK> if it
108wishes to advertise. Otherwise, no such extension will be included in the
109ServerHello.
110
111SSL_get0_alpn_selected() returns a pointer to the selected protocol in B<data>
112with length B<len>. It is not NUL-terminated. B<data> is set to NULL and B<len>
113is set to 0 if no protocol has been selected. B<data> must not be freed.
114
115SSL_get0_next_proto_negotiated() sets B<data> and B<len> to point to the
116client's requested protocol for this connection. If the client did not
117request any protocol or NPN is not enabled, then B<data> is set to NULL and
118B<len> to 0. Note that
119the client can request any protocol it chooses. The value returned from
120this function need not be a member of the list of supported protocols
121provided by the callback.
122
123=head1 NOTES
124
125The protocol-lists must be in wire-format, which is defined as a vector of
126nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
127included in the length. Each string is limited to 255 bytes. A byte-string
128length of 0 is invalid. A truncated byte-string is invalid. The length of the
129vector is not in the vector itself, but in a separate variable.
130
131Example:
132
133 unsigned char vector[] = {
134     6, 's', 'p', 'd', 'y', '/', '1',
135     8, 'h', 't', 't', 'p', '/', '1', '.', '1'
136 };
137 unsigned int length = sizeof(vector);
138
139The ALPN callback is executed after the servername callback; as that servername
140callback may update the SSL_CTX, and subsequently, the ALPN callback.
141
142If there is no ALPN proposed in the ClientHello, the ALPN callback is not
143invoked.
144
145=head1 RETURN VALUES
146
147SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
148non-0 on failure. WARNING: these functions reverse the return value convention.
149
150SSL_select_next_proto() returns one of the following:
151
152=over 4
153
154=item OPENSSL_NPN_NEGOTIATED
155
156A match was found and is returned in B<out>, B<outlen>.
157
158=item OPENSSL_NPN_NO_OVERLAP
159
160No match was found. The first item in B<client>, B<client_len> is returned in
161B<out>, B<outlen> (or B<NULL> and 0 in the case where the first entry in
162B<client> is invalid).
163
164=back
165
166The ALPN select callback B<cb>, must return one of the following:
167
168=over 4
169
170=item SSL_TLSEXT_ERR_OK
171
172ALPN protocol selected.
173
174=item SSL_TLSEXT_ERR_ALERT_FATAL
175
176There was no overlap between the client's supplied list and the server
177configuration.
178
179=item SSL_TLSEXT_ERR_NOACK
180
181ALPN protocol not selected, e.g., because no ALPN protocols are configured for
182this connection.
183
184=back
185
186The callback set using SSL_CTX_set_next_proto_select_cb() should return
187B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection.
188
189The callback set using SSL_CTX_set_next_protos_advertised_cb() should return
190B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension
191will be included in the ServerHello.
192
193=head1 SEE ALSO
194
195L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
196L<SSL_CTX_set_tlsext_servername_arg(3)>
197
198=head1 COPYRIGHT
199
200Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
201
202Licensed under the Apache License 2.0 (the "License").  You may not use
203this file except in compliance with the License.  You can obtain a copy
204in the file LICENSE in the source distribution or at
205L<https://www.openssl.org/source/license.html>.
206
207=cut
208