lib/libssl/man/SSL_CTX_set_alpn_select_cb.3

   1 .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
   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 turned on, 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 "2016-05-03" "1.0.2h" "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,
 143 SSL_select_next_proto, SSL_get0_alpn_selected \- handle application layer
 144 protocol negotiation (ALPN)
 145 .SH "SYNOPSIS"
 146 .IX Header "SYNOPSIS"
 147 .Vb 1
 148 \& #include <openssl/ssl.h>
 149 \&
 150 \& int SSL_CTX_set_alpn_protos(SSL_CTX *ctx, const unsigned char *protos,
 151 \&                             unsigned protos_len);
 152 \& int SSL_set_alpn_protos(SSL *ssl, const unsigned char *protos,
 153 \&                         unsigned protos_len);
 154 \& void SSL_CTX_set_alpn_select_cb(SSL_CTX *ctx,
 155 \&                                 int (*cb) (SSL *ssl,
 156 \&                                            const unsigned char **out,
 157 \&                                            unsigned char *outlen,
 158 \&                                            const unsigned char *in,
 159 \&                                            unsigned int inlen,
 160 \&                                            void *arg), void *arg);
 161 \& int SSL_select_next_proto(unsigned char **out, unsigned char *outlen,
 162 \&                           const unsigned char *server,
 163 \&                           unsigned int server_len,
 164 \&                           const unsigned char *client,
 165 \&                           unsigned int client_len)
 166 \& void SSL_get0_alpn_selected(const SSL *ssl, const unsigned char **data,
 167 \&                             unsigned int *len);
 168 .Ve
 169 .SH "DESCRIPTION"
 170 .IX Header "DESCRIPTION"
 171 \&\fISSL_CTX_set_alpn_protos()\fR and \fISSL_set_alpn_protos()\fR are used by the client to
 172 set the list of protocols available to be negotiated. The \fBprotos\fR must be in
 173 protocol-list format, described below. The length of \fBprotos\fR is specified in
 174 \&\fBprotos_len\fR.
 175 .PP
 176 \&\fISSL_CTX_set_alpn_select_cb()\fR sets the application callback \fBcb\fR used by a
 177 server to select which protocol to use for the incoming connection. When \fBcb\fR
 178 is \s-1NULL, ALPN\s0 is not used. The \fBarg\fR value is a pointer which is passed to
 179 the application callback.
 180 .PP
 181 \&\fBcb\fR is the application defined callback. The \fBin\fR, \fBinlen\fR parameters are a
 182 vector in protocol-list format. The value of the \fBout\fR, \fBoutlen\fR vector
 183 should be set to the value of a single protocol selected from the \fBin\fR,
 184 \&\fBinlen\fR vector. The \fBarg\fR parameter is the pointer set via
 185 \&\fISSL_CTX_set_alpn_select_cb()\fR.
 186 .PP
 187 \&\fISSL_select_next_proto()\fR is a helper function used to select protocols. It
 188 implements the standard protocol selection. It is expected that this function
 189 is called from the application callback \fBcb\fR. The protocol data in \fBserver\fR,
 190 \&\fBserver_len\fR and \fBclient\fR, \fBclient_len\fR must be in the protocol-list format
 191 described below. The first item in the \fBserver\fR, \fBserver_len\fR list that
 192 matches an item in the \fBclient\fR, \fBclient_len\fR list is selected, and returned
 193 in \fBout\fR, \fBoutlen\fR. The \fBout\fR value will point into either \fBserver\fR or
 194 \&\fBclient\fR, so it should be copied immediately. If no match is found, the first
 195 item in \fBclient\fR, \fBclient_len\fR is returned in \fBout\fR, \fBoutlen\fR. This
 196 function can also be used in the \s-1NPN\s0 callback.
 197 .PP
 198 \&\fISSL_get0_alpn_selected()\fR returns a pointer to the selected protocol in \fBdata\fR
 199 with length \fBlen\fR. It is not NUL-terminated. \fBdata\fR is set to \s-1NULL\s0 and \fBlen\fR
 200 is set to 0 if no protocol has been selected. \fBdata\fR must not be freed.
 201 .SH "NOTES"
 202 .IX Header "NOTES"
 203 The protocol-lists must be in wire-format, which is defined as a vector of
 204 non-empty, 8\-bit length-prefixed, byte strings. The length-prefix byte is not
 205 included in the length. Each string is limited to 255 bytes. A byte-string
 206 length of 0 is invalid. A truncated byte-string is invalid. The length of the
 207 vector is not in the vector itself, but in a separate variable.
 208 .PP
 209 Example:
 210 .PP
 211 .Vb 5
 212 \& unsigned char vector[] = {
 213 \&     6, \*(Aqs\*(Aq, \*(Aqp\*(Aq, \*(Aqd\*(Aq, \*(Aqy\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq,
 214 \&     8, \*(Aqh\*(Aq, \*(Aqt\*(Aq, \*(Aqt\*(Aq, \*(Aqp\*(Aq, \*(Aq/\*(Aq, \*(Aq1\*(Aq, \*(Aq.\*(Aq, \*(Aq1\*(Aq
 215 \& };
 216 \& unsigned int length = sizeof(vector);
 217 .Ve
 218 .PP
 219 The \s-1ALPN\s0 callback is executed after the servername callback; as that servername
 220 callback may update the \s-1SSL_CTX,\s0 and subsequently, the \s-1ALPN\s0 callback.
 221 .PP
 222 If there is no \s-1ALPN\s0 proposed in the ClientHello, the \s-1ALPN\s0 callback is not
 223 invoked.
 224 .SH "RETURN VALUES"
 225 .IX Header "RETURN VALUES"
 226 \&\fISSL_CTX_set_alpn_protos()\fR and \fISSL_set_alpn_protos()\fR return 0 on success, and
 227 non\-0 on failure. \s-1WARNING:\s0 these functions reverse the return value convention.
 228 .PP
 229 \&\fISSL_select_next_proto()\fR returns one of the following:
 230 .IP "\s-1OPENSSL_NPN_NEGOTIATED\s0" 4
 231 .IX Item "OPENSSL_NPN_NEGOTIATED"
 232 A match was found and is returned in \fBout\fR, \fBoutlen\fR.
 233 .IP "\s-1OPENSSL_NPN_NO_OVERLAP\s0" 4
 234 .IX Item "OPENSSL_NPN_NO_OVERLAP"
 235 No match was found. The first item in \fBclient\fR, \fBclient_len\fR is returned in
 236 \&\fBout\fR, \fBoutlen\fR.
 237 .PP
 238 The \s-1ALPN\s0 select callback \fBcb\fR, must return one of the following:
 239 .IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4
 240 .IX Item "SSL_TLSEXT_ERR_OK"
 241 \&\s-1ALPN\s0 protocol selected.
 242 .IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4
 243 .IX Item "SSL_TLSEXT_ERR_NOACK"
 244 \&\s-1ALPN\s0 protocol not selected.
 245 .SH "SEE ALSO"
 246 .IX Header "SEE ALSO"
 247 \&\fIssl\fR\|(3), \fISSL_CTX_set_tlsext_servername_callback\fR\|(3),
 248 \&\fISSL_CTX_set_tlsext_servername_arg\fR\|(3)