| =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 *, int *, void *)); |
| 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 superseded by the |
| ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb(). |
| The servername callback is retained for historical compatibility. |
| |
| 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 B<arg> value is a pointer which is passed to |
| the application callback. |
| |
| SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be |
| passed into the callback for this B<SSL_CTX>. |
| |
| SSL_get_servername() returns a servername extension value of the specified |
| type if provided in the Client Hello or NULL. |
| |
| 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 COPYRIGHT |
| |
| Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. |
| |
| Licensed under the OpenSSL license (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 |