| blob | 2c0905123bfe59623a4e81a93c44fa29b4407c27 |
1 .\" $OpenBSD: SSL_CTX_set_alpn_select_cb.3,v 1.5 2017/08/28 17:36:58 jsing Exp $
2 .\" OpenSSL 87b81496 Apr 19 12:38:27 2017 -0400
3 .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
4 .\"
5 .\" This file was written by Todd Short <tshort@akamai.com>.
6 .\" Copyright (c) 2016 The OpenSSL Project. All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\"
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\"
15 .\" 2. Redistributions in binary form must reproduce the above copyright
16 .\" notice, this list of conditions and the following disclaimer in
17 .\" the documentation and/or other materials provided with the
18 .\" distribution.
19 .\"
20 .\" 3. All advertising materials mentioning features or use of this
21 .\" software must display the following acknowledgment:
22 .\" "This product includes software developed by the OpenSSL Project
23 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
24 .\"
25 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
26 .\" endorse or promote products derived from this software without
27 .\" prior written permission. For written permission, please contact
28 .\" openssl-core@openssl.org.
29 .\"
30 .\" 5. Products derived from this software may not be called "OpenSSL"
31 .\" nor may "OpenSSL" appear in their names without prior written
32 .\" permission of the OpenSSL Project.
33 .\"
34 .\" 6. Redistributions of any form whatsoever must retain the following
35 .\" acknowledgment:
36 .\" "This product includes software developed by the OpenSSL Project
37 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
38 .\"
39 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
40 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
41 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
42 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
43 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
44 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
45 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
46 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
48 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
49 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
50 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
51 .\"
52 .Dd $Mdocdate: August 28 2017 $
53 .Dt SSL_CTX_SET_ALPN_SELECT_CB 3
54 .Os
55 .Sh NAME
56 .Nm SSL_CTX_set_alpn_protos ,
57 .Nm SSL_set_alpn_protos ,
58 .Nm SSL_CTX_set_alpn_select_cb ,
59 .Nm SSL_select_next_proto ,
60 .Nm SSL_get0_alpn_selected
61 .Nd handle application layer protocol negotiation (ALPN)
62 .Sh SYNOPSIS
63 .In openssl/ssl.h
64 .Ft int
65 .Fo SSL_CTX_set_alpn_protos
66 .Fa "SSL_CTX *ctx"
67 .Fa "const unsigned char *protos"
68 .Fa "unsigned int protos_len"
69 .Fc
70 .Ft int
71 .Fo SSL_set_alpn_protos
72 .Fa "SSL *ssl"
73 .Fa "const unsigned char *protos"
74 .Fa "unsigned int protos_len"
75 .Fc
76 .Ft void
77 .Fo SSL_CTX_set_alpn_select_cb
78 .Fa "SSL_CTX *ctx"
79 .Fa "int (*cb)(SSL *ssl, const unsigned char **out,\
80 unsigned char *outlen, const unsigned char *in,\
81 unsigned int inlen, void *arg)"
82 .Fa "void *arg"
83 .Fc
84 .Ft int
85 .Fo SSL_select_next_proto
86 .Fa "unsigned char **out"
87 .Fa "unsigned char *outlen"
88 .Fa "const unsigned char *server"
89 .Fa "unsigned int server_len"
90 .Fa "const unsigned char *client"
91 .Fa "unsigned int client_len"
92 .Fc
93 .Ft void
94 .Fo SSL_get0_alpn_selected
95 .Fa "const SSL *ssl"
96 .Fa "const unsigned char **data"
97 .Fa "unsigned int *len"
98 .Fc
99 .Sh DESCRIPTION
100 .Fn SSL_CTX_set_alpn_protos
101 and
102 .Fn SSL_set_alpn_protos
103 are used by the client to set the list of protocols available to be
104 negotiated.
105 The
106 .Fa protos
107 must be in protocol-list format, described below.
108 The length of
109 .Fa protos
110 is specified in
111 .Fa protos_len .
112 .Pp
113 .Fn SSL_CTX_set_alpn_select_cb
114 sets the application callback
115 .Fa cb
116 used by a server to select which protocol to use for the incoming
117 connection.
118 When
119 .Fa cb
120 is
121 .Dv NULL ,
122 ALPN is not used.
123 The
124 .Fa arg
125 value is a pointer which is passed to the application callback.
126 .Pp
127 .Fa cb
128 is the application defined callback.
129 The
130 .Fa in ,
131 .Fa inlen
132 parameters are a vector in protocol-list format.
133 The value of the
134 .Fa out ,
135 .Fa outlen
136 vector should be set to the value of a single protocol selected from the
137 .Fa in ,
138 .Fa inlen
139 vector.
140 The
141 .Fa out
142 buffer may point directly into
143 .Fa in ,
144 or to a buffer that outlives the handshake.
145 The
146 .Fa arg
147 parameter is the pointer set via
148 .Fn SSL_CTX_set_alpn_select_cb .
149 .Pp
150 .Fn SSL_select_next_proto
151 is a helper function used to select protocols.
152 It implements the standard protocol selection.
153 It is expected that this function is called from the application
154 callback
155 .Fa cb .
156 The protocol data in
157 .Fa server ,
158 .Fa server_len
159 and
160 .Fa client ,
161 .Fa client_len
162 must be in the protocol-list format described below.
163 The first item in the
164 .Fa server ,
165 .Fa server_len
166 list that matches an item in the
167 .Fa client ,
168 .Fa client_len
169 list is selected, and returned in
170 .Fa out ,
171 .Fa outlen .
172 The
173 .Fa out
174 value will point into either
175 .Fa server
176 or
177 .Fa client ,
178 so it should be copied immediately.
179 If no match is found, the first item in
180 .Fa client ,
181 .Fa client_len
182 is returned in
183 .Fa out ,
184 .Fa outlen .
185 .Pp
186 .Fn SSL_get0_alpn_selected
187 returns a pointer to the selected protocol in
188 .Fa data
189 with length
190 .Fa len .
191 It is not NUL-terminated.
192 .Fa data
193 is set to
194 .Dv NULL
195 and
196 .Fa len
197 is set to 0 if no protocol has been selected.
198 .Fa data
199 must not be freed.
200 .Pp
201 The protocol-lists must be in wire-format, which is defined as a vector
202 of non-empty, 8-bit length-prefixed byte strings.
203 The length-prefix byte is not included in the length.
204 Each string is limited to 255 bytes.
205 A byte-string length of 0 is invalid.
206 A truncated byte-string is invalid.
207 The length of the vector is not in the vector itself, but in a separate
208 variable.
209 .Pp
210 For example:
211 .Bd -literal
212 unsigned char vector[] = {
213 6, 's', 'p', 'd', 'y', '/', '1',
214 8, 'h', 't', 't', 'p', '/', '1', '.', '1'
215 };
216 unsigned int length = sizeof(vector);
217 .Ed
218 .Pp
219 The ALPN callback is executed after the servername callback; as that
220 servername callback may update the SSL_CTX, and subsequently, the ALPN
221 callback.
222 .Pp
223 If there is no ALPN proposed in the ClientHello, the ALPN callback is
224 not invoked.
225 .Sh RETURN VALUES
226 .Fn SSL_CTX_set_alpn_protos
227 and
228 .Fn SSL_set_alpn_protos
229 return 0 on success or non-zero on failure.
230 WARNING: these functions reverse the return value convention.
231 .Pp
232 .Fn SSL_select_next_proto
233 returns one of the following:
234 .Bl -tag -width Ds
235 .It OPENSSL_NPN_NEGOTIATED
236 A match was found and is returned in
237 .Fa out ,
238 .Fa outlen .
239 .It OPENSSL_NPN_NO_OVERLAP
240 No match was found.
241 The first item in
242 .Fa client ,
243 .Fa client_len
244 is returned in
245 .Fa out ,
246 .Fa outlen .
247 .El
248 .Pp
249 The ALPN select callback
250 .Fa cb
251 must return one of the following:
252 .Bl -tag -width Ds
253 .It SSL_TLSEXT_ERR_OK
254 ALPN protocol selected.
255 .It SSL_TLSEXT_ERR_NOACK
256 ALPN protocol not selected.
257 .El
258 .Sh SEE ALSO
259 .Xr ssl 3 ,
260 .Xr SSL_CTX_set_tlsext_servername_arg 3 ,
261 .Xr SSL_CTX_set_tlsext_servername_callback 3