---
name: "libressl-SSL_set1_host"
section: "3"
platform: "linux"
package: "libressl"
version: "4.4.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/libressl-SSL_set1_host"
---

# libressl-SSL\_set1\_host(3)

SSL server verification parameters

## NAME

**SSL\_set1\_host**, **SSL\_set\_hostflags**, **SSL\_get0\_peername** – SSL server verification parameters

## SYNOPSIS

SSL Library (libssl, -lssl) libcrypto

**#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/3.md), 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.