279 lines
12 KiB
Groff
Executable File
279 lines
12 KiB
Groff
Executable File
.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
|
|
.\"
|
|
.\" Standard preamble:
|
|
.\" ========================================================================
|
|
.de Sp \" Vertical space (when we can't use .PP)
|
|
.if t .sp .5v
|
|
.if n .sp
|
|
..
|
|
.de Vb \" Begin verbatim text
|
|
.ft CW
|
|
.nf
|
|
.ne \\$1
|
|
..
|
|
.de Ve \" End verbatim text
|
|
.ft R
|
|
.fi
|
|
..
|
|
.\" Set up some character translations and predefined strings. \*(-- will
|
|
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
|
|
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
|
|
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
|
|
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
|
|
.\" nothing in troff, for use with C<>.
|
|
.tr \(*W-
|
|
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
|
|
.ie n \{\
|
|
. ds -- \(*W-
|
|
. ds PI pi
|
|
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
|
|
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
|
|
. ds L" ""
|
|
. ds R" ""
|
|
. ds C` ""
|
|
. ds C' ""
|
|
'br\}
|
|
.el\{\
|
|
. ds -- \|\(em\|
|
|
. ds PI \(*p
|
|
. ds L" ``
|
|
. ds R" ''
|
|
'br\}
|
|
.\"
|
|
.\" Escape single quotes in literal strings from groff's Unicode transform.
|
|
.ie \n(.g .ds Aq \(aq
|
|
.el .ds Aq '
|
|
.\"
|
|
.\" If the F register is turned on, we'll generate index entries on stderr for
|
|
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
|
|
.\" entries marked with X<> in POD. Of course, you'll have to process the
|
|
.\" output yourself in some meaningful fashion.
|
|
.ie \nF \{\
|
|
. de IX
|
|
. tm Index:\\$1\t\\n%\t"\\$2"
|
|
..
|
|
. nr % 0
|
|
. rr F
|
|
.\}
|
|
.el \{\
|
|
. de IX
|
|
..
|
|
.\}
|
|
.\"
|
|
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
|
|
.\" Fear. Run. Save yourself. No user-serviceable parts.
|
|
. \" fudge factors for nroff and troff
|
|
.if n \{\
|
|
. ds #H 0
|
|
. ds #V .8m
|
|
. ds #F .3m
|
|
. ds #[ \f1
|
|
. ds #] \fP
|
|
.\}
|
|
.if t \{\
|
|
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
|
|
. ds #V .6m
|
|
. ds #F 0
|
|
. ds #[ \&
|
|
. ds #] \&
|
|
.\}
|
|
. \" simple accents for nroff and troff
|
|
.if n \{\
|
|
. ds ' \&
|
|
. ds ` \&
|
|
. ds ^ \&
|
|
. ds , \&
|
|
. ds ~ ~
|
|
. ds /
|
|
.\}
|
|
.if t \{\
|
|
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
|
|
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
|
|
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
|
|
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
|
|
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
|
|
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
|
|
.\}
|
|
. \" troff and (daisy-wheel) nroff accents
|
|
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
|
|
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
|
|
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
|
|
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
|
|
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
|
|
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
|
|
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
|
|
.ds ae a\h'-(\w'a'u*4/10)'e
|
|
.ds Ae A\h'-(\w'A'u*4/10)'E
|
|
. \" corrections for vroff
|
|
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
|
|
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
|
|
. \" for low resolution devices (crt and lpr)
|
|
.if \n(.H>23 .if \n(.V>19 \
|
|
\{\
|
|
. ds : e
|
|
. ds 8 ss
|
|
. ds o a
|
|
. ds d- d\h'-1'\(ga
|
|
. ds D- D\h'-1'\(hy
|
|
. ds th \o'bp'
|
|
. ds Th \o'LP'
|
|
. ds ae ae
|
|
. ds Ae AE
|
|
.\}
|
|
.rm #[ #] #H #V #F C
|
|
.\" ========================================================================
|
|
.\"
|
|
.IX Title "SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3"
|
|
.TH SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3 "2020-03-02" "3.0.0-dev" "OpenSSL"
|
|
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
|
|
.\" way too many mistakes in technical documents.
|
|
.if n .ad l
|
|
.nh
|
|
.SH "NAME"
|
|
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)
|
|
.SH "SYNOPSIS"
|
|
.IX Header "SYNOPSIS"
|
|
.Vb 1
|
|
\& #include <openssl/ssl.h>
|
|
\&
|
|
\& long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
|
|
\& int (*cb)(SSL *s, int *al, void *arg));
|
|
\& long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
|
|
\&
|
|
\& const char *SSL_get_servername(const SSL *s, const int type);
|
|
\& int SSL_get_servername_type(const SSL *s);
|
|
\&
|
|
\& int SSL_set_tlsext_host_name(const SSL *s, const char *name);
|
|
.Ve
|
|
.SH "DESCRIPTION"
|
|
.IX Header "DESCRIPTION"
|
|
The functionality provided by the servername callback is mostly superseded by
|
|
the ClientHello callback, which can be set using \fISSL_CTX_set_client_hello_cb()\fR.
|
|
However, even where the ClientHello callback is used, the servername callback is
|
|
still necessary in order to acknowledge the servername requested by the client.
|
|
.PP
|
|
\&\fISSL_CTX_set_tlsext_servername_callback()\fR sets the application callback \fBcb\fR
|
|
used by a server to perform any actions or configuration required based on
|
|
the servername extension received in the incoming connection. When \fBcb\fR
|
|
is \s-1NULL\s0, \s-1SNI\s0 is not used.
|
|
.PP
|
|
The servername callback should return one of the following values:
|
|
.IP "\s-1SSL_TLSEXT_ERR_OK\s0" 4
|
|
.IX Item "SSL_TLSEXT_ERR_OK"
|
|
This is used to indicate that the servername requested by the client has been
|
|
accepted. Typically a server will call \fISSL_set_SSL_CTX()\fR in the callback to set
|
|
up a different configuration for the selected servername in this case.
|
|
.IP "\s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0" 4
|
|
.IX Item "SSL_TLSEXT_ERR_ALERT_FATAL"
|
|
In this case the servername requested by the client is not accepted and the
|
|
handshake will be aborted. The value of the alert to be used should be stored in
|
|
the location pointed to by the \fBal\fR parameter to the callback. By default this
|
|
value is initialised to \s-1SSL_AD_UNRECOGNIZED_NAME\s0.
|
|
.IP "\s-1SSL_TLSEXT_ERR_ALERT_WARNING\s0" 4
|
|
.IX Item "SSL_TLSEXT_ERR_ALERT_WARNING"
|
|
If this value is returned then the servername is not accepted by the server.
|
|
However the handshake will continue and send a warning alert instead. The value
|
|
of the alert should be stored in the location pointed to by the \fBal\fR parameter
|
|
as for \s-1SSL_TLSEXT_ERR_ALERT_FATAL\s0 above. Note that TLSv1.3 does not support
|
|
warning alerts, so if TLSv1.3 has been negotiated then this return value is
|
|
treated the same way as \s-1SSL_TLSEXT_ERR_NOACK\s0.
|
|
.IP "\s-1SSL_TLSEXT_ERR_NOACK\s0" 4
|
|
.IX Item "SSL_TLSEXT_ERR_NOACK"
|
|
This return value indicates that the servername is not accepted by the server.
|
|
No alerts are sent and the server will not acknowledge the requested servername.
|
|
.PP
|
|
\&\fISSL_CTX_set_tlsext_servername_arg()\fR sets a context-specific argument to be
|
|
passed into the callback (via the \fBarg\fR parameter) for this \fB\s-1SSL_CTX\s0\fR.
|
|
.PP
|
|
The behaviour of \fISSL_get_servername()\fR depends on a number of different factors.
|
|
In particular note that in TLSv1.3 the servername is negotiated in every
|
|
handshake. In TLSv1.2 the servername is only negotiated on initial handshakes
|
|
and not on resumption handshakes.
|
|
.IP "On the client, before the handshake" 4
|
|
.IX Item "On the client, before the handshake"
|
|
If a servername has been set via a call to \fISSL_set_tlsext_host_name()\fR then it
|
|
will return that servername.
|
|
.Sp
|
|
If one has not been set, but a TLSv1.2 resumption is being attempted and the
|
|
session from the original handshake had a servername accepted by the server then
|
|
it will return that servername.
|
|
.Sp
|
|
Otherwise it returns \s-1NULL\s0.
|
|
.IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" 4
|
|
.IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred"
|
|
If the session from the orignal handshake had a servername accepted by the
|
|
server then it will return that servername.
|
|
.Sp
|
|
Otherwise it returns the servername set via \fISSL_set_tlsext_host_name()\fR or \s-1NULL\s0
|
|
if it was not called.
|
|
.IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" 4
|
|
.IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur"
|
|
It will return the servername set via \fISSL_set_tlsext_host_name()\fR or \s-1NULL\s0 if it
|
|
was not called.
|
|
.IP "On the server, before the handshake" 4
|
|
.IX Item "On the server, before the handshake"
|
|
The function will always return \s-1NULL\s0 before the handshake
|
|
.IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" 4
|
|
.IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred"
|
|
If a servername was accepted by the server in the original handshake then it
|
|
will return that servername, or \s-1NULL\s0 otherwise.
|
|
.IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" 4
|
|
.IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur"
|
|
The function will return the servername requested by the client in this
|
|
handshake or \s-1NULL\s0 if none was requested.
|
|
.PP
|
|
Note that the ClientHello callback occurs before a servername extension from the
|
|
client is processed. The servername, certificate and \s-1ALPN\s0 callbacks occur after
|
|
a servername extension from the client is processed.
|
|
.PP
|
|
\&\fISSL_get_servername_type()\fR returns the servername type or \-1 if no servername
|
|
is present. Currently the only supported type (defined in \s-1RFC3546\s0) is
|
|
\&\fBTLSEXT_NAMETYPE_host_name\fR.
|
|
.PP
|
|
\&\fISSL_set_tlsext_host_name()\fR sets the server name indication ClientHello extension
|
|
to contain the value \fBname\fR. The type of server name indication extension is set
|
|
to \fBTLSEXT_NAMETYPE_host_name\fR (defined in \s-1RFC3546\s0).
|
|
.SH "NOTES"
|
|
.IX Header "NOTES"
|
|
Several callbacks are executed during ClientHello processing, including
|
|
the ClientHello, \s-1ALPN\s0, and servername callbacks. The ClientHello callback is
|
|
executed first, then the servername callback, followed by the \s-1ALPN\s0 callback.
|
|
.PP
|
|
The \fISSL_set_tlsext_host_name()\fR function should only be called on \s-1SSL\s0 objects
|
|
that will act as clients; otherwise the configured \fBname\fR will be ignored.
|
|
.SH "RETURN VALUES"
|
|
.IX Header "RETURN VALUES"
|
|
\&\fISSL_CTX_set_tlsext_servername_callback()\fR and
|
|
\&\fISSL_CTX_set_tlsext_servername_arg()\fR both always return 1 indicating success.
|
|
\&\fISSL_set_tlsext_host_name()\fR returns 1 on success, 0 in case of error.
|
|
.SH "SEE ALSO"
|
|
.IX Header "SEE ALSO"
|
|
\&\fIssl\fR\|(7), \fISSL_CTX_set_alpn_select_cb\fR\|(3),
|
|
\&\fISSL_get0_alpn_selected\fR\|(3), \fISSL_CTX_set_client_hello_cb\fR\|(3)
|
|
.SH "HISTORY"
|
|
.IX Header "HISTORY"
|
|
\&\fISSL_get_servername()\fR historically provided some unexpected results in certain
|
|
corner cases. This has been fixed from OpenSSL 1.1.1e.
|
|
.PP
|
|
Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2
|
|
handshake, the server accepted it, and then the client successfully resumed but
|
|
set a different explict servername in the second handshake then when called by
|
|
the client it returned the servername from the second handshake. This has now
|
|
been changed to return the servername requested in the original handshake.
|
|
.PP
|
|
Also prior to 1.1.1e, if the client sent a servername in the first handshake but
|
|
the server did not accept it, and then a second handshake occured where TLSv1.2
|
|
resumption was successful then when called by the server it returned the
|
|
servername requested in the original handshake. This has now been changed to
|
|
\&\s-1NULL\s0.
|
|
.SH "COPYRIGHT"
|
|
.IX Header "COPYRIGHT"
|
|
Copyright 2017 The OpenSSL Project Authors. All Rights Reserved.
|
|
.PP
|
|
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file \s-1LICENSE\s0 in the source distribution or at
|
|
<https://www.openssl.org/source/license.html>.
|