secure/lib/libssl/man/SSL_CTX_set_alpn_select_cb.3

   1 .\" Automatically generated by Pod::Man 4.09 (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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  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
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  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'
 101 .\}
 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 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_CTX_set_alpn_select_cb 3"
 132 .TH SSL_CTX_set_alpn_select_cb 3 "2018-11-20" "1.0.2q" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 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)
 141 .SH "SYNOPSIS"
 142 .IX Header "SYNOPSIS"
 143 .Vb 1
 144 \& #include <openssl/ssl.h>
 145 \&
 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);
 164 .Ve
 165 .SH "DESCRIPTION"
 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
 170 \&\fBprotos_len\fR.
 171 .PP
 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.
 176 .PP
 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.
 182 .PP
 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.
 193 .PP
 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.
 197 .SH "NOTES"
 198 .IX Header "NOTES"
 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.
 204 .PP
 205 Example:
 206 .PP
 207 .Vb 5
 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
 211 \& };
 212 \& unsigned int length = sizeof(vector);
 213 .Ve
 214 .PP
 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.
 217 .PP
 218 If there is no \s-1ALPN\s0 proposed in the ClientHello, the \s-1ALPN\s0 callback is not
 219 invoked.
 220 .SH "RETURN VALUES"
 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.
 224 .PP
 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.
 233 .PP
 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.
 241 .SH "SEE ALSO"
 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)