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

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