xref: /openssl/doc/man3/SSL_set1_host.pod (revision 0f84cbc3)
1=pod
2
3=head1 NAME
4
5SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername -
6SSL server verification parameters
7
8=head1 SYNOPSIS
9
10 #include <openssl/ssl.h>
11
12 int SSL_set1_host(SSL *s, const char *hostname);
13 int SSL_add1_host(SSL *s, const char *hostname);
14 void SSL_set_hostflags(SSL *s, unsigned int flags);
15 const char *SSL_get0_peername(SSL *s);
16
17=head1 DESCRIPTION
18
19These functions configure server hostname checks in the SSL client.
20
21SSL_set1_host() sets the expected DNS hostname to B<name> clearing
22any previously specified hostname.  If B<name> is NULL
23or the empty string, the list of hostnames is cleared and name
24checks are not performed on the peer certificate.  When a nonempty
25B<name> is specified, certificate verification automatically checks
26the peer hostname via L<X509_check_host(3)> with B<flags> as specified
27via SSL_set_hostflags().  Clients that enable DANE TLSA authentication
28via L<SSL_dane_enable(3)> should leave it to that function to set
29the primary reference identifier of the peer, and should not call
30SSL_set1_host().
31
32SSL_add1_host() adds B<name> as an additional reference identifier
33that can match the peer's certificate.  Any previous names set via
34SSL_set1_host() or SSL_add1_host() are retained, no change is made
35if B<name> is NULL or empty.  When multiple names are configured,
36the peer is considered verified when any name matches.  This function
37is required for DANE TLSA in the presence of service name indirection
38via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or
39RFC7673.
40
41SSL_set_hostflags() sets the B<flags> that will be passed to
42L<X509_check_host(3)> when name checks are applicable, by default
43the B<flags> value is 0.  See L<X509_check_host(3)> for the list
44of available flags and their meaning.
45
46SSL_get0_peername() returns the DNS hostname or subject CommonName
47from the peer certificate that matched one of the reference
48identifiers.  When wildcard matching is not disabled, the name
49matched in the peer certificate may be a wildcard name.  When one
50of the reference identifiers configured via SSL_set1_host() or
51SSL_add1_host() starts with ".", which indicates a parent domain prefix
52rather than a fixed name, the matched peer name may be a sub-domain
53of the reference identifier.  The returned string is allocated by
54the library and is no longer valid once the associated B<ssl> handle
55is cleared or freed, or a renegotiation takes place.  Applications
56must not free the return value.
57
58SSL clients are advised to use these functions in preference to
59explicitly calling L<X509_check_host(3)>.  Hostname checks may be out
60of scope with the RFC7671 DANE-EE(3) certificate usage, and the
61internal check will be suppressed as appropriate when DANE is
62enabled.
63
64=head1 RETURN VALUES
65
66SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for
67failure.
68
69SSL_get0_peername() returns NULL if peername verification is not
70applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
71matched.  Otherwise, it returns the matched peername.  To determine
72whether verification succeeded call L<SSL_get_verify_result(3)>.
73
74=head1 EXAMPLES
75
76Suppose "smtp.example.com" is the MX host of the domain "example.com".
77The calls below will arrange to match either the MX hostname or the
78destination domain name in the SMTP server certificate.  Wildcards
79are supported, but must match the entire label.  The actual name
80matched in the certificate (which might be a wildcard) is retrieved,
81and must be copied by the application if it is to be retained beyond
82the lifetime of the SSL connection.
83
84 SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
85 if (!SSL_set1_host(ssl, "smtp.example.com"))
86     /* error */
87 if (!SSL_add1_host(ssl, "example.com"))
88     /* error */
89
90 /* XXX: Perform SSL_connect() handshake and handle errors here */
91
92 if (SSL_get_verify_result(ssl) == X509_V_OK) {
93     const char *peername = SSL_get0_peername(ssl);
94
95     if (peername != NULL)
96         /* Name checks were in scope and matched the peername */
97 }
98
99=head1 SEE ALSO
100
101L<ssl(7)>,
102L<X509_check_host(3)>,
103L<SSL_get_verify_result(3)>.
104L<SSL_dane_enable(3)>.
105
106=head1 HISTORY
107
108These functions were added in OpenSSL 1.1.0.
109
110=head1 COPYRIGHT
111
112Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
113
114Licensed under the Apache License 2.0 (the "License").  You may not use
115this file except in compliance with the License.  You can obtain a copy
116in the file LICENSE in the source distribution or at
117L<https://www.openssl.org/source/license.html>.
118
119=cut
120