lib/libssl/man/SSL_CTX_set_tlsext_servername_callback.3

   1 .\"     $OpenBSD: SSL_CTX_set_tlsext_servername_callback.3,v 1.3 2018/03/23 01:06:56 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: March 23 2018 $
  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
  91 sets the application callback
  92 .Fa cb
  93 used by a server to perform any actions or configuration required based
  94 on the servername extension received in the incoming connection.
  95 When
  96 .Fa cb
  97 is
  98 .Dv NULL ,
  99 SNI is not used.
 100 The
 101 .Fa arg
 102 value is a pointer which is passed to the application callback.
 103 .Pp
 104 .Fn SSL_CTX_set_tlsext_servername_arg
 105 sets a context-specific argument to be passed into the callback for
 106 .Fa ctx .
 107 .Pp
 108 .Fn SSL_set_tlsext_host_name
 109 sets the server name indication ClientHello extension
 110 to contain the value
 111 .Fa name ,
 112 or clears it if
 113 .Fa name
 114 is
 115 .Dv NULL .
 116 The type of server name indication
 117 extension is set to
 118 .Dv TLSEXT_NAMETYPE_host_name
 119 as defined in RFC 3546.
 120 .Pp
 121 All three functions are implemented as macros.
 122 .Pp
 123 The ALPN and SNI callbacks are both executed during Client Hello
 124 processing.
 125 The servername callback is executed first, followed by the ALPN
 126 callback.
 127 .Sh RETURN VALUES
 128 .Fn SSL_CTX_set_tlsext_servername_callback
 129 and
 130 .Fn SSL_CTX_set_tlsext_servername_arg
 131 always return 1 indicating success.
 132 .Pp
 133 .Fn SSL_get_servername
 134 returns a servername extension value of the specified type if provided
 135 in the Client Hello, or
 136 .Dv NULL
 137 otherwise.
 138 .Pp
 139 .Fn SSL_get_servername_type
 140 returns the servername type or -1 if no servername is present.
 141 Currently the only supported type (defined in RFC 3546) is
 142 .Dv TLSEXT_NAMETYPE_host_name .
 143 .Pp
 144 .Fn SSL_set_tlsext_host_name
 145 returns 1 on success or 0 in case of an error.
 146 .Sh SEE ALSO
 147 .Xr SSL_CTX_callback_ctrl 3 ,
 148 .Xr SSL_CTX_set_alpn_select_cb 3
 149 .Sh HISTORY
 150 These functions first appeared in OpenSSL 0.9.8f
 151 and have been available since
 152 .Ox 4.5 .