1.\" $OpenBSD: SSL_CTX_set_tlsext_servername_callback.3,v 1.4 2019/06/12 09:36:30 schwarze Exp $ 2.\" OpenSSL 190b9a03 Jun 28 15:46:13 2017 +0800 3.\" OpenSSL 8c55c461 Mar 29 08:34:37 2017 +1000 4.\" 5.\" This file was written by Jon Spillett <jon.spillett@oracle.com> 6.\" and Paul Yang <yang dot yang at baishancloud dot com>. 7.\" Copyright (c) 2000 The OpenSSL Project. All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: June 12 2019 $ 54.Dt SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3 55.Os 56.Sh NAME 57.Nm SSL_CTX_set_tlsext_servername_callback , 58.Nm SSL_CTX_set_tlsext_servername_arg , 59.Nm SSL_get_servername_type , 60.Nm SSL_get_servername , 61.Nm SSL_set_tlsext_host_name 62.Nd handle server name indication (SNI) 63.Sh SYNOPSIS 64.In openssl/ssl.h 65.Ft long 66.Fo SSL_CTX_set_tlsext_servername_callback 67.Fa "SSL_CTX *ctx" 68.Fa "int (*cb)(SSL_CTX *, int *, void *)" 69.Fc 70.Ft long 71.Fo SSL_CTX_set_tlsext_servername_arg 72.Fa "SSL_CTX *ctx" 73.Fa "void *arg" 74.Fc 75.Ft const char * 76.Fo SSL_get_servername 77.Fa "const SSL *s" 78.Fa "const int type" 79.Fc 80.Ft int 81.Fo SSL_get_servername_type 82.Fa "const SSL *s" 83.Fc 84.Ft int 85.Fo SSL_set_tlsext_host_name 86.Fa "const SSL *s" 87.Fa "const char *name" 88.Fc 89.Sh DESCRIPTION 90.Fn SSL_CTX_set_tlsext_servername_callback 91sets the application callback 92.Fa cb 93used by a server to perform any actions or configuration required based 94on the servername extension received in the incoming connection. 95When 96.Fa cb 97is 98.Dv NULL , 99SNI is not used. 100The 101.Fa arg 102value is a pointer which is passed to the application callback. 103.Pp 104.Fn SSL_CTX_set_tlsext_servername_arg 105sets a context-specific argument to be passed into the callback for 106.Fa ctx . 107.Pp 108.Fn SSL_set_tlsext_host_name 109sets the server name indication ClientHello extension 110to contain the value 111.Fa name , 112or clears it if 113.Fa name 114is 115.Dv NULL . 116The type of server name indication 117extension is set to 118.Dv TLSEXT_NAMETYPE_host_name 119as defined in RFC 3546. 120.Pp 121All three functions are implemented as macros. 122.Pp 123The ALPN and SNI callbacks are both executed during Client Hello 124processing. 125The servername callback is executed first, followed by the ALPN 126callback. 127.Sh RETURN VALUES 128.Fn SSL_CTX_set_tlsext_servername_callback 129and 130.Fn SSL_CTX_set_tlsext_servername_arg 131always return 1 indicating success. 132.Pp 133.Fn SSL_get_servername 134returns a servername extension value of the specified type if provided 135in the Client Hello, or 136.Dv NULL 137otherwise. 138.Pp 139.Fn SSL_get_servername_type 140returns the servername type or -1 if no servername is present. 141Currently the only supported type (defined in RFC 3546) is 142.Dv TLSEXT_NAMETYPE_host_name . 143.Pp 144.Fn SSL_set_tlsext_host_name 145returns 1 on success or 0 in case of an error. 146.Sh SEE ALSO 147.Xr ssl 3 , 148.Xr SSL_CTX_callback_ctrl 3 , 149.Xr SSL_CTX_set_alpn_select_cb 3 150.Sh HISTORY 151These functions first appeared in OpenSSL 0.9.8f 152and have been available since 153.Ox 4.5 . 154