|
Packit |
c4476c |
=pod
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 NAME
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set1_host, SSL_add1_host, SSL_set_hostflags, SSL_get0_peername -
|
|
Packit |
c4476c |
SSL server verification parameters
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SYNOPSIS
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
#include <openssl/ssl.h>
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
int SSL_set1_host(SSL *s, const char *hostname);
|
|
Packit |
c4476c |
int SSL_add1_host(SSL *s, const char *hostname);
|
|
Packit |
c4476c |
void SSL_set_hostflags(SSL *s, unsigned int flags);
|
|
Packit |
c4476c |
const char *SSL_get0_peername(SSL *s);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 DESCRIPTION
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
These functions configure server hostname checks in the SSL client.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set1_host() sets the expected DNS hostname to B<name> clearing
|
|
Packit |
c4476c |
any previously specified host name or names. If B<name> is NULL,
|
|
Packit |
c4476c |
or the empty string the list of hostnames is cleared, and name
|
|
Packit |
c4476c |
checks are not performed on the peer certificate. When a non-empty
|
|
Packit |
c4476c |
B<name> is specified, certificate verification automatically checks
|
|
Packit |
c4476c |
the peer hostname via L<X509_check_host(3)> with B<flags> as specified
|
|
Packit |
c4476c |
via SSL_set_hostflags(). Clients that enable DANE TLSA authentication
|
|
Packit |
c4476c |
via L<SSL_dane_enable(3)> should leave it to that function to set
|
|
Packit |
c4476c |
the primary reference identifier of the peer, and should not call
|
|
Packit |
c4476c |
SSL_set1_host().
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_add1_host() adds B<name> as an additional reference identifier
|
|
Packit |
c4476c |
that can match the peer's certificate. Any previous names set via
|
|
Packit |
c4476c |
SSL_set1_host() or SSL_add1_host() are retained, no change is made
|
|
Packit |
c4476c |
if B<name> is NULL or empty. When multiple names are configured,
|
|
Packit |
c4476c |
the peer is considered verified when any name matches. This function
|
|
Packit |
c4476c |
is required for DANE TLSA in the presence of service name indirection
|
|
Packit |
c4476c |
via CNAME, MX or SRV records as specified in RFC7671, RFC7672 or
|
|
Packit |
c4476c |
RFC7673.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set_hostflags() sets the B<flags> that will be passed to
|
|
Packit |
c4476c |
L<X509_check_host(3)> when name checks are applicable, by default
|
|
Packit |
c4476c |
the B<flags> value is 0. See L<X509_check_host(3)> for the list
|
|
Packit |
c4476c |
of available flags and their meaning.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_get0_peername() returns the DNS hostname or subject CommonName
|
|
Packit |
c4476c |
from the peer certificate that matched one of the reference
|
|
Packit |
c4476c |
identifiers. When wildcard matching is not disabled, the name
|
|
Packit |
c4476c |
matched in the peer certificate may be a wildcard name. When one
|
|
Packit |
c4476c |
of the reference identifiers configured via SSL_set1_host() or
|
|
Packit |
c4476c |
SSL_add1_host() starts with ".", which indicates a parent domain prefix
|
|
Packit |
c4476c |
rather than a fixed name, the matched peer name may be a sub-domain
|
|
Packit |
c4476c |
of the reference identifier. The returned string is allocated by
|
|
Packit |
c4476c |
the library and is no longer valid once the associated B<ssl> handle
|
|
Packit |
c4476c |
is cleared or freed, or a renegotiation takes place. Applications
|
|
Packit |
c4476c |
must not free the return value.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL clients are advised to use these functions in preference to
|
|
Packit |
c4476c |
explicitly calling L<X509_check_host(3)>. Hostname checks may be out
|
|
Packit |
c4476c |
of scope with the RFC7671 DANE-EE(3) certificate usage, and the
|
|
Packit |
c4476c |
internal check will be suppressed as appropriate when DANE is
|
|
Packit |
c4476c |
enabled.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 RETURN VALUES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set1_host() and SSL_add1_host() return 1 for success and 0 for
|
|
Packit |
c4476c |
failure.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_get0_peername() returns NULL if peername verification is not
|
|
Packit |
c4476c |
applicable (as with RFC7671 DANE-EE(3)), or no trusted peername was
|
|
Packit |
c4476c |
matched. Otherwise, it returns the matched peername. To determine
|
|
Packit |
c4476c |
whether verification succeeded call L<SSL_get_verify_result(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 EXAMPLES
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Suppose "smtp.example.com" is the MX host of the domain "example.com".
|
|
Packit |
c4476c |
The calls below will arrange to match either the MX hostname or the
|
|
Packit |
c4476c |
destination domain name in the SMTP server certificate. Wildcards
|
|
Packit |
c4476c |
are supported, but must match the entire label. The actual name
|
|
Packit |
c4476c |
matched in the certificate (which might be a wildcard) is retrieved,
|
|
Packit |
c4476c |
and must be copied by the application if it is to be retained beyond
|
|
Packit |
c4476c |
the lifetime of the SSL connection.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
SSL_set_hostflags(ssl, X509_CHECK_FLAG_NO_PARTIAL_WILDCARDS);
|
|
Packit |
c4476c |
if (!SSL_set1_host(ssl, "smtp.example.com"))
|
|
Packit |
c4476c |
/* error */
|
|
Packit |
c4476c |
if (!SSL_add1_host(ssl, "example.com"))
|
|
Packit |
c4476c |
/* error */
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
/* XXX: Perform SSL_connect() handshake and handle errors here */
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
if (SSL_get_verify_result(ssl) == X509_V_OK) {
|
|
Packit |
c4476c |
const char *peername = SSL_get0_peername(ssl);
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
if (peername != NULL)
|
|
Packit |
c4476c |
/* Name checks were in scope and matched the peername */
|
|
Packit |
c4476c |
}
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 SEE ALSO
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
L<X509_check_host(3)>,
|
|
Packit |
c4476c |
L<SSL_get_verify_result(3)>.
|
|
Packit |
c4476c |
L<SSL_dane_enable(3)>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 HISTORY
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
These functions were added in OpenSSL 1.1.0.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=head1 COPYRIGHT
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Copyright 2016-2019 The OpenSSL Project Authors. All Rights Reserved.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
Licensed under the OpenSSL license (the "License"). You may not use
|
|
Packit |
c4476c |
this file except in compliance with the License. You can obtain a copy
|
|
Packit |
c4476c |
in the file LICENSE in the source distribution or at
|
|
Packit |
c4476c |
L<https://www.openssl.org/source/license.html>.
|
|
Packit |
c4476c |
|
|
Packit |
c4476c |
=cut
|