secure/lib/libcrypto/man/SSL_CTX_set_alpn_select_cb.3

   1 .\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  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<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  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
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  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.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_CTX_SET_ALPN_SELECT_CB 3"
 136 .TH SSL_CTX_SET_ALPN_SELECT_CB 3 "2019-02-26" "1.1.1b" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_CTX_set_alpn_protos, SSL_set_alpn_protos, SSL_CTX_set_alpn_select_cb, SSL_CTX_set_next_proto_select_cb, SSL_CTX_set_next_protos_advertised_cb, SSL_select_next_proto, SSL_get0_alpn_selected, SSL_get0_next_proto_negotiated \&\- handle application layer protocol negotiation (ALPN)
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
 149 \&                             unsigned int protos_len);
 150 \& int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
 151 \&                         unsigned int protos_len);
 152 \& void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
 153 \&                                 int (*cb) (SSL *ssl,
 154 \&                                            const unsigned char **out,
 155 \&                                            unsigned char *outlen,
 156 \&                                            const unsigned char *in,
 157 \&                                            unsigned int inlen,
 158 \&                                            void *arg), void *arg);
 159 \& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
 160 \&                             unsigned int *len);
 161 \&
 162 \& void SSL_CTX_set_next_protos_advertised_cb(SSL_CTX *ctx,
 163 \&                                            int (*cb)(SSL *ssl,
 164 \&                                                      const unsigned char **out,
 165 \&                                                      unsigned int *outlen,
 166 \&                                                      void *arg),
 167 \&                                            void *arg);
 168 \& void SSL_CTX_set_next_proto_select_cb(SSL_CTX *ctx,
 169 \&                               int (*cb)(SSL *s,
 170 \&                                         unsigned char **out,
 171 \&                                         unsigned char *outlen,
 172 \&                                         const unsigned char *in,
 173 \&                                         unsigned int inlen,
 174 \&                                         void *arg),
 175 \&                               void *arg);
 176 \& int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
 177 \&                           const unsigned char *server,
 178 \&                           unsigned int server_len,
 179 \&                           const unsigned char *client,
 180 \&                           unsigned int client_len)
 181 \& void SSL_get0_next_proto_negotiated(const SSL *s, const unsigned char **data,
 182 \&                             unsigned *len);
 183 .Ve
 184 .SH "DESCRIPTION"
 185 .IX Header "DESCRIPTION"
 186 \&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR are used by the client to
 187 set the list of protocols available to be negotiated. The \fBprotos\fR must be in
 188 protocol-list format, described below. The length of \fBprotos\fR is specified in
 189 \&\fBprotos_len\fR.
 190 .PP
 191 \&\fBSSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a
 192 server to select which protocol to use for the incoming connection. When \fBcb\fR
 193 is \s-1NULL, ALPN\s0 is not used. The \fBarg\fR value is a pointer which is passed to
 194 the application callback.
 195 .PP
 196 \&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a
 197 vector in protocol-list format. The value of the \fBout\fR, \fBoutlen\fR vector
 198 should be set to the value of a single protocol selected from the \fBin\fR,
 199 \&\fBinlen\fR vector. The \fBout\fR buffer may point directly into \fBin\fR, or to a
 200 buffer that outlives the handshake. The \fBarg\fR parameter is the pointer set via
 201 \&\fBSSL_CTX_set_alpn_select_cb()\fR.
 202 .PP
 203 \&\fBSSL_select_next_proto()\fR is a helper function used to select protocols. It
 204 implements the standard protocol selection. It is expected that this function
 205 is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR,
 206 \&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol-list format
 207 described below. The first item in the \fBserver\fR, \fBserver_len\fR list that
 208 matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned
 209 in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or
 210 \&\fBclient\fR, so it should be copied immediately. If no match is found, the first
 211 item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR. This
 212 function can also be used in the \s-1NPN\s0 callback.
 213 .PP
 214 \&\fBSSL_CTX_set_next_proto_select_cb()\fR sets a callback \fBcb\fR that is called when a
 215 client needs to select a protocol from the server's provided list, and a
 216 user-defined pointer argument \fBarg\fR which will be passed to this callback.
 217 For the callback itself, \fBout\fR
 218 must be set to point to the selected protocol (which may be within \fBin\fR).
 219 The length of the protocol name must be written into \fBoutlen\fR. The
 220 server's advertised protocols are provided in \fBin\fR and \fBinlen\fR. The
 221 callback can assume that \fBin\fR is syntactically valid. The client must
 222 select a protocol. It is fatal to the connection if this callback returns
 223 a value other than \fB\s-1SSL_TLSEXT_ERR_OK\s0\fR. The \fBarg\fR parameter is the pointer
 224 set via \fBSSL_CTX_set_next_proto_select_cb()\fR.
 225 .PP
 226 \&\fBSSL_CTX_set_next_protos_advertised_cb()\fR sets a callback \fBcb\fR that is called
 227 when a \s-1TLS\s0 server needs a list of supported protocols for Next Protocol
 228 Negotiation. The returned list must be in protocol-list format, described
 229 below.  The list is
 230 returned by setting \fBout\fR to point to it and \fBoutlen\fR to its length. This
 231 memory will not be modified, but the \fB\s-1SSL\s0\fR does keep a
 232 reference to it. The callback should return \fB\s-1SSL_TLSEXT_ERR_OK\s0\fR if it
 233 wishes to advertise. Otherwise, no such extension will be included in the
 234 ServerHello.
 235 .PP
 236 \&\fBSSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR
 237 with length \fBlen\fR. It is not NUL-terminated. \fBdata\fR is set to \s-1NULL\s0 and \fBlen\fR
 238 is set to 0 if no protocol has been selected. \fBdata\fR must not be freed.
 239 .PP
 240 \&\fBSSL_get0_next_proto_negotiated()\fR sets \fBdata\fR and \fBlen\fR to point to the
 241 client's requested protocol for this connection. If the client did not
 242 request any protocol or \s-1NPN\s0 is not enabled, then \fBdata\fR is set to \s-1NULL\s0 and
 243 \&\fBlen\fR to 0. Note that
 244 the client can request any protocol it chooses. The value returned from
 245 this function need not be a member of the list of supported protocols
 246 provided by the callback.
 247 .SH "NOTES"
 248 .IX Header "NOTES"
 249 The protocol-lists must be in wire-format, which is defined as a vector of
 250 non-empty, 8\-bit length-prefixed, byte strings. The length-prefix byte is not
 251 included in the length. Each string is limited to 255 bytes. A byte-string
 252 length of 0 is invalid. A truncated byte-string is invalid. The length of the
 253 vector is not in the vector itself, but in a separate variable.
 254 .PP
 255 Example:
 256 .PP
 257 .Vb 5
 258 \& unsigned char vector[] = {
 259 \&     6, \*(Aqs\*(Aq, \*(Aqp\*(Aq, \*(Aqd\*(Aq, \*(Aqy\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq,
 260 \&     8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq1\*(Aq
 261 \& };
 262 \& unsigned int length = sizeof(vector);
 263 .Ve
 264 .PP
 265 The \s-1ALPN\s0 callback is executed after the servername callback; as that servername
 266 callback may update the \s-1SSL_CTX,\s0 and subsequently, the \s-1ALPN\s0 callback.
 267 .PP
 268 If there is no \s-1ALPN\s0 proposed in the ClientHello, the \s-1ALPN\s0 callback is not
 269 invoked.
 270 .SH "RETURN VALUES"
 271 .IX Header "RETURN VALUES"
 272 \&\fBSSL_CTX_set_alpn_protos()\fR and \fBSSL_set_alpn_protos()\fR return 0 on success, and
 273 non\-0 on failure. \s-1WARNING:\s0 these functions reverse the return value convention.
 274 .PP
 275 \&\fBSSL_select_next_proto()\fR returns one of the following:
 276 .IP "\s-1OPENSSL_NPN_NEGOTIATED\s0" 4
 277 .IX Item "OPENSSL_NPN_NEGOTIATED"
 278 A match was found and is returned in \fBout\fR, \fBoutlen\fR.
 279 .IP "\s-1OPENSSL_NPN_NO_OVERLAP\s0" 4
 280 .IX Item "OPENSSL_NPN_NO_OVERLAP"
 281 No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in
 282 \&\fBout\fR, \fBoutlen\fR.
 283 .PP
 284 The \s-1ALPN\s0 select callback \fBcb\fR, must return one of the following:
 285 .IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4
 286 .IX Item "SSL_TLSEXT_ERR_OK"
 287 \&\s-1ALPN\s0 protocol selected.
 288 .IP "\s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0" 4
 289 .IX Item "SSL_TLSEXT_ERR_ALERT_FATAL"
 290 There was no overlap between the client's supplied list and the server
 291 configuration.
 292 .IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4
 293 .IX Item "SSL_TLSEXT_ERR_NOACK"
 294 \&\s-1ALPN\s0 protocol not selected, e.g., because no \s-1ALPN\s0 protocols are configured for
 295 this connection.
 296 .PP
 297 The callback set using \fBSSL_CTX_set_next_proto_select_cb()\fR should return
 298 \&\fB\s-1SSL_TLSEXT_ERR_OK\s0\fR if successful. Any other value is fatal to the connection.
 299 .PP
 300 The callback set using \fBSSL_CTX_set_next_protos_advertised_cb()\fR should return
 301 \&\fB\s-1SSL_TLSEXT_ERR_OK\s0\fR if it wishes to advertise. Otherwise, no such extension
 302 will be included in the ServerHello.
 303 .SH "SEE ALSO"
 304 .IX Header "SEE ALSO"
 305 \&\fBssl\fR\|(7), \fBSSL_CTX_set_tlsext_servername_callback\fR\|(3),
 306 \&\fBSSL_CTX_set_tlsext_servername_arg\fR\|(3)
 307 .SH "COPYRIGHT"
 308 .IX Header "COPYRIGHT"
 309 Copyright 2016\-2017 The OpenSSL Project Authors. All Rights Reserved.
 310 .PP
 311 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 312 this file except in compliance with the License.  You can obtain a copy
 313 in the file \s-1LICENSE\s0 in the source distribution or at
 314 <https://www.openssl.org/source/license.html>.