]>
Commit | Line | Data |
---|---|---|
8c55c461 JS |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | SSL_CTX_set_tlsext_servername_callback, SSL_CTX_set_tlsext_servername_arg, | |
190b9a03 PY |
6 | SSL_get_servername_type, SSL_get_servername, |
7 | SSL_set_tlsext_host_name - handle server name indication (SNI) | |
8c55c461 JS |
8 | |
9 | =head1 SYNOPSIS | |
10 | ||
11 | #include <openssl/ssl.h> | |
12 | ||
13 | long SSL_CTX_set_tlsext_servername_callback(SSL_CTX *ctx, | |
721eb8f6 | 14 | int (*cb)(SSL *s, int *al, void *arg)); |
8c55c461 JS |
15 | long SSL_CTX_set_tlsext_servername_arg(SSL_CTX *ctx, void *arg); |
16 | ||
17 | const char *SSL_get_servername(const SSL *s, const int type); | |
18 | int SSL_get_servername_type(const SSL *s); | |
19 | ||
190b9a03 PY |
20 | int SSL_set_tlsext_host_name(const SSL *s, const char *name); |
21 | ||
8c55c461 JS |
22 | =head1 DESCRIPTION |
23 | ||
721eb8f6 MC |
24 | The functionality provided by the servername callback is mostly superseded by |
25 | the ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb(). | |
26 | However, even where the ClientHello callback is used, the servername callback is | |
27 | still necessary in order to acknowledge the servername requested by the client. | |
e5db7fcf | 28 | |
8c55c461 JS |
29 | SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb> |
30 | used by a server to perform any actions or configuration required based on | |
31 | the servername extension received in the incoming connection. When B<cb> | |
721eb8f6 MC |
32 | is NULL, SNI is not used. |
33 | ||
34 | The servername callback should return one of the following values: | |
35 | ||
36 | =over 4 | |
37 | ||
38 | =item SSL_TLSEXT_ERR_OK | |
39 | ||
40 | This is used to indicate that the servername requested by the client has been | |
41 | accepted. Typically a server will call SSL_set_SSL_CTX() in the callback to set | |
42 | up a different configuration for the selected servername in this case. | |
43 | ||
44 | =item SSL_TLSEXT_ERR_ALERT_FATAL | |
45 | ||
46 | In this case the servername requested by the client is not accepted and the | |
47 | handshake will be aborted. The value of the alert to be used should be stored in | |
48 | the location pointed to by the B<al> parameter to the callback. By default this | |
49 | value is initialised to SSL_AD_UNRECOGNIZED_NAME. | |
50 | ||
51 | =item SSL_TLSEXT_ERR_ALERT_WARNING | |
52 | ||
53 | If this value is returned then the servername is not accepted by the server. | |
54 | However the handshake will continue and send a warning alert instead. The value | |
55 | of the alert should be stored in the location pointed to by the B<al> parameter | |
56 | as for SSL_TLSEXT_ERR_ALERT_FATAL above. Note that TLSv1.3 does not support | |
57 | warning alerts, so if TLSv1.3 has been negotiated then this return value is | |
58 | treated the same way as SSL_TLSEXT_ERR_NOACK. | |
59 | ||
60 | =item SSL_TLSEXT_ERR_NOACK | |
61 | ||
62 | This return value indicates that the servername is not accepted by the server. | |
63 | No alerts are sent and the server will not acknowledge the requested servername. | |
64 | ||
65 | =back | |
8c55c461 JS |
66 | |
67 | SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be | |
721eb8f6 MC |
68 | passed into the callback (via the B<arg> parameter) for this B<SSL_CTX>. |
69 | ||
70 | The behaviour of SSL_get_servername() depends on a number of different factors. | |
71 | In particular note that in TLSv1.3 the servername is negotiated in every | |
72 | handshake. In TLSv1.2 the servername is only negotiated on initial handshakes | |
73 | and not on resumption handshakes. | |
74 | ||
75 | =over 4 | |
76 | ||
77 | =item On the client, before the handshake | |
78 | ||
79 | If a servername has been set via a call to SSL_set_tlsext_host_name() then it | |
80 | will return that servername. | |
81 | ||
82 | If one has not been set, but a TLSv1.2 resumption is being attempted and the | |
83 | session from the original handshake had a servername accepted by the server then | |
84 | it will return that servername. | |
85 | ||
86 | Otherwise it returns NULL. | |
8c55c461 | 87 | |
721eb8f6 MC |
88 | =item On the client, during or after the handshake and a TLSv1.2 (or below) |
89 | resumption occurred | |
90 | ||
91 | If the session from the orignal handshake had a servername accepted by the | |
92 | server then it will return that servername. | |
93 | ||
94 | Otherwise it returns the servername set via SSL_set_tlsext_host_name() or NULL | |
95 | if it was not called. | |
96 | ||
97 | =item On the client, during or after the handshake and a TLSv1.2 (or below) | |
98 | resumption did not occur | |
99 | ||
100 | It will return the servername set via SSL_set_tlsext_host_name() or NULL if it | |
101 | was not called. | |
102 | ||
103 | =item On the server, before the handshake | |
104 | ||
105 | The function will always return NULL before the handshake | |
106 | ||
107 | =item On the server, after the servername extension has been processed and a | |
108 | TLSv1.2 (or below) resumption occurred | |
109 | ||
110 | If a servername was accepted by the server in the original handshake then it | |
111 | will return that servername, or NULL otherwise. | |
112 | ||
113 | =item On the server, after the servername extension has been processed and a | |
114 | TLSv1.2 (or below) resumption did not occur | |
115 | ||
116 | The function will return the servername requested by the client in this | |
117 | handshake or NULL if none was requested. | |
118 | ||
119 | =back | |
120 | ||
121 | Note that the ClientHello callback occurs before a servername extension from the | |
122 | client is processed. The servername, certificate and ALPN callbacks occur after | |
123 | a servername extension from the client is processed. | |
8c55c461 JS |
124 | |
125 | SSL_get_servername_type() returns the servername type or -1 if no servername | |
126 | is present. Currently the only supported type (defined in RFC3546) is | |
127 | B<TLSEXT_NAMETYPE_host_name>. | |
128 | ||
190b9a03 PY |
129 | SSL_set_tlsext_host_name() sets the server name indication ClientHello extension |
130 | to contain the value B<name>. The type of server name indication extension is set | |
131 | to B<TLSEXT_NAMETYPE_host_name> (defined in RFC3546). | |
132 | ||
8c55c461 JS |
133 | =head1 NOTES |
134 | ||
e5db7fcf | 135 | Several callbacks are executed during ClientHello processing, including |
a9c0d8be DB |
136 | the ClientHello, ALPN, and servername callbacks. The ClientHello callback is |
137 | executed first, then the servername callback, followed by the ALPN callback. | |
8c55c461 | 138 | |
190b9a03 PY |
139 | The SSL_set_tlsext_host_name() function should only be called on SSL objects |
140 | that will act as clients; otherwise the configured B<name> will be ignored. | |
141 | ||
8c55c461 JS |
142 | =head1 RETURN VALUES |
143 | ||
144 | SSL_CTX_set_tlsext_servername_callback() and | |
145 | SSL_CTX_set_tlsext_servername_arg() both always return 1 indicating success. | |
190b9a03 | 146 | SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error. |
8c55c461 JS |
147 | |
148 | =head1 SEE ALSO | |
149 | ||
150 | L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>, | |
a9c0d8be | 151 | L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)> |
8c55c461 | 152 | |
721eb8f6 MC |
153 | =head1 HISTORY |
154 | ||
155 | SSL_get_servername() historically provided some unexpected results in certain | |
156 | corner cases. This has been fixed from OpenSSL 1.1.1e. | |
157 | ||
158 | Prior to 1.1.1e, when the client requested a servername in an initial TLSv1.2 | |
159 | handshake, the server accepted it, and then the client successfully resumed but | |
160 | set a different explict servername in the second handshake then when called by | |
161 | the client it returned the servername from the second handshake. This has now | |
162 | been changed to return the servername requested in the original handshake. | |
163 | ||
164 | Also prior to 1.1.1e, if the client sent a servername in the first handshake but | |
165 | the server did not accept it, and then a second handshake occured where TLSv1.2 | |
166 | resumption was successful then when called by the server it returned the | |
167 | servername requested in the original handshake. This has now been changed to | |
168 | NULL. | |
169 | ||
8c55c461 JS |
170 | =head1 COPYRIGHT |
171 | ||
e7ff223a | 172 | Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved. |
8c55c461 JS |
173 | |
174 | Licensed under the OpenSSL license (the "License"). You may not use | |
175 | this file except in compliance with the License. You can obtain a copy | |
176 | in the file LICENSE in the source distribution or at | |
177 | L<https://www.openssl.org/source/license.html>. | |
178 | ||
179 | =cut |