mirror of
https://github.com/openssl/openssl.git
synced 2024-12-09 05:51:54 +08:00
8c1cbc7210
CLA: trivial Reviewed-by: Shane Lontis <shane.lontis@oracle.com> Reviewed-by: Matthias St. Pierre <Matthias.St.Pierre@ncp-e.com> (Merged from https://github.com/openssl/openssl/pull/12320)
180 lines
6.8 KiB
Plaintext
180 lines
6.8 KiB
Plaintext
=pod
|
|
|
|
=head1 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)
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#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);
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
The functionality provided by the servername callback is mostly superseded by
|
|
the ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb().
|
|
However, even where the ClientHello callback is used, the servername callback is
|
|
still necessary in order to acknowledge the servername requested by the client.
|
|
|
|
SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb>
|
|
used by a server to perform any actions or configuration required based on
|
|
the servername extension received in the incoming connection. When B<cb>
|
|
is NULL, SNI is not used.
|
|
|
|
The servername callback should return one of the following values:
|
|
|
|
=over 4
|
|
|
|
=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 SSL_set_SSL_CTX() in the callback to set
|
|
up a different configuration for the selected servername in this case.
|
|
|
|
=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 B<al> parameter to the callback. By default this
|
|
value is initialised to SSL_AD_UNRECOGNIZED_NAME.
|
|
|
|
=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 B<al> parameter
|
|
as for SSL_TLSEXT_ERR_ALERT_FATAL 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 SSL_TLSEXT_ERR_NOACK.
|
|
|
|
=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.
|
|
|
|
=back
|
|
|
|
SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be
|
|
passed into the callback (via the B<arg> parameter) for this B<SSL_CTX>.
|
|
|
|
The behaviour of SSL_get_servername() 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.
|
|
|
|
=over 4
|
|
|
|
=item On the client, before the handshake
|
|
|
|
If a servername has been set via a call to SSL_set_tlsext_host_name() then it
|
|
will return that servername.
|
|
|
|
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.
|
|
|
|
Otherwise it returns NULL.
|
|
|
|
=item On the client, during or after the handshake and a TLSv1.2 (or below)
|
|
resumption occurred
|
|
|
|
If the session from the original handshake had a servername accepted by the
|
|
server then it will return that servername.
|
|
|
|
Otherwise it returns the servername set via SSL_set_tlsext_host_name() or NULL
|
|
if it was not called.
|
|
|
|
=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 SSL_set_tlsext_host_name() or NULL if it
|
|
was not called.
|
|
|
|
=item On the server, before the handshake
|
|
|
|
The function will always return NULL before the handshake
|
|
|
|
=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 NULL otherwise.
|
|
|
|
=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 NULL if none was requested.
|
|
|
|
=back
|
|
|
|
Note that the ClientHello callback occurs before a servername extension from the
|
|
client is processed. The servername, certificate and ALPN callbacks occur after
|
|
a servername extension from the client is processed.
|
|
|
|
SSL_get_servername_type() returns the servername type or -1 if no servername
|
|
is present. Currently the only supported type (defined in RFC3546) is
|
|
B<TLSEXT_NAMETYPE_host_name>.
|
|
|
|
SSL_set_tlsext_host_name() sets the server name indication ClientHello extension
|
|
to contain the value B<name>. The type of server name indication extension is set
|
|
to B<TLSEXT_NAMETYPE_host_name> (defined in RFC3546).
|
|
|
|
=head1 NOTES
|
|
|
|
Several callbacks are executed during ClientHello processing, including
|
|
the ClientHello, ALPN, and servername callbacks. The ClientHello callback is
|
|
executed first, then the servername callback, followed by the ALPN callback.
|
|
|
|
The SSL_set_tlsext_host_name() function should only be called on SSL objects
|
|
that will act as clients; otherwise the configured B<name> will be ignored.
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
SSL_CTX_set_tlsext_servername_callback() and
|
|
SSL_CTX_set_tlsext_servername_arg() both always return 1 indicating success.
|
|
SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>,
|
|
L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)>
|
|
|
|
=head1 HISTORY
|
|
|
|
SSL_get_servername() historically provided some unexpected results in certain
|
|
corner cases. This has been fixed from OpenSSL 1.1.1e.
|
|
|
|
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 explicit 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.
|
|
|
|
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 occurred 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
|
|
NULL.
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|
|
|
Licensed under the Apache License 2.0 (the "License"). You may not use
|
|
this file except in compliance with the License. You can obtain a copy
|
|
in the file LICENSE in the source distribution or at
|
|
L<https://www.openssl.org/source/license.html>.
|
|
|
|
=cut
|