Scroll to navigation

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

#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

() 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.

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

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

() loads a file containing the root certificates.

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

() sets the root certificates directly from memory.

() loads a file containing the public certificate.

() sets the public certificate directly from memory.

() loads a file containing the Certificate Revocation List (CRL).

() sets the CRL directly from memory.

() loads a file containing the private key.

() directly sets the private key from memory.

() loads a file containing a DER-encoded OCSP response to be stapled during the TLS handshake.

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

() loads two files from which the public certificate and private key will be read.

() directly sets the public certificate and private key from memory.

() loads three files containing the public certificate, private key, and DER-encoded OCSP staple.

() directly sets the public certificate, private key, and DER-encoded OCSP staple from memory.

() adds an additional public certificate and private key from the specified files, used as an alternative certificate for Server Name Indication (server only).

() adds an additional public certificate and private key from memory, used as an alternative certificate for Server Name Indication (server only).

() 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).

() 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).

() clears any secret keys from memory.

() limits the number of intermediate certificates that will be followed during certificate validation.

() enables client certificate verification, requiring the client to send a certificate (server only).

() 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>.

January 1, 2022 Debian