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_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
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_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);
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. Alternatively, a new client
connection can be accepted over a pair of existing file descriptors by
calling
tls_accept_fds
().
The TLS handshake can be completed by calling
tls_handshake
().
Two functions are provided for input and output,
tls_read
()
and
tls_write
().
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
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 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.
tls_config_set_ca_file
() sets the filename used to load a file containing the root certificates. (Client and Server)tls_config_set_ca_path
() sets the path (directory) which should be searched for root certificates. (Client and Server)tls_config_set_ca_mem
() sets the root certificates directly from memory. (Client and Server)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. Lists of ciphers are specified by name, and the permitted names are:(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:Additionally, the values
TLS_PROTOCOL_TLSv1
(TLSv1.0, TLSv1.1 and TLSv1.2),TLS_PROTOCOLS_ALL
(all supported protocols) andTLS_PROTOCOLS_DEFAULT
(TLSv1.2 only) may be used. (Client and server)tls_config_prefer_ciphers_client
() prefers ciphers in the client's cipher list when selecting a cipher suite. This is considered to be less secure than preferring the server's list. (Server)tls_config_prefer_ciphers_server
() prefers ciphers in the server's cipher list when selecting a cipher suite. This is considered to be more secure than preferring the client's list and is the default. (Server)tls_config_clear_keys
() clears any secret keys from memory. (Server)tls_config_insecure_noverifycert
() disables certificate verification. Be extremely careful when using this option. (Client and server)tls_config_insecure_noverifyname
() disables server name verification. Be careful when using this option. (Client)tls_config_insecure_noverifytime
() disables validity checking of certificates. Be careful when using this option. (Client and server)tls_config_verify
() reenables server name and certificate verification. (Client)tls_config_verify_client
() enables client certificate verification, requiring the client to send a certificate. (Server)tls_config_verify_client_optional
() enables client certificate verification, without requiring the client to send a certificate. (Server)tls_peer_cert_provided
() checks if the peer of ctx has provided a certificate.tls_peer_cert_provided
() can only succeed after the handshake is complete. (Server and client)tls_peer_cert_contains_name
() checks if the peer of a TLS ctx has povided a certificate that contains a SAN or CN that matches name.tls_peer_cert_contains_name
() can only succeed after the handshake is complete. (Server and client)tls_peer_cert_subject
() returns a string corresponding to the subject of the peer certificate from ctx.tls_peer_cert_subject
() will only succeed after the handshake is complete. (Server and client)tls_peer_cert_issuer
() returns a string corresponding to the issuer of the peer certificate from ctx.tls_peer_cert_issuer
() will only succeed after the handshake is complete. (Server and client)tls_peer_cert_hash
() returns a string corresponding to a hash of the raw peer certificate from ctx prefixed by a hash name followed by a colon. The hash currently used is SHA256, though this could change in the future. The hash string for a certificate in file mycert.crt can be generated using the commands:h=$(openssl x509 -outform der -in mycert.crt | sha256) printf "SHA256:${h}\n"
tls_peer_cert_notbefore
() returns the time corresponding to the start of the validity period of the peer certificate from ctx.tls_peer_cert_notbefore
() will only succeed after the handshake is complete. (Server and client)tls_peer_cert_notafter
() returns the time corresponding to the end of the validity period of the peer certificate from ctx.tls_peer_cert_notafter
() will only succeed after the handshake is complete. (Server and client)tls_conn_version
() returns a string corresponding to a TLS version negotiated with the peer connected to ctx.tls_conn_version
() will only succeed after the handshake is complete.tls_conn_cipher
() returns a string corresponding to a the cipher suite negotated with the peer connected to ctx.tls_conn_cipher
() will only succeed after the handshake is complete. (Server and client)tls_load_file
() loads a certificate or key from disk into memory to be loaded withtls_config_set_ca_mem
(),tls_config_set_cert_mem
() ortls_config_set_key_mem
(). A private key will be decrypted if the optional password argument is specified. (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_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_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.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.tls_handshake
() performs the TLS handshake. It is only necessary to call this function if you need to guarantee that the handshake has completed, as bothtls_read
() andtls_write
() will perform the TLS handshake if necessary.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.tls_close
() closes a connection after use. Only the TLS layer will be shut down and the caller is responsible for closing the file descriptors, unless the connection was established usingtls_connect
() ortls_connect_servername
().
RETURN VALUES
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:
TLS_WANT_POLLIN
- The underlying read file descriptor needs to be readable in order to continue.
TLS_WANT_POLLOUT
- 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.
EXAMPLES
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; } } } ...
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 unnecessary
challenges other APIs present in order to use them safely.