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
