TLS(3)

NAME
tls_init, tls_error, tls_config_new, tls_config_free, tls_config_set_ca_file, tls_config_set_ca_path, tls_config_set_cert_file, tls_config_set_cert_mem, tls_config_set_ciphers, tls_config_set_ecdhcurve, tls_config_set_key_file, tls_config_set_key_mem, tls_config_set_protocols, tls_config_set_verify_depth, tls_config_clear_keys, tls_config_insecure_noverifyhost, tls_config_insecure_noverifycert, tls_config_verify, tls_client, tls_server, tls_configure, tls_reset, tls_close, tls_free, tls_connect, tls_connect_fds, tls_connect_socket, tls_read, tls_write, - TLS client and server API

SYNOPSIS
#include <tls.h>
int
tls_init(void);
const char *
tls_error(struct tls *ctx);
struct tls_config *
tls_config_new(void);
void
tls_config_free(struct tls_config *config);
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_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_ciphers(struct tls_config *config, const char *ciphers);
int
tls_config_set_ecdhcurve(struct tls_config *config, const char *name);
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_protocols(struct tls_config *config, uint32_t protocols);
int
tls_config_set_verify_depth(struct tls_config *config, int verify_depth);
void
tls_config_clear_keys(struct tls_config *config);
void
tls_config_insecure_noverifyhost(struct tls_config *config);
void
tls_config_insecure_noverifycert(struct tls_config *config);
void
tls_config_verify(struct tls_config *config);
struct tls *
tls_client(void);
struct tls *
tls_server(void);
int
tls_configure(struct tls *ctx, struct tls_config *config);
void
tls_reset(struct tls *ctx);
int
tls_close(struct tls *ctx);
void
tls_free(struct tls *ctx);
int
tls_connect(struct tls *ctx, const char *host, const char *port);
int
tls_connect_fds(struct tls *ctx, int fd_read, int fd_write, const char *hostname);
int
tls_connect_socket(struct tls *ctx, int s, const char *hostname);
int
tls_read(struct tls *ctx, void *buf, size_t buflen, size_t *outlen);
int
tls_write(struct tls *ctx, const void *buf, size_t buflen, size_t *outlen);

DESCRIPTION
The tls family of functions establishes a secure communications channel using the TLS socket protocol. Both clients and servers are supported.

The tls_init() function should be called once before any function is used.

Before a connection is created, a configuration must be created. The tls_config_new() function returns a new default configuration that can be used for future connections. Several functions exist to change the options of the configuration; see below.

A tls connection is represented as a context. A new context is created by either the tls_client() or tls_server() functions. The context can then be configured with the function tls_configure(). The same tls_config object can be used to configure multiple contexts.

A client connection is initiated after configuration by calling tls_connect(). This function will create a new socket, connect to the specified host and port, and then establish a secure connection. An already existing socket can be upgraded to a secure connection by calling tls_connect_socket(). Alternatively, a secure connection can be established over a pair of existing file descriptors by calling tls_connect_fds().

Two functions are provided for input and output, tls_read() and tls_write().

After use, a tls context should be closed with tls_close(), and then freed by calling tls_free(). When no more contexts are to be created, the tls_config object should be freed by calling tls_config_free().

FUNCTIONS
The tls_init() function initializes global data structures. It should be called once before any other functions.

The following functions create and free configuration objects.

•   tls_config_new() allocates a new default configuration object.

•   tls_config_free() frees a configuration object.

The following functions modify a configuration by setting parameters. Configuration options may apply to only clients or only servers or both.

•   tls_config_set_ca_file() sets the filename used to load a file containing the root certificates. (Client)

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

•   tls_config_set_cert_file() sets file from which the public certificate will be read. (Client and server)

•   tls_config_set_cert_mem() sets the public certificate directly from memory. (Client and server)

•   tls_config_set_ciphers() sets the list of ciphers that may be used. (Client and server)

•   tls_config_set_key_file() sets the file from which the private key will be read. (Server)

•   tls_config_set_key_mem() directly sets the private key from memory. (Server)

•   tls_config_set_protocols() sets which versions of the protocol may be used. Possible values are the bitwise OR of:

    TLS_PROTOCOL_TLSv1_0
    TLS_PROTOCOL_TLSv1_1
    TLS_PROTOCOL_TLSv1_2

    Additionally, the values TLS_PROTOCOL_TLSv1 (all TLS versions) and TLS_PROTOCOLS_DEFAULT (currently all TLS versions) may be used. (Client and server)

•   tls_config_clear_keys() clears any secret keys from memory. (Server)

•   tls_config_insecure_noverifyhost() disables hostname verification. Be careful when using this option. (Client)

•   tls_config_insecure_noverifycert() disables certificate verification. Be extremely careful when using this option. (Client)

•   tls_config_verify() reenables hostname and certificate verification. (Client)

The following functions create, prepare, and free a connection context.

•   tls_client() creates a new tls context for client connections.

•   tls_server() creates a new tls context for server connections.

•   tls_configure() readies a tls context for use by applying the configuration options.

•   tls_close() closes a connection after use. If the connection was established using tls_connect_fds(), only the TLS layer will be closed and it is the caller's responsibility to close the file descriptors.

•   tls_free() frees a tls context after use.

The following functions initiate a connection and perform input and output operations.

•   tls_connect() connects a client context to the server named by host. The port may be numeric or a service name. If it is NULL then a host of the format "hostname:port" is permitted.

•   tls_connect_fds() connects a client context to a pair of existing file descriptors.

•   tls_connect_socket() connects a client context to an already established socket connection.

•   tls_read() reads buflen bytes of data from the socket into buf. The amount of data read is returned in outlen.

•   tls_write() writes buflen bytes of data from buf to the socket. The amount of data written is returned in outlen.

RETURN VALUES
Functions that return int will return 0 on success and -1 on error. Functions that return a pointer will return NULL on error.

HISTORY
The tls API first appeared in OpenBSD 5.6 as a response to the unnecessary challenges other APIs present in order to use them safely.