NAME
SSL_set1_host
,
SSL_set_hostflags
,
SSL_get0_peername
—
SSL server verification
parameters
SYNOPSIS
#include
<openssl/ssl.h>
int
SSL_set1_host
(SSL *ssl,
const char *hostname);
void
SSL_set_hostflags
(SSL *ssl,
unsigned int flags);
const char *
SSL_get0_peername
(SSL *ssl);
DESCRIPTION
SSL_set1_host
()
configures a server hostname check in the ssl client,
setting the expected DNS hostname to hostname and
clearing any previously specified hostname. If
hostname is NULL
or the empty
string, name checks are not performed on the peer certificate. If a nonempty
hostname is specified, certificate verification
automatically checks the peer hostname via
X509_check_host(3)
with flags set to 0.
SSL_set_hostflags
()
sets the flags that will be passed to
X509_check_host(3)
when name checks are applicable, by default the flags value is 0. See
X509_check_host(3)
for the list of available flags and their meaning.
SSL_get0_peername
()
returns the DNS hostname or subject CommonName from the peer certificate
that matched one of the reference identifiers. Unless wildcard matching is
disabled, the name matched in the peer certificate may be a wildcard name. A
reference identifier starting with ‘.’ indicates a parent
domain prefix rather than a fixed name. In this case, the matched peername
may be a sub-domain of the reference identifier. The returned string is
owned by the library and is no longer valid once the associated
ssl object is cleared or freed, or if a renegotiation
takes place. Applications must not free the return value.
SSL clients are advised to use these functions in preference to explicitly calling X509_check_host(3).
RETURN VALUES
SSL_set1_host
() returns 1 for success or 0
for failure.
SSL_get0_peername
() returns the matched
peername or NULL
if peername verification is not
applicable or no trusted peername was matched. Use
SSL_get_verify_result(3) to determine whether verification
succeeded.
EXAMPLES
The calls below check the hostname. Wildcards are supported, but they must match the entire label. The actual name matched in the certificate (which might be a wildcard) is retrieved, and must be copied by the application if it is to be retained beyond the lifetime of the SSL connection.
if (!SSL_set1_host(ssl, "smtp.example.com")) /* error */ /* XXX: Perform SSL_connect() handshake and handle errors here */ if (SSL_get_verify_result(ssl) == X509_V_OK) { const char *peername = SSL_get0_peername(ssl); if (peername != NULL) /* Name checks were in scope and matched the peername */ }
SEE ALSO
ssl(3), SSL_CTX_set_verify(3), SSL_get_peer_certificate(3), SSL_get_verify_result(3), X509_check_host(3), X509_VERIFY_PARAM_set1_host(3)
HISTORY
All three functions first appeared in OpenSSL 1.1.0.
SSL_set1_host
() has been available since
OpenBSD 6.5, and
SSL_set_hostflags
() and
SSL_get0_peername
() since OpenBSD
6.9.