OpenBSD manual page server

Manual Page Search Parameters
TLS_INIT(3) Library Functions Manual TLS_INIT(3)

tls_init, tls_error, tls_config_new, tls_config_free, tls_config_parse_protocols, 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_ciphers, tls_config_set_dheparams, tls_config_set_ecdhecurve, tls_config_set_key_file, tls_config_set_key_mem, tls_config_set_protocols, tls_config_set_verify_depth, tls_config_prefer_ciphers_client, tls_config_prefer_ciphers_server, tls_config_clear_keys, tls_config_insecure_noverifycert, tls_config_insecure_noverifyname, tls_config_insecure_noverifytime, tls_config_verify, tls_config_verify_client, tls_config_verify_client_optional, tls_peer_cert_provided, tls_peer_cert_contains_name, tls_peer_cert_issuer, tls_peer_cert_subject, tls_peer_cert_hash, tls_peer_cert_notbefore, tls_peer_cert_notafter, tls_conn_version, tls_conn_cipher, tls_load_file, tls_client, tls_server, tls_configure, tls_reset, tls_free, tls_connect, tls_connect_fds, tls_connect_servername, tls_connect_socket, tls_accept_fds, tls_accept_socket, tls_handshake, tls_read, tls_write, tls_close — TLS client and server API

#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_parse_protocols(uint32_t *protocols, const char *protostr);

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_ciphers(struct tls_config *config, const char *ciphers);

int
tls_config_set_dheparams(struct tls_config *config, const char *params);

int
tls_config_set_ecdhecurve(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);

void
tls_config_set_protocols(struct tls_config *config, uint32_t protocols);

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

void
tls_config_prefer_ciphers_client(struct tls_config *config);

void
tls_config_prefer_ciphers_server(struct tls_config *config);

void
tls_config_clear_keys(struct tls_config *config);

void
tls_config_insecure_noverifycert(struct tls_config *config);

void
tls_config_insecure_noverifyname(struct tls_config *config);

void
tls_config_insecure_noverifytime(struct tls_config *config);

void
tls_config_verify(struct tls_config *config);

void
tls_config_verify_client(struct tls_config *config);

void
tls_config_verify_client_optional(struct tls_config *config);

int
tls_peer_cert_provided(struct tls *ctx);

int
tls_peer_cert_contains_name(struct tls *ctx, const char *name);

const char *
tls_peer_cert_issuer(struct tls *ctx);

const char *
tls_peer_cert_subject(struct tls *ctx);

const char *
tls_peer_cert_hash(struct tls *ctx);

time_t
tls_peer_cert_notbefore(struct tls *ctx);

time_t
tls_peer_cert_notafter(struct tls *ctx);

const char *
tls_conn_version(struct tls *ctx);

const char *
tls_conn_cipher(struct tls *ctx);

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

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);

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 *servername);

int
tls_connect_servername(struct tls *ctx, const char *host, const char *port, const char *servername);

int
tls_connect_socket(struct tls *ctx, int s, const char *servername);

int
tls_accept_fds(struct tls *tls, struct tls **cctx, int fd_read, int fd_write);

int
tls_accept_socket(struct tls *tls, struct tls **cctx, int socket);

int
tls_handshake(struct tls *ctx);

ssize_t
tls_read(struct tls *ctx, void *buf, size_t buflen);

ssize_t
tls_write(struct tls *ctx, const void *buf, size_t buflen);

int
tls_close(struct tls *ctx);

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

The () function should be called once before any function is used. It may be called more than once, but not concurrently.

Before a connection is created, a configuration must be created. The () 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 () or () functions. The context can then be configured with the function (). The same tls_config object can be used to configure multiple contexts.

A client connection is initiated after configuration by calling (). This function will create a new socket, connect to the specified host and port, and then establish a secure connection. The () function has the same behaviour, however the name to use for verification is explicitly provided, rather than being inferred from the host value. An already existing socket can be upgraded to a secure connection by calling (). Alternatively, a secure connection can be established over a pair of existing file descriptors by calling tls_connect_fds().

A server can accept a new client connection by calling () on an already established socket connection. Alternatively, a new client connection can be accepted over a pair of existing file descriptors by calling ().

The TLS handshake can be completed by calling (). Two functions are provided for input and output, () and (). Both of these functions will result in the TLS handshake being performed if it has not already completed.

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

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.

The () function parses a protocol string and returns the corresponding value via the protocols argument. This value can then be passed to the () function. The protocol string is a comma or colon separated list of keywords. Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols), default (an alias for secure), legacy (an alias for all) and secure (currently TLSv1.2 only). If a value has a negative prefix (in the form of a leading exclamation mark) then it is removed from the list of available protocols, rather than being added to it.

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

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

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

The tls_peer_cert_provided() and tls_peer_cert_contains_name() functions return 1 if the check succeeds, and 0 if it does not. Functions that return a time_t will return a time in epoch-seconds on success, and -1 on error. Functions that return a ssize_t will return a size on success, and -1 on error. All other functions that return int will return 0 on success and -1 on error. Functions that return a pointer will return NULL on error, which indicates an out of memory condition.

The tls_handshake(), tls_read(), tls_write(), and tls_close() functions have two special return values:

The underlying read file descriptor needs to be readable in order to continue.
The underlying write file descriptor needs to be writeable in order to continue.

In the case of blocking file descriptors, the same function call should be repeated immediately. In the case of non-blocking file descriptors, the same function call should be repeated when the required condition has been met.

Callers of these functions cannot rely on the value of the global errno. To prevent mishandling of error conditions, tls_handshake(), tls_read(), tls_write(), and tls_close() all explicitly clear errno.

The following example demonstrates how to handle TLS writes on a blocking file descriptor:

...
while (len > 0) {
	ssize_t ret;

	ret = tls_write(ctx, buf, len);
	if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT)
		continue;
	if (ret < 0)
		err(1, "tls_write: %s", tls_error(ctx));
	buf += ret;
	len -= ret;
}
...

The following example demonstrates how to handle TLS writes on a non-blocking file descriptor using poll(2):

...
pfd[0].fd = fd;
pfd[0].events = POLLIN|POLLOUT;
while (len > 0) {
	nready = poll(pfd, 1, 0);
	if (nready == -1)
		err(1, "poll");
	if ((pfd[0].revents & (POLLERR|POLLNVAL)))
		errx(1, "bad fd %d", pfd[0].fd);
	if ((pfd[0].revents & (pfd[0].events|POLLHUP))) {
		ssize_t ret;

		ret = tls_write(ctx, buf, len);
		if (ret == TLS_WANT_POLLIN)
			pfd[0].events = POLLIN;
		else if (ret == TLS_WANT_POLLOUT)
			pfd[0].events = POLLOUT;
		else if (ret < 0)
			err(1, "tls_write: %s", tls_error(ctx));
		else {
			buf += ret;
			len -= ret;
		}
	}
}
...

The tls_error() function may be used to retrieve a string containing more information about the most recent error.

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.

November 9, 2015 OpenBSD-5.9