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 implementating
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
123NPN functionality cannot be used with QUIC SSL objects. Use of ALPN is mandatory
124when using QUIC SSL objects. SSL_CTX_set_next_protos_advertised_cb() and
125SSL_CTX_set_next_proto_select_cb() have no effect if called on a QUIC SSL
126context.
127
128=head1 NOTES
129
130The protocol-lists must be in wire-format, which is defined as a vector of
131nonempty, 8-bit length-prefixed, byte strings. The length-prefix byte is not
132included in the length. Each string is limited to 255 bytes. A byte-string
133length of 0 is invalid. A truncated byte-string is invalid. The length of the
134vector is not in the vector itself, but in a separate variable.
135
136Example:
137
138 unsigned char vector[] = {
139     6, 's', 'p', 'd', 'y', '/', '1',
140     8, 'h', 't', 't', 'p', '/', '1', '.', '1'
141 };
142 unsigned int length = sizeof(vector);
143
144The ALPN callback is executed after the servername callback; as that servername
145callback may update the SSL_CTX, and subsequently, the ALPN callback.
146
147If there is no ALPN proposed in the ClientHello, the ALPN callback is not
148invoked.
149
150=head1 RETURN VALUES
151
152SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on success, and
153non-0 on failure. WARNING: these functions reverse the return value convention.
154
155SSL_select_next_proto() returns one of the following:
156
157=over 4
158
159=item OPENSSL_NPN_NEGOTIATED
160
161A match was found and is returned in B<out>, B<outlen>.
162
163=item OPENSSL_NPN_NO_OVERLAP
164
165No match was found. The first item in B<client>, B<client_len> is returned in
166B<out>, B<outlen> (or B<NULL> and 0 in the case where the first entry in
167B<client> is invalid).
168
169=back
170
171The ALPN select callback B<cb>, must return one of the following:
172
173=over 4
174
175=item SSL_TLSEXT_ERR_OK
176
177ALPN protocol selected.
178
179=item SSL_TLSEXT_ERR_ALERT_FATAL
180
181There was no overlap between the client's supplied list and the server
182configuration.
183
184=item SSL_TLSEXT_ERR_NOACK
185
186ALPN protocol not selected, e.g., because no ALPN protocols are configured for
187this connection.
188
189=back
190
191The callback set using SSL_CTX_set_next_proto_select_cb() should return
192B<SSL_TLSEXT_ERR_OK> if successful. Any other value is fatal to the connection.
193
194The callback set using SSL_CTX_set_next_protos_advertised_cb() should return
195B<SSL_TLSEXT_ERR_OK> if it wishes to advertise. Otherwise, no such extension
196will be included in the ServerHello.
197
198=head1 SEE ALSO
199
200L<ssl(7)>, L<SSL_CTX_set_tlsext_servername_callback(3)>,
201L<SSL_CTX_set_tlsext_servername_arg(3)>
202
203=head1 COPYRIGHT
204
205Copyright 2016-2023 The OpenSSL Project Authors. All Rights Reserved.
206
207Licensed under the Apache License 2.0 (the "License").  You may not use
208this file except in compliance with the License.  You can obtain a copy
209in the file LICENSE in the source distribution or at
210L<https://www.openssl.org/source/license.html>.
211
212=cut
213