TLS_LOAD_FILE(3) | Library Functions Manual | TLS_LOAD_FILE(3)

# 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` — TLS certificate and key configuration

# SYNOPSIS

library “libtls” libssl libcrypto
`#include <tls.h>`

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

`tls_load_file`() loads a certificate or key from disk into memory to be used with `tls_config_set_ca_mem`(), `tls_config_set_cert_mem`(), `tls_config_set_crl_mem`() or `tls_config_set_key_mem`(). A private key will be decrypted if the optional password argument is specified.

`tls_unload_file`() unloads the memory that was returned from an earlier `tls_load_file`() call, ensuring that the memory contents is discarded.

`tls_default_ca_cert_file`() returns the path of the file that contains the default root certificates.

`tls_config_set_ca_file`() loads a file containing the root certificates.

`tls_config_set_ca_path`() sets the path (directory) which should be searched for root certificates.

`tls_config_set_ca_mem`() sets the root certificates directly 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).

`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 to be stapled during the TLS handshake.

`tls_config_set_ocsp_staple_mem`() sets a DER-encoded OCSP response to be stapled during the TLS handshake from memory.

`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 containing the public certificate, private key, and DER-encoded OCSP staple.

`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.

`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, without requiring the client to send a certificate (server only).

# RETURN VALUES

`tls_load_file`() returns `NULL` on error or an out of memory condition.

The other functions return 0 on success or -1 on error.

# SEE ALSO

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

# HISTORY

`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.

`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

Joel Sing <jsing@openbsd.org> with contributions from
Ted Unangst <tedu@openbsd.org> and
Bob Beck <beck@openbsd.org>.

`tls_load_file`() and `tls_config_set_ca_mem`() were written by
Reyk Floeter <reyk@openbsd.org>.

July 7, 2025 | Debian