TLS_LOAD_FILE(3)

okay so bestie, gather round, because this is TLS_LOAD_FILE(3) — a page from the Library Functions Manual for libtls, and it's literally the whole certificate-and-key-configuration friend group. Yes, all 26 of them. They're a package deal. 💅

✨ NAME ✨

tls_load_file, tls_unload_file, tls_config_set_ca_file, tls_config_set_ca_path, tls_config_set_ca_mem, tls_config_set_cert_file, tls_config_set_cert_mem, tls_config_set_crl_file, tls_config_set_crl_mem, tls_config_set_key_file, tls_config_set_key_mem, tls_config_set_ocsp_staple_mem, tls_config_set_ocsp_staple_file, tls_config_set_keypair_file, tls_config_set_keypair_mem, tls_config_set_keypair_ocsp_file, tls_config_set_keypair_ocsp_mem, tls_config_add_keypair_file, tls_config_add_keypair_ocsp_mem, tls_config_add_keypair_ocsp_file, tls_config_add_keypair_mem, tls_config_clear_keys, tls_config_set_verify_depth, tls_config_verify_client, tls_config_verify_client_optional, tls_default_ca_cert_file

...and what do they all do? TLS certificate and key configuration, obviously. 💖

✨ SYNOPSIS ✨

So you're pulling from the library libtls, which is riding on libssl and libcrypto, and you get all of this the second you write #include <tls.h>. Here's the whole squad in their natural habitat:

uint8_t *
tls_load_file(const char *file, size_t *len, char *password);

void
tls_unload_file(uint8_t *buf, size_t len);

int
tls_config_set_ca_file(struct tls_config *config, const char *ca_file);

int
tls_config_set_ca_path(struct tls_config *config, const char *ca_path);

int
tls_config_set_ca_mem(struct tls_config *config, const uint8_t *cert,
    size_t len);

int
tls_config_set_cert_file(struct tls_config *config,
    const char *cert_file);

int
tls_config_set_cert_mem(struct tls_config *config, const uint8_t *cert,
    size_t len);

int
tls_config_set_crl_file(struct tls_config *config,
    const char *crl_file);

int
tls_config_set_crl_mem(struct tls_config *config, const uint8_t *crl,
    size_t len);

int
tls_config_set_key_file(struct tls_config *config,
    const char *key_file);

int
tls_config_set_key_mem(struct tls_config *config, const uint8_t *key,
    size_t len);

int
tls_config_set_ocsp_staple_mem(struct tls_config *config,
    const uint8_t *staple, size_t len);

int
tls_config_set_ocsp_staple_file(struct tls_config *config,
    const char *staple_file);

int
tls_config_set_keypair_file(struct tls_config *config,
    const char *cert_file, const char *key_file);

int
tls_config_set_keypair_mem(struct tls_config *config,
    const uint8_t *cert, size_t cert_len, const uint8_t *key,
    size_t key_len);

int
tls_config_set_keypair_ocsp_file(struct tls_config *config,
    const char *cert_file, const char *key_file,
    const char *staple_file);

int
tls_config_set_keypair_ocsp_mem(struct tls_config *config,
    const uint8_t *cert, size_t cert_len, const uint8_t *key,
    size_t key_len, const uint8_t *staple, size_t staple_len);

int
tls_config_add_keypair_file(struct tls_config *config,
    const char *cert_file, const char *key_file);

int
tls_config_add_keypair_mem(struct tls_config *config,
    const uint8_t *cert, size_t cert_len, const uint8_t *key,
    size_t key_len);

int
tls_config_add_keypair_ocsp_file(struct tls_config *config,
    const char *cert_file, const char *key_file,
    const char *staple_file);

int
tls_config_add_keypair_ocsp_mem(struct tls_config *config,
    const uint8_t *cert, size_t cert_len, const uint8_t *key,
    size_t key_len, const uint8_t *staple, size_t staple_len);

void
tls_config_clear_keys(struct tls_config *config);

int
tls_config_set_verify_depth(struct tls_config *config,
    int verify_depth);

void
tls_config_verify_client(struct tls_config *config);

void
tls_config_verify_client_optional(struct tls_config *config);

const char *
tls_default_ca_cert_file(void);

💖 DESCRIPTION 💖

Okay so here's the vibe check on each one, in order, no skipping, because I would never do you like that. 🫶

• tls_load_file() — loads a certificate or key off the disk into memory so you can hand it to tls_config_set_ca_mem(), tls_config_set_cert_mem(), tls_config_set_crl_mem() or tls_config_set_key_mem(). And get this: a private key will be decrypted if you pass that optional password argument. iykyk. 🔑
• tls_unload_file() — unloads the memory that came back from an earlier tls_load_file() call, and it makes sure the memory contents get discarded. Cleanup queen behavior, honestly.
• tls_default_ca_cert_file() — returns the path of the file that holds the default root certificates. It just tells you where they live. 🏠
• tls_config_set_ca_file() — loads a file containing the root certificates.
• tls_config_set_ca_path() — sets the path (that's a directory, bestie) which should be searched for root certificates.
• tls_config_set_ca_mem() — sets the root certificates straight from memory.
• tls_config_set_cert_file() — loads a file containing the public certificate.
• tls_config_set_cert_mem() — sets the public certificate directly from memory.
• tls_config_set_crl_file() — loads a file containing the Certificate Revocation List (CRL). yes that's what CRL stands for, you're welcome 💅
• tls_config_set_crl_mem() — sets the CRL directly from memory.
• tls_config_set_key_file() — loads a file containing the private key.
• tls_config_set_key_mem() — directly sets the private key from memory.
• tls_config_set_ocsp_staple_file() — loads a file containing a DER-encoded OCSP response that gets stapled during the TLS handshake. ✨stapled✨
• tls_config_set_ocsp_staple_mem() — sets a DER-encoded OCSP response to be stapled during the TLS handshake, but from memory this time.
• tls_config_set_keypair_file() — loads two files, from which the public certificate and private key will be read.
• tls_config_set_keypair_mem() — directly sets the public certificate and private key from memory.
• tls_config_set_keypair_ocsp_file() — loads three files: the public certificate, the private key, and the DER-encoded OCSP staple. iconique trio 🎀
• tls_config_set_keypair_ocsp_mem() — directly sets the public certificate, private key, and DER-encoded OCSP staple from memory.
• tls_config_add_keypair_file() — adds an additional public certificate and private key from the specified files, used as an alternative certificate for Server Name Indication (server only).
• tls_config_add_keypair_mem() — adds an additional public certificate and private key from memory, used as an alternative certificate for Server Name Indication (server only).
• tls_config_add_keypair_ocsp_file() — adds an additional public certificate, private key, and DER-encoded OCSP staple from the specified files, used as an alternative certificate for Server Name Indication (server only).
• tls_config_add_keypair_ocsp_mem() — adds an additional public certificate, private key, and DER-encoded OCSP staple from memory, used as an alternative certificate for Server Name Indication (server only).
• tls_config_clear_keys() — clears any secret keys from memory. bye bye secrets, we don't know her 🫡
• tls_config_set_verify_depth() — limits the number of intermediate certificates that will be followed during certificate validation.
• tls_config_verify_client() — enables client certificate verification, requiring the client to send a certificate (server only).
• tls_config_verify_client_optional() — enables client certificate verification, but without requiring the client to send a certificate (server only). the chill version.

heads up bestie: those (server only) notes are not a suggestion, they're a whole rule. server side. periodt. 💀

🌸 RETURN VALUES 🌸

tls_load_file() returns NULL on error or an out of memory condition. Not great, not terrible, but at least you know. 😭

The other functions return 0 on success or -1 on error. That's it. That's the whole personality.

🦋 SEE ALSO 🦋

Go read these next, they're all in section 3 and they all ate:

• tls_config_ocsp_require_stapling(3)
• tls_config_set_protocols(3)
• tls_config_set_session_id(3)
• tls_configure(3)
• tls_init(3)

🌈 HISTORY 🌈

A lil timeline for you, because we stan a documented glow-up:

• tls_config_set_ca_file(), tls_config_set_ca_path(), tls_config_set_cert_file(), tls_config_set_cert_mem(), tls_config_set_key_file(), tls_config_set_key_mem(), and tls_config_set_verify_depth() appeared in OpenBSD 5.6 and got their final names in OpenBSD 5.7. name change era.
• tls_load_file(), tls_config_set_ca_mem(), and tls_config_clear_keys() appeared in OpenBSD 5.7.
• tls_config_verify_client() and tls_config_verify_client_optional() appeared in OpenBSD 5.9.
• tls_config_set_keypair_file() and tls_config_set_keypair_mem() appeared in OpenBSD 6.0, and tls_config_add_keypair_file() and tls_config_add_keypair_mem() in OpenBSD 6.1.
• tls_config_set_crl_file() and tls_config_set_crl_mem() appeared in OpenBSD 6.2.

👑 AUTHORS 👑

Give it up for Joel Sing <jsing@openbsd.org>, with contributions from Ted Unangst <tedu@openbsd.org> and Bob Beck <beck@openbsd.org>. 🫶

And extra flowers for Reyk Floeter <reyk@openbsd.org>, who wrote tls_load_file() and tls_config_set_ca_mem().

---

and that's the page!! this lil beauty is from the Debian build, dated July 7, 2025 — so go forth, load those files, unload them properly, and don't leak your keys. ily bestie, stan secure TLS 💖✨🎀