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