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.