1SSL_CTX_SET_ALPN_SELECT_CB(3)       OpenSSL      SSL_CTX_SET_ALPN_SELECT_CB(3)
2
3
4

NAME

6       SSL_CTX_set_alpn_protos, SSL_set_alpn_protos,
7       SSL_CTX_set_alpn_select_cb, SSL_CTX_set_next_proto_select_cb,
8       SSL_CTX_set_next_protos_advertised_cb, SSL_select_next_proto,
9       SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated - handle
10       application layer protocol negotiation (ALPN)
11

SYNOPSIS

13        #include <openssl/ssl.h>
14
15        int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
16                                    unsigned int protos_len);
17        int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
18                                unsigned int protos_len);
19        void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
20                                        int (*cb) (SSL *ssl,
21                                                   const unsigned char **out,
22                                                   unsigned char *outlen,
23                                                   const unsigned char *in,
24                                                   unsigned int inlen,
25                                                   void *arg), void *arg);
26        void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
27                                    unsigned int *len);
28
29        void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx,
30                                                   int (*cb)(SSL *ssl,
31                                                             const unsigned char **out,
32                                                             unsigned int *outlen,
33                                                             void *arg),
34                                                   void *arg);
35        void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx,
36                                      int (*cb)(SSL *s,
37                                                unsigned char **out,
38                                                unsigned char *outlen,
39                                                const unsigned char *in,
40                                                unsigned int inlen,
41                                                void *arg),
42                                      void *arg);
43        int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
44                                  const unsigned char *server,
45                                  unsigned int server_len,
46                                  const unsigned char *client,
47                                  unsigned int client_len)
48        void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
49                                    unsigned *len);
50

DESCRIPTION

52       SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() are used by the
53       client to set the list of protocols available to be negotiated. The
54       protos must be in protocol-list format, described below. The length of
55       protos is specified in protos_len.
56
57       SSL_CTX_set_alpn_select_cb() sets the application callback cb used by a
58       server to select which protocol to use for the incoming connection.
59       When cb is NULL, ALPN is not used. The arg value is a pointer which is
60       passed to the application callback.
61
62       cb is the application defined callback. The in, inlen parameters are a
63       vector in protocol-list format. The value of the out, outlen vector
64       should be set to the value of a single protocol selected from the in,
65       inlen vector. The out buffer may point directly into in, or to a buffer
66       that outlives the handshake. The arg parameter is the pointer set via
67       SSL_CTX_set_alpn_select_cb().
68
69       SSL_select_next_proto() is a helper function used to select protocols.
70       It implements the standard protocol selection. It is expected that this
71       function is called from the application callback cb. The protocol data
72       in server, server_len and client, client_len must be in the protocol-
73       list format described below. The first item in the server, server_len
74       list that matches an item in the client, client_len list is selected,
75       and returned in out, outlen. The out value will point into either
76       server or client, so it should be copied immediately. If no match is
77       found, the first item in client, client_len is returned in out, outlen.
78       This function can also be used in the NPN callback.
79
80       SSL_CTX_set_next_proto_select_cb() sets a callback cb that is called
81       when a client needs to select a protocol from the server's provided
82       list, and a user-defined pointer argument arg which will be passed to
83       this callback.  For the callback itself, out must be set to point to
84       the selected protocol (which may be within in).  The length of the
85       protocol name must be written into outlen. The server's advertised
86       protocols are provided in in and inlen. The callback can assume that in
87       is syntactically valid. The client must select a protocol. It is fatal
88       to the connection if this callback returns a value other than
89       SSL_TLSEXT_ERR_OK. The arg parameter is the pointer set via
90       SSL_CTX_set_next_proto_select_cb().
91
92       SSL_CTX_set_next_protos_advertised_cb() sets a callback cb that is
93       called when a TLS server needs a list of supported protocols for Next
94       Protocol Negotiation. The returned list must be in protocol-list
95       format, described below.  The list is returned by setting out to point
96       to it and outlen to its length. This memory will not be modified, but
97       the SSL does keep a reference to it. The callback should return
98       SSL_TLSEXT_ERR_OK if it wishes to advertise. Otherwise, no such
99       extension will be included in the ServerHello.
100
101       SSL_get0_alpn_selected() returns a pointer to the selected protocol in
102       data with length len. It is not NUL-terminated. data is set to NULL and
103       len is set to 0 if no protocol has been selected. data must not be
104       freed.
105
106       SSL_get0_next_proto_negotiated() sets data and len to point to the
107       client's requested protocol for this connection. If the client did not
108       request any protocol or NPN is not enabled, then data is set to NULL
109       and len to 0. Note that the client can request any protocol it chooses.
110       The value returned from this function need not be a member of the list
111       of supported protocols provided by the callback.
112

NOTES

114       The protocol-lists must be in wire-format, which is defined as a vector
115       of nonempty, 8-bit length-prefixed, byte strings. The length-prefix
116       byte is not included in the length. Each string is limited to 255
117       bytes. A byte-string length of 0 is invalid. A truncated byte-string is
118       invalid. The length of the vector is not in the vector itself, but in a
119       separate variable.
120
121       Example:
122
123        unsigned char vector[] = {
124            6, 's', 'p', 'd', 'y', '/', '1',
125            8, 'h', 't', 't', 'p', '/', '1', '.', '1'
126        };
127        unsigned int length = sizeof(vector);
128
129       The ALPN callback is executed after the servername callback; as that
130       servername callback may update the SSL_CTX, and subsequently, the ALPN
131       callback.
132
133       If there is no ALPN proposed in the ClientHello, the ALPN callback is
134       not invoked.
135

RETURN VALUES

137       SSL_CTX_set_alpn_protos() and SSL_set_alpn_protos() return 0 on
138       success, and non-0 on failure. WARNING: these functions reverse the
139       return value convention.
140
141       SSL_select_next_proto() returns one of the following:
142
143       OPENSSL_NPN_NEGOTIATED
144           A match was found and is returned in out, outlen.
145
146       OPENSSL_NPN_NO_OVERLAP
147           No match was found. The first item in client, client_len is
148           returned in out, outlen.
149
150       The ALPN select callback cb, must return one of the following:
151
152       SSL_TLSEXT_ERR_OK
153           ALPN protocol selected.
154
155       SSL_TLSEXT_ERR_ALERT_FATAL
156           There was no overlap between the client's supplied list and the
157           server configuration.
158
159       SSL_TLSEXT_ERR_NOACK
160           ALPN protocol not selected, e.g., because no ALPN protocols are
161           configured for this connection.
162
163       The callback set using SSL_CTX_set_next_proto_select_cb() should return
164       SSL_TLSEXT_ERR_OK if successful. Any other value is fatal to the
165       connection.
166
167       The callback set using SSL_CTX_set_next_protos_advertised_cb() should
168       return SSL_TLSEXT_ERR_OK if it wishes to advertise. Otherwise, no such
169       extension will be included in the ServerHello.
170

SEE ALSO

172       ssl(7), SSL_CTX_set_tlsext_servername_callback(3),
173       SSL_CTX_set_tlsext_servername_arg(3)
174
176       Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
177
178       Licensed under the OpenSSL license (the "License").  You may not use
179       this file except in compliance with the License.  You can obtain a copy
180       in the file LICENSE in the source distribution or at
181       <https://www.openssl.org/source/license.html>.
182
183
184
1851.1.1k                            2021-03-26     SSL_CTX_SET_ALPN_SELECT_CB(3)
Impressum