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