1 .\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.35)
4 .\" ========================================================================
5 .de Sp \" Vertical space (when we can't use .PP)
9 .de Vb \" Begin verbatim text
14 .de Ve \" End verbatim text
18 .\" Set up some character translations and predefined strings. \*(-- will
19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
20 .\" double quote, and \*(R" will give a right double quote. \*(C+ will
21 .\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22 .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23 .\" nothing in troff, for use with C<>.
25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
29 . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30 . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
45 .\" Escape single quotes in literal strings from groff's Unicode transform.
49 .\" If the F register is >0, we'll generate index entries on stderr for
50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
51 .\" entries marked with X<> in POD. Of course, you'll have to process the
52 .\" output yourself in some meaningful fashion.
54 .\" Avoid warning from groff about undefined register 'F'.
60 . tm Index:\\$1\t\\n%\t"\\$2"
68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
69 .\" Fear. Run. Save yourself. No user-serviceable parts.
70 . \" fudge factors for nroff and troff
79 . ds #H ((1u-(\\\\n(.fu%2u))*.13m)
85 . \" simple accents for nroff and troff
95 . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
96 . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
97 . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
98 . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
99 . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
100 . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
102 . \" troff and (daisy-wheel) nroff accents
103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
110 .ds ae a\h'-(\w'a'u*4/10)'e
111 .ds Ae A\h'-(\w'A'u*4/10)'E
112 . \" corrections for vroff
113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
115 . \" for low resolution devices (crt and lpr)
116 .if \n(.H>23 .if \n(.V>19 \
129 .\" ========================================================================
131 .IX Title "SSL_CTX_set_alpn_select_cb 3"
132 .TH SSL_CTX_set_alpn_select_cb 3 "2017-01-26" "1.0.2k" "OpenSSL"
133 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
134 .\" way too many mistakes in technical documents.
138 SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb,
139 SSL_select_next_proto, SSL_get0_alpn_selected \- handle application layer
140 protocol negotiation (ALPN)
142 .IX Header "SYNOPSIS"
144 \& #include <openssl/ssl.h>
146 \& int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
147 \& unsigned protos_len);
148 \& int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
149 \& unsigned protos_len);
150 \& void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
151 \& int (*cb) (SSL *ssl,
152 \& const unsigned char **out,
153 \& unsigned char *outlen,
154 \& const unsigned char *in,
155 \& unsigned int inlen,
156 \& void *arg), void *arg);
157 \& int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
158 \& const unsigned char *server,
159 \& unsigned int server_len,
160 \& const unsigned char *client,
161 \& unsigned int client_len)
162 \& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
163 \& unsigned int *len);
166 .IX Header "DESCRIPTION"
167 \&\fISSL_CTX_set_alpn_protos()\fR and \fISSL_set_alpn_protos()\fR are used by the client to
168 set the list of protocols available to be negotiated. The \fBprotos\fR must be in
169 protocol-list format, described below. The length of \fBprotos\fR is specified in
172 \&\fISSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a
173 server to select which protocol to use for the incoming connection. When \fBcb\fR
174 is \s-1NULL, ALPN\s0 is not used. The \fBarg\fR value is a pointer which is passed to
175 the application callback.
177 \&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a
178 vector in protocol-list format. The value of the \fBout\fR, \fBoutlen\fR vector
179 should be set to the value of a single protocol selected from the \fBin\fR,
180 \&\fBinlen\fR vector. The \fBarg\fR parameter is the pointer set via
181 \&\fISSL_CTX_set_alpn_select_cb()\fR.
183 \&\fISSL_select_next_proto()\fR is a helper function used to select protocols. It
184 implements the standard protocol selection. It is expected that this function
185 is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR,
186 \&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol-list format
187 described below. The first item in the \fBserver\fR, \fBserver_len\fR list that
188 matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned
189 in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or
190 \&\fBclient\fR, so it should be copied immediately. If no match is found, the first
191 item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR. This
192 function can also be used in the \s-1NPN\s0 callback.
194 \&\fISSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR
195 with length \fBlen\fR. It is not NUL-terminated. \fBdata\fR is set to \s-1NULL\s0 and \fBlen\fR
196 is set to 0 if no protocol has been selected. \fBdata\fR must not be freed.
199 The protocol-lists must be in wire-format, which is defined as a vector of
200 non-empty, 8\-bit length-prefixed, byte strings. The length-prefix byte is not
201 included in the length. Each string is limited to 255 bytes. A byte-string
202 length of 0 is invalid. A truncated byte-string is invalid. The length of the
203 vector is not in the vector itself, but in a separate variable.
208 \& unsigned char vector[] = {
209 \& 6, \*(Aqs\*(Aq, \*(Aqp\*(Aq, \*(Aqd\*(Aq, \*(Aqy\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq,
210 \& 8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq1\*(Aq
212 \& unsigned int length = sizeof(vector);
215 The \s-1ALPN\s0 callback is executed after the servername callback; as that servername
216 callback may update the \s-1SSL_CTX,\s0 and subsequently, the \s-1ALPN\s0 callback.
218 If there is no \s-1ALPN\s0 proposed in the ClientHello, the \s-1ALPN\s0 callback is not
221 .IX Header "RETURN VALUES"
222 \&\fISSL_CTX_set_alpn_protos()\fR and \fISSL_set_alpn_protos()\fR return 0 on success, and
223 non\-0 on failure. \s-1WARNING:\s0 these functions reverse the return value convention.
225 \&\fISSL_select_next_proto()\fR returns one of the following:
226 .IP "\s-1OPENSSL_NPN_NEGOTIATED\s0" 4
227 .IX Item "OPENSSL_NPN_NEGOTIATED"
228 A match was found and is returned in \fBout\fR, \fBoutlen\fR.
229 .IP "\s-1OPENSSL_NPN_NO_OVERLAP\s0" 4
230 .IX Item "OPENSSL_NPN_NO_OVERLAP"
231 No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in
232 \&\fBout\fR, \fBoutlen\fR.
234 The \s-1ALPN\s0 select callback \fBcb\fR, must return one of the following:
235 .IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4
236 .IX Item "SSL_TLSEXT_ERR_OK"
237 \&\s-1ALPN\s0 protocol selected.
238 .IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4
239 .IX Item "SSL_TLSEXT_ERR_NOACK"
240 \&\s-1ALPN\s0 protocol not selected.
242 .IX Header "SEE ALSO"
243 \&\fIssl\fR\|(3), \fISSL_CTX_set_tlsext_servername_callback\fR\|(3),
244 \&\fISSL_CTX_set_tlsext_servername_arg\fR\|(3)