]>
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, | |
14 | int (*cb)(SSL *, int *, void *)); | |
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 | ||
a9c0d8be DB |
24 | The functionality provided by the servername callback is superseded by the |
25 | ClientHello callback, which can be set using SSL_CTX_set_client_hello_cb(). | |
e5db7fcf RS |
26 | The servername callback is retained for historical compatibility. |
27 | ||
8c55c461 JS |
28 | SSL_CTX_set_tlsext_servername_callback() sets the application callback B<cb> |
29 | used by a server to perform any actions or configuration required based on | |
30 | the servername extension received in the incoming connection. When B<cb> | |
31 | is NULL, SNI is not used. The B<arg> value is a pointer which is passed to | |
32 | the application callback. | |
33 | ||
34 | SSL_CTX_set_tlsext_servername_arg() sets a context-specific argument to be | |
35 | passed into the callback for this B<SSL_CTX>. | |
36 | ||
37 | SSL_get_servername() returns a servername extension value of the specified | |
38 | type if provided in the Client Hello or NULL. | |
39 | ||
40 | SSL_get_servername_type() returns the servername type or -1 if no servername | |
41 | is present. Currently the only supported type (defined in RFC3546) is | |
42 | B<TLSEXT_NAMETYPE_host_name>. | |
43 | ||
190b9a03 PY |
44 | SSL_set_tlsext_host_name() sets the server name indication ClientHello extension |
45 | to contain the value B<name>. The type of server name indication extension is set | |
46 | to B<TLSEXT_NAMETYPE_host_name> (defined in RFC3546). | |
47 | ||
8c55c461 JS |
48 | =head1 NOTES |
49 | ||
e5db7fcf | 50 | Several callbacks are executed during ClientHello processing, including |
a9c0d8be DB |
51 | the ClientHello, ALPN, and servername callbacks. The ClientHello callback is |
52 | executed first, then the servername callback, followed by the ALPN callback. | |
8c55c461 | 53 | |
190b9a03 PY |
54 | The SSL_set_tlsext_host_name() function should only be called on SSL objects |
55 | that will act as clients; otherwise the configured B<name> will be ignored. | |
56 | ||
8c55c461 JS |
57 | =head1 RETURN VALUES |
58 | ||
59 | SSL_CTX_set_tlsext_servername_callback() and | |
60 | SSL_CTX_set_tlsext_servername_arg() both always return 1 indicating success. | |
190b9a03 | 61 | SSL_set_tlsext_host_name() returns 1 on success, 0 in case of error. |
8c55c461 JS |
62 | |
63 | =head1 SEE ALSO | |
64 | ||
65 | L<ssl(7)>, L<SSL_CTX_set_alpn_select_cb(3)>, | |
a9c0d8be | 66 | L<SSL_get0_alpn_selected(3)>, L<SSL_CTX_set_client_hello_cb(3)> |
8c55c461 JS |
67 | |
68 | =head1 COPYRIGHT | |
69 | ||
70 | Copyright 2017 The OpenSSL Project Authors. All Rights Reserved. | |
71 | ||
4746f25a | 72 | Licensed under the Apache License 2.0 (the "License"). You may not use |
8c55c461 JS |
73 | this file except in compliance with the License. You can obtain a copy |
74 | in the file LICENSE in the source distribution or at | |
75 | L<https://www.openssl.org/source/license.html>. | |
76 | ||
77 | =cut |