secure/lib/libcrypto/man/man3/SSL_CTX_set_tlsext_servername_callback.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
   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_TLSEXT_SERVERNAME_CALLBACK 3"
 136 .TH SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3 "2022-05-03" "1.1.1o" "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_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg, SSL_get_servername_type, SSL_get_servername, SSL_set_tlsext_host_name \- handle server name indication (SNI)
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
 149 \&                                   int (*cb)(SSL *s, int *al, void *arg));
 150 \& long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
 151 \&
 152 \& const char *SSL_get_servername(const SSL *s, const int type);
 153 \& int SSL_get_servername_type(const SSL *s);
 154 \&
 155 \& int SSL_set_tlsext_host_name(const SSL *s, const char *name);
 156 .Ve
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 The functionality provided by the servername callback is mostly superseded by
 160 the ClientHello callback, which can be set using \fBSSL_CTX_set_client_hello_cb()\fR.
 161 However, even where the ClientHello callback is used, the servername callback is
 162 still necessary in order to acknowledge the servername requested by the client.
 163 .PP
 164 \&\fBSSL_CTX_set_tlsext_servername_callback()\fR sets the application callback \fBcb\fR
 165 used by a server to perform any actions or configuration required based on
 166 the servername extension received in the incoming connection. When \fBcb\fR
 167 is \s-1NULL, SNI\s0 is not used.
 168 .PP
 169 The servername callback should return one of the following values:
 170 .IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4
 171 .IX Item "SSL_TLSEXT_ERR_OK"
 172 This is used to indicate that the servername requested by the client has been
 173 accepted. Typically a server will call \fBSSL_set_SSL_CTX()\fR in the callback to set
 174 up a different configuration for the selected servername in this case.
 175 .IP "\s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0" 4
 176 .IX Item "SSL_TLSEXT_ERR_ALERT_FATAL"
 177 In this case the servername requested by the client is not accepted and the
 178 handshake will be aborted. The value of the alert to be used should be stored in
 179 the location pointed to by the \fBal\fR parameter to the callback. By default this
 180 value is initialised to \s-1SSL_AD_UNRECOGNIZED_NAME.\s0
 181 .IP "\s-1SSL_TLSEXT_ERR_ALERT_WARNING\s0" 4
 182 .IX Item "SSL_TLSEXT_ERR_ALERT_WARNING"
 183 If this value is returned then the servername is not accepted by the server.
 184 However, the handshake will continue and send a warning alert instead. The value
 185 of the alert should be stored in the location pointed to by the \fBal\fR parameter
 186 as for \s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0 above. Note that TLSv1.3 does not support
 187 warning alerts, so if TLSv1.3 has been negotiated then this return value is
 188 treated the same way as \s-1SSL_TLSEXT_ERR_NOACK.\s0
 189 .IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4
 190 .IX Item "SSL_TLSEXT_ERR_NOACK"
 191 This return value indicates that the servername is not accepted by the server.
 192 No alerts are sent and the server will not acknowledge the requested servername.
 193 .PP
 194 \&\fBSSL_CTX_set_tlsext_servername_arg()\fR sets a context-specific argument to be
 195 passed into the callback (via the \fBarg\fR parameter) for this \fB\s-1SSL_CTX\s0\fR.
 196 .PP
 197 The behaviour of \fBSSL_get_servername()\fR depends on a number of different factors.
 198 In particular note that in TLSv1.3 the servername is negotiated in every
 199 handshake. In TLSv1.2 the servername is only negotiated on initial handshakes
 200 and not on resumption handshakes.
 201 .IP "On the client, before the handshake" 4
 202 .IX Item "On the client, before the handshake"
 203 If a servername has been set via a call to \fBSSL_set_tlsext_host_name()\fR then it
 204 will return that servername.
 205 .Sp
 206 If one has not been set, but a TLSv1.2 resumption is being attempted and the
 207 session from the original handshake had a servername accepted by the server then
 208 it will return that servername.
 209 .Sp
 210 Otherwise it returns \s-1NULL.\s0
 211 .IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" 4
 212 .IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred"
 213 If the session from the original handshake had a servername accepted by the
 214 server then it will return that servername.
 215 .Sp
 216 Otherwise it returns the servername set via \fBSSL_set_tlsext_host_name()\fR or \s-1NULL\s0
 217 if it was not called.
 218 .IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" 4
 219 .IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur"
 220 It will return the servername set via \fBSSL_set_tlsext_host_name()\fR or \s-1NULL\s0 if it
 221 was not called.
 222 .IP "On the server, before the handshake" 4
 223 .IX Item "On the server, before the handshake"
 224 The function will always return \s-1NULL\s0 before the handshake
 225 .IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" 4
 226 .IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred"
 227 If a servername was accepted by the server in the original handshake then it
 228 will return that servername, or \s-1NULL\s0 otherwise.
 229 .IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" 4
 230 .IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur"
 231 The function will return the servername requested by the client in this
 232 handshake or \s-1NULL\s0 if none was requested.
 233 .PP
 234 Note that the ClientHello callback occurs before a servername extension from the
 235 client is processed. The servername, certificate and \s-1ALPN\s0 callbacks occur after
 236 a servername extension from the client is processed.
 237 .PP
 238 \&\fBSSL_get_servername_type()\fR returns the servername type or \-1 if no servername
 239 is present. Currently the only supported type (defined in \s-1RFC3546\s0) is
 240 \&\fBTLSEXT_NAMETYPE_host_name\fR.
 241 .PP
 242 \&\fBSSL_set_tlsext_host_name()\fR sets the server name indication ClientHello extension
 243 to contain the value \fBname\fR. The type of server name indication extension is set
 244 to \fBTLSEXT_NAMETYPE_host_name\fR (defined in \s-1RFC3546\s0).
 245 .SH "NOTES"
 246 .IX Header "NOTES"
 247 Several callbacks are executed during ClientHello processing, including
 248 the ClientHello, \s-1ALPN,\s0 and servername callbacks.  The ClientHello callback is
 249 executed first, then the servername callback, followed by the \s-1ALPN\s0 callback.
 250 .PP
 251 The \fBSSL_set_tlsext_host_name()\fR function should only be called on \s-1SSL\s0 objects
 252 that will act as clients; otherwise the configured \fBname\fR will be ignored.
 253 .SH "RETURN VALUES"
 254 .IX Header "RETURN VALUES"
 255 \&\fBSSL_CTX_set_tlsext_servername_callback()\fR and
 256 \&\fBSSL_CTX_set_tlsext_servername_arg()\fR both always return 1 indicating success.
 257 \&\fBSSL_set_tlsext_host_name()\fR returns 1 on success, 0 in case of error.
 258 .SH "SEE ALSO"
 259 .IX Header "SEE ALSO"
 260 \&\fBssl\fR\|(7), \fBSSL_CTX_set_alpn_select_cb\fR\|(3),
 261 \&\fBSSL_get0_alpn_selected\fR\|(3), \fBSSL_CTX_set_client_hello_cb\fR\|(3)
 262 .SH "HISTORY"
 263 .IX Header "HISTORY"
 264 \&\fBSSL_get_servername()\fR historically provided some unexpected results in certain
 265 corner cases. This has been fixed from OpenSSL 1.1.1e.
 266 .PP
 267 Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2
 268 handshake, the server accepted it, and then the client successfully resumed but
 269 set a different explicit servername in the second handshake then when called by
 270 the client it returned the servername from the second handshake. This has now
 271 been changed to return the servername requested in the original handshake.
 272 .PP
 273 Also prior to 1.1.1e, if the client sent a servername in the first handshake but
 274 the server did not accept it, and then a second handshake occurred where TLSv1.2
 275 resumption was successful then when called by the server it returned the
 276 servername requested in the original handshake. This has now been changed to
 277 \&\s-1NULL.\s0
 278 .SH "COPYRIGHT"
 279 .IX Header "COPYRIGHT"
 280 Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
 281 .PP
 282 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 283 this file except in compliance with the License.  You can obtain a copy
 284 in the file \s-1LICENSE\s0 in the source distribution or at
 285 <https://www.openssl.org/source/license.html>.