TLS_INIT(3) BSD Library Functions Manual TLS_INIT(3)NAME
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_clear_keys, tls_config_insecure_noverifycert,
tls_config_insecure_noverifyname, tls_config_verify, tls_load_file,
tls_client, tls_server, tls_configure, tls_reset, tls_close, tls_free,
tls_connect, tls_connect_fds, tls_connect_servername, tls_connect_socket,
tls_accept_fds, tls_accept_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_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_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_verify(struct tls_config *config);
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);
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 *servername);
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_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. It may be called more than once, but not concurrently.
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. The
tls_connect_servername() 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 tls_connect_socket(). 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
tls_accept_socket() on an already established socket connection. Alter‐
natively, a new client connection can be accepted over a pair of existing
file descriptors by calling tls_accept_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 tls_config_parse_protocols() function parses a protocol string and
returns the corresponding value via the protocols argument. This value
can then be passed to the tls_config_set_protocols() function. The pro‐
tocol string is a comma or colon separated list of keywords. Valid key‐
words are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols),
default (an alias for secure), legacy (an alias for all) and secure (cur‐
rently 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.
· 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_ca_mem() sets the root certificates directly from
memory. (Client)
· tls_config_set_cert_file() sets file from which the public cer‐
tificate 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 mem‐
ory. (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 (TLSv1.0, TLSv1.1 and
TLSv1.2), TLS_PROTOCOLS_ALL (all supported protocols) and
TLS_PROTOCOLS_DEFAULT (TLSv1.2 only) may be used. (Client and
server)
· tls_config_clear_keys() clears any secret keys from memory.
(Server)
· tls_config_insecure_noverifycert() disables certificate verifica‐
tion. Be extremely careful when using this option. (Client)
· tls_config_insecure_noverifyname() disables server name verifica‐
tion. Be careful when using this option. (Client)
· tls_config_verify() reenables server name and certificate verifi‐
cation. (Client)
· tls_load_file() loads a certificate or key from disk into memory
to be loaded with tls_config_set_ca_mem(),
tls_config_set_cert_mem() or tls_config_set_key_mem(). A private
key will be decrypted if the optional password argument is speci‐
fied. (Client and server)
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 out‐
put 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_accept_fds() creates a new context suitable for reading and
writing on an existing pair of file descriptors and returns it in
*cctx. A configured server context should be passed in ctx and
*cctx should be initialized to NULL.
· tls_accept_socket() creates a new context suitable for reading
and writing on an already established socket connection and
returns it in *cctx. A configured server context should be
passed in ctx and *cctx should be initialized to NULL.
· 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.
The tls_close(), tls_read() and tls_write() functions, along with the
tls_accept() and tls_connect() function families, have two special return
values:
TLS_READ_AGAIN A read operation is necessary to continue.
TLS_WRITE_AGAIN A write operation is necessary to continue.
There are underlying TLS engine read or write operations which may not
correspond with the name of the function called. For example, it is pos‐
sible to receive a TLS_READ_AGAIN even when calling tls_write().
While there are cases where these functions will return one or the other
or both, the best practice is to always check for both. The caller
should call the appropriate function or, in the case of the tls_close()
and the tls_accept() and tls_connect() function families, repeat the
call.
EXAMPLES
Example showing how to handle partial TLS writes.
...
while (len > 0) {
ret = tls_write(ctx, buf, len, &num_written);
if (ret == TLS_READ_AGAIN || ret == TLS_WRITE_AGAIN) {
/* retry. May use select to wait for nonblocking */
} else if (ret < 0) {
return -1;
} else {
buf += num_written;
len -= num_written;
}
}
...
ERRORS
The tls_error() function may be used to retrieve a string containing more
information about the most recent error.
HISTORY
The tls API first appeared in OpenBSD 5.6 as a response to the unneces‐
sary challenges other APIs present in order to use them safely.
BSD April 29, 2024 BSD
