Debian Codegraph @

upstream/debian-unstable/man3/SSL_CTX_set_tlsext_servername_callback.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3SSL"
58 .TH SSL_CTX_SET_TLSEXT_SERVERNAME_CALLBACK 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg,
65 SSL_get_servername_type, SSL_get_servername,
66 SSL_set_tlsext_host_name \- handle server name indication (SNI)
67 .SH SYNOPSIS
68 .IX Header "SYNOPSIS"
69 .Vb 1
70 \& #include <openssl/ssl.h>
71 \&
72 \& long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx,
73 \& int (*cb)(SSL *s, int *al, void *arg));
74 \& long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg);
75 \&
76 \& const char *SSL_get_servername(const SSL *s, const int type);
77 \& int SSL_get_servername_type(const SSL *s);
78 \&
79 \& int SSL_set_tlsext_host_name(const SSL *s, const char *name);
80 .Ve
81 .SH DESCRIPTION
82 .IX Header "DESCRIPTION"
83 The functionality provided by the servername callback is mostly superseded by
84 the ClientHello callback, which can be set using \fBSSL_CTX_set_client_hello_cb()\fR.
85 However, even where the ClientHello callback is used, the servername callback is
86 still necessary in order to acknowledge the servername requested by the client.
87 .PP
88 \&\fBSSL_CTX_set_tlsext_servername_callback()\fR sets the application callback \fBcb\fR
89 used by a server to perform any actions or configuration required based on
90 the servername extension received in the incoming connection. When \fBcb\fR
91 is NULL, SNI is not used.
92 .PP
93 The servername callback should return one of the following values:
94 .IP SSL_TLSEXT_ERR_OK 4
95 .IX Item "SSL_TLSEXT_ERR_OK"
96 This is used to indicate that the servername requested by the client has been
97 accepted. Typically a server will call \fBSSL_set_SSL_CTX()\fR in the callback to set
98 up a different configuration for the selected servername in this case.
99 .IP SSL_TLSEXT_ERR_ALERT_FATAL 4
100 .IX Item "SSL_TLSEXT_ERR_ALERT_FATAL"
101 In this case the servername requested by the client is not accepted and the
102 handshake will be aborted. The value of the alert to be used should be stored in
103 the location pointed to by the \fBal\fR parameter to the callback. By default this
104 value is initialised to SSL_AD_UNRECOGNIZED_NAME.
105 .IP SSL_TLSEXT_ERR_ALERT_WARNING 4
106 .IX Item "SSL_TLSEXT_ERR_ALERT_WARNING"
107 If this value is returned then the servername is not accepted by the server.
108 However, the handshake will continue and send a warning alert instead. The value
109 of the alert should be stored in the location pointed to by the \fBal\fR parameter
110 as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support
111 warning alerts, so if TLSv1.3 has been negotiated then this return value is
112 treated the same way as SSL_TLSEXT_ERR_NOACK.
113 .IP SSL_TLSEXT_ERR_NOACK 4
114 .IX Item "SSL_TLSEXT_ERR_NOACK"
115 This return value indicates that the servername is not accepted by the server.
116 No alerts are sent and the server will not acknowledge the requested servername.
117 .PP
118 \&\fBSSL_CTX_set_tlsext_servername_arg()\fR sets a context-specific argument to be
119 passed into the callback (via the \fBarg\fR parameter) for this \fBSSL_CTX\fR.
120 .PP
121 The behaviour of \fBSSL_get_servername()\fR depends on a number of different factors.
122 In particular note that in TLSv1.3 the servername is negotiated in every
123 handshake. In TLSv1.2 the servername is only negotiated on initial handshakes
124 and not on resumption handshakes.
125 .IP "On the client, before the handshake" 4
126 .IX Item "On the client, before the handshake"
127 If a servername has been set via a call to \fBSSL_set_tlsext_host_name()\fR then it
128 will return that servername.
129 .Sp
130 If one has not been set, but a TLSv1.2 resumption is being attempted and the
131 session from the original handshake had a servername accepted by the server then
132 it will return that servername.
133 .Sp
134 Otherwise it returns NULL.
135 .IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred" 4
136 .IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption occurred"
137 If the session from the original handshake had a servername accepted by the
138 server then it will return that servername.
139 .Sp
140 Otherwise it returns the servername set via \fBSSL_set_tlsext_host_name()\fR or NULL
141 if it was not called.
142 .IP "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur" 4
143 .IX Item "On the client, during or after the handshake and a TLSv1.2 (or below) resumption did not occur"
144 It will return the servername set via \fBSSL_set_tlsext_host_name()\fR or NULL if it
145 was not called.
146 .IP "On the server, before the handshake" 4
147 .IX Item "On the server, before the handshake"
148 The function will always return NULL before the handshake
149 .IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred" 4
150 .IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption occurred"
151 If a servername was accepted by the server in the original handshake then it
152 will return that servername, or NULL otherwise.
153 .IP "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur" 4
154 .IX Item "On the server, after the servername extension has been processed and a TLSv1.2 (or below) resumption did not occur"
155 The function will return the servername requested by the client in this
156 handshake or NULL if none was requested.
157 .PP
158 Note that the ClientHello callback occurs before a servername extension from the
159 client is processed. The servername, certificate and ALPN callbacks occur after
160 a servername extension from the client is processed.
161 .PP
162 \&\fBSSL_get_servername_type()\fR returns the servername type or \-1 if no servername
163 is present. Currently the only supported type (defined in RFC3546) is
164 \&\fBTLSEXT_NAMETYPE_host_name\fR.
165 .PP
166 \&\fBSSL_set_tlsext_host_name()\fR sets the server name indication ClientHello extension
167 to contain the value \fBname\fR. The type of server name indication extension is set
168 to \fBTLSEXT_NAMETYPE_host_name\fR (defined in RFC3546).
169 .SH NOTES
170 .IX Header "NOTES"
171 Several callbacks are executed during ClientHello processing, including
172 the ClientHello, ALPN, and servername callbacks. The ClientHello callback is
173 executed first, then the servername callback, followed by the ALPN callback.
174 .PP
175 The \fBSSL_set_tlsext_host_name()\fR function should only be called on SSL objects
176 that will act as clients; otherwise the configured \fBname\fR will be ignored.
177 .SH "RETURN VALUES"
178 .IX Header "RETURN VALUES"
179 \&\fBSSL_CTX_set_tlsext_servername_callback()\fR and
180 \&\fBSSL_CTX_set_tlsext_servername_arg()\fR both always return 1 indicating success.
181 \&\fBSSL_set_tlsext_host_name()\fR returns 1 on success, 0 in case of error.
182 .SH "SEE ALSO"
183 .IX Header "SEE ALSO"
184 \&\fBssl\fR\|(7), \fBSSL_CTX_set_alpn_select_cb\fR\|(3),
185 \&\fBSSL_get0_alpn_selected\fR\|(3), \fBSSL_CTX_set_client_hello_cb\fR\|(3)
186 .SH HISTORY
187 .IX Header "HISTORY"
188 \&\fBSSL_get_servername()\fR historically provided some unexpected results in certain
189 corner cases. This has been fixed from OpenSSL 1.1.1e.
190 .PP
191 Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2
192 handshake, the server accepted it, and then the client successfully resumed but
193 set a different explicit servername in the second handshake then when called by
194 the client it returned the servername from the second handshake. This has now
195 been changed to return the servername requested in the original handshake.
196 .PP
197 Also prior to 1.1.1e, if the client sent a servername in the first handshake but
198 the server did not accept it, and then a second handshake occurred where TLSv1.2
199 resumption was successful then when called by the server it returned the
200 servername requested in the original handshake. This has now been changed to
201 NULL.
202 .SH COPYRIGHT
203 .IX Header "COPYRIGHT"
204 Copyright 2017\-2020 The OpenSSL Project Authors. All Rights Reserved.
205 .PP
206 Licensed under the Apache License 2.0 (the "License"). You may not use
207 this file except in compliance with the License. You can obtain a copy
208 in the file LICENSE in the source distribution or at
209 <https://www.openssl.org/source/license.html>.