SSL_SET1_HOST(3)

💅 SSL_SET1_HOST(3) — the server verification params page, bestie

okay so this is a page from the libssl / libcrypto library manual (the OpenSSL-ish one, iykyk) — SSL server verification parameters. that's the whole vibe. it's about three little functions that let your TLS client go "hmm, is this actually the server I think it is?" 🕵️‍♀️✨

---

✨ SYNOPSIS ✨

grab the header first, obviously:

#include <openssl/ssl.h>

then here's your cast of characters 🎀

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() sets up a server hostname check in the ssl client — it sets the expected DNS hostname to hostname and clears any previously specified hostname (so like, out with the old, in with the new 🫶). if hostname is NULL or the empty string, then name checks are not performed on the peer certificate. if you give it a nonempty hostname, certificate verification automatically checks the peer hostname via X509_check_host(3) with flags set to 0.

SSL_set_hostflags() sets the flags that get passed to X509_check_host(3) whenever name checks are applicable. by default the flags value is 0. see X509_check_host(3) for the full list of available flags and what they mean — that's a different page, go read it, I'm not doing your homework 📚✨

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 that case, the matched peername may be a sub-domain of the reference identifier. 👑

⚠️ the returned string is owned by the library!! it 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. do not free it. do not pass go. do not collect $200. 💀

SSL clients are advised to use these functions in preference to explicitly calling X509_check_host(3) — like, that's the whole recommendation, bestie, take the shortcut 🌈

---

⭐ RETURN VALUES ⭐

• SSL_set1_host() — returns 1 for success or 0 for failure. simple. iconic. slay. ✅
• 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 figure out whether verification actually succeeded — don't just vibe-check it 🙈

---

🦋 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 it must be copied by the application if it's going to be retained beyond the lifetime of the SSL connection — yes, copy it yourself, the library is not your storage unit 🎀

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)

go read them. all of them. I believe in you 💜

---

🧚 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. glow-up timeline fr fr 🌸⭐

---

💌 and that's the page, bestie! brought to you by the Debian version, dated June 8, 2025, from the SSL_SET1_HOST(3) manual — go verify some hostnames responsibly 🫶✨🎀