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