.\" $OpenBSD: tls_init.3,v 1.25 2015/07/19 17:10:23 jmc Exp $
.\"
.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 19 2015 $
.Dt TLS_INIT 3
.Os
.Sh NAME
.Nm tls_init ,
.Nm tls_error ,
.Nm tls_config_new ,
.Nm tls_config_free ,
.Nm tls_config_parse_protocols ,
.Nm tls_config_set_ca_file ,
.Nm tls_config_set_ca_path ,
.Nm tls_config_set_ca_mem ,
.Nm tls_config_set_cert_file ,
.Nm tls_config_set_cert_mem ,
.Nm tls_config_set_ciphers ,
.Nm tls_config_set_dheparams ,
.Nm tls_config_set_ecdhecurve ,
.Nm tls_config_set_key_file ,
.Nm tls_config_set_key_mem ,
.Nm tls_config_set_protocols ,
.Nm tls_config_set_verify_depth ,
.Nm tls_config_clear_keys ,
.Nm tls_config_insecure_noverifycert ,
.Nm tls_config_insecure_noverifyname ,
.Nm tls_config_verify ,
.Nm tls_load_file ,
.Nm tls_client ,
.Nm tls_server ,
.Nm tls_configure ,
.Nm tls_reset ,
.Nm tls_close ,
.Nm tls_free ,
.Nm tls_connect ,
.Nm tls_connect_fds ,
.Nm tls_connect_servername ,
.Nm tls_connect_socket ,
.Nm tls_accept_fds ,
.Nm tls_accept_socket ,
.Nm tls_read ,
.Nm tls_write
.Nd TLS client and server API
.Sh SYNOPSIS
.In tls.h
.Ft "int"
.Fn tls_init "void"
.Ft "const char *"
.Fn tls_error "struct tls *ctx"
.Ft "struct tls_config *"
.Fn tls_config_new "void"
.Ft "void"
.Fn tls_config_free "struct tls_config *config"
.Ft "int"
.Fn tls_config_parse_protocols "uint32_t *protocols" "const char *protostr"
.Ft "int"
.Fn tls_config_set_ca_file "struct tls_config *config" "const char *ca_file"
.Ft "int"
.Fn tls_config_set_ca_path "struct tls_config *config" "const char *ca_path"
.Ft "int"
.Fn tls_config_set_ca_mem "struct tls_config *config" "const uint8_t *cert" "size_t len"
.Ft "int"
.Fn tls_config_set_cert_file "struct tls_config *config" "const char *cert_file"
.Ft "int"
.Fn tls_config_set_cert_mem  "struct tls_config *config" "const uint8_t *cert" "size_t len"
.Ft "int"
.Fn tls_config_set_ciphers "struct tls_config *config" "const char *ciphers"
.Ft "int"
.Fn tls_config_set_dheparams "struct tls_config *config" "const char *params"
.Ft "int"
.Fn tls_config_set_ecdhecurve "struct tls_config *config" "const char *name"
.Ft "int"
.Fn tls_config_set_key_file "struct tls_config *config" "const char *key_file"
.Ft "int"
.Fn tls_config_set_key_mem "struct tls_config *config" "const uint8_t *key" "size_t len"
.Ft "void"
.Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols"
.Ft "void"
.Fn tls_config_set_verify_depth "struct tls_config *config" "int verify_depth"
.Ft "void"
.Fn tls_config_clear_keys "struct tls_config *config"
.Ft "void"
.Fn tls_config_insecure_noverifycert "struct tls_config *config"
.Ft "void"
.Fn tls_config_insecure_noverifyname "struct tls_config *config"
.Ft "void"
.Fn tls_config_verify "struct tls_config *config"
.Ft "uint8_t *"
.Fn tls_load_file "const char *file" "size_t *len" "char *password"
.Ft "struct tls *"
.Fn tls_client void
.Ft "struct tls *"
.Fn tls_server void
.Ft "int"
.Fn tls_configure "struct tls *ctx" "struct tls_config *config"
.Ft "void"
.Fn tls_reset "struct tls *ctx"
.Ft "int"
.Fn tls_close "struct tls *ctx"
.Ft "void"
.Fn tls_free "struct tls *ctx"
.Ft "int"
.Fn tls_connect "struct tls *ctx" "const char *host" "const char *port"
.Ft "int"
.Fn tls_connect_fds "struct tls *ctx" "int fd_read" "int fd_write" "const char *servername"
.Fn tls_connect_servername "struct tls *ctx" "const char *host" "const char *port" "const char *servername"
.Ft "int"
.Fn tls_connect_socket "struct tls *ctx" "int s" "const char *servername"
.Ft "int"
.Fn tls_accept_fds "struct tls *tls" "struct tls **cctx" "int fd_read" "int fd_write"
.Ft "int"
.Fn tls_accept_socket "struct tls *tls" "struct tls **cctx" "int socket"
.Ft "int"
.Fn tls_read "struct tls *ctx" "void *buf" "size_t buflen" "size_t *outlen"
.Ft "int"
.Fn tls_write "struct tls *ctx" "const void *buf" "size_t buflen" "size_t *outlen"
.Sh DESCRIPTION
The
.Nm tls
family of functions establishes a secure communications channel
using the TLS socket protocol.
Both clients and servers are supported.
.Pp
The
.Fn tls_init
function should be called once before any function is used.
It may be called more than once, but not concurrently.
.Pp
Before a connection is created, a configuration must be created.
The
.Fn 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.
.Pp
A
.Em tls
connection is represented as a
.Em context .
A new
.Em context
is created by either the
.Fn tls_client
or
.Fn tls_server
functions.
The context can then be configured with the function
.Fn tls_configure .
The same
.Em tls_config
object can be used to configure multiple contexts.
.Pp
A client connection is initiated after configuration by calling
.Fn tls_connect .
This function will create a new socket, connect to the specified host and
port, and then establish a secure connection.
The
.Fn tls_connect_servername
function has the same behaviour, however the name to use for verification is
explicitly provided, rather than being inferred from the
.Ar host
value.
An already existing socket can be upgraded to a secure connection by calling
.Fn tls_connect_socket .
Alternatively, a secure connection can be established over a pair of existing
file descriptors by calling
.Fn tls_connect_fds .
.Pp
A server can accept a new client connection by calling
.Fn 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
.Fn tls_accept_fds .
.Pp
Two functions are provided for input and output,
.Fn tls_read
and
.Fn tls_write .
.Pp
After use, a tls
.Em context
should be closed with
.Fn tls_close ,
and then freed by calling
.Fn tls_free .
When no more contexts are to be created, the
.Em tls_config
object should be freed by calling
.Fn tls_config_free .
.Sh FUNCTIONS
The
.Fn tls_init
function initializes global data structures.
It should be called once before any other functions.
.Pp
The following functions create and free configuration objects.
.Bl -bullet -offset four
.It
.Fn tls_config_new
allocates a new default configuration object.
.It
.Fn tls_config_free
frees a configuration object.
.El
.Pp
The
.Fn tls_config_parse_protocols
function parses a protocol string and returns the corresponding value via the
.Ar protocols
argument.
This value can then be passed to the
.Fn 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.
.Pp
The following functions modify a configuration by setting parameters.
Configuration options may apply to only clients or only servers or both.
.Bl -bullet -offset four
.It
.Fn tls_config_set_ca_file
sets the filename used to load a file
containing the root certificates.
.Em (Client)
.It
.Fn tls_config_set_ca_path
sets the path (directory) which should be searched for root
certificates.
.Em (Client)
.It
.Fn tls_config_set_ca_mem
sets the root certificates directly from memory.
.Em (Client)
.It
.Fn tls_config_set_cert_file
sets file from which the public certificate will be read.
.Em (Client and server)
.It
.Fn tls_config_set_cert_mem
sets the public certificate directly from memory.
.Em (Client and server)
.It
.Fn tls_config_set_ciphers
sets the list of ciphers that may be used.
.Em (Client and server)
.It
.Fn tls_config_set_key_file
sets the file from which the private key will be read.
.Em (Server)
.It
.Fn tls_config_set_key_mem
directly sets the private key from memory.
.Em (Server)
.It
.Fn tls_config_set_protocols
sets which versions of the protocol may be used.
Possible values are the bitwise OR of:
.Pp
.Bl -tag -width "TLS_PROTOCOL_TLSv1_2" -offset indent -compact
.It Dv TLS_PROTOCOL_TLSv1_0
.It Dv TLS_PROTOCOL_TLSv1_1
.It Dv TLS_PROTOCOL_TLSv1_2
.El
.Pp
Additionally, the values
.Dv TLS_PROTOCOL_TLSv1
(TLSv1.0, TLSv1.1 and TLSv1.2),
.Dv TLS_PROTOCOLS_ALL
(all supported protocols) and
.Dv TLS_PROTOCOLS_DEFAULT
(TLSv1.2 only) may be used.
.Em (Client and server)
.It
.Fn tls_config_clear_keys
clears any secret keys from memory.
.Em (Server)
.It
.Fn tls_config_insecure_noverifycert
disables certificate verification.
Be extremely careful when using this option.
.Em (Client)
.It
.Fn tls_config_insecure_noverifyname
disables server name verification.
Be careful when using this option.
.Em (Client)
.It
.Fn tls_config_verify
reenables server name and certificate verification.
.Em (Client)
.It
.Fn tls_load_file
loads a certificate or key from disk into memory to be loaded with
.Fn tls_config_set_ca_mem ,
.Fn tls_config_set_cert_mem
or
.Fn tls_config_set_key_mem .
A private key will be decrypted if the optional
.Ar password
argument is specified.
.Em (Client and server)
.El
.Pp
The following functions create, prepare, and free a connection context.
.Bl -bullet -offset four
.It
.Fn tls_client
creates a new tls context for client connections.
.It
.Fn tls_server
creates a new tls context for server connections.
.It
.Fn tls_configure
readies a tls context for use by applying the configuration
options.
.It
.Fn tls_close
closes a connection after use.
If the connection was established using
.Fn tls_connect_fds ,
only the TLS layer will be closed and it is the caller's responsibility to close
the file descriptors.
.It
.Fn tls_free
frees a tls context after use.
.El
.Pp
The following functions initiate a connection and perform input and output
operations.
.Bl -bullet -offset four
.It
.Fn tls_connect
connects a client context to the server named by
.Fa host .
The
.Fa port
may be numeric or a service name.
If it is NULL then a host of the format "hostname:port" is permitted.
.It
.Fn tls_connect_fds
connects a client context to a pair of existing file descriptors.
.It
.Fn tls_connect_socket
connects a client context to an already established socket connection.
.It
.Fn tls_accept_fds
creates a new context suitable for reading and writing on an existing pair of
file descriptors and returns it in
.Fa *cctx .
A configured server context should be passed in
.Fa ctx
and
.Fa *cctx
should be initialized to NULL.
.It
.Fn tls_accept_socket
creates a new context suitable for reading and writing on an already
established socket connection and returns it in
.Fa *cctx .
A configured server context should be passed in
.Fa ctx
and
.Fa *cctx
should be initialized to NULL.
.It
.Fn tls_read
reads
.Fa buflen
bytes of data from the socket into
.Fa buf .
The amount of data read is returned in
.Fa outlen .
.It
.Fn tls_write
writes
.Fa buflen
bytes of data from
.Fa buf
to the socket.
The amount of data written is returned in
.Fa outlen .
.El
.Sh RETURN VALUES
Functions that return
.Vt int
will return 0 on success and -1 on error.
Functions that return a pointer will return NULL on error.
.Pp
The
.Fn tls_close ,
.Fn tls_read
and
.Fn tls_write
functions, along with the
.Fn tls_accept
and
.Fn tls_connect
function families, have two special return values:
.Pp
.Bl -tag -width "TLS_WRITE_AGAIN" -offset indent -compact
.It Dv TLS_READ_AGAIN
A read operation is necessary to continue.
.It Dv TLS_WRITE_AGAIN
A write operation is necessary to continue.
.El
.Pp
There are underlying TLS engine read or write operations which may
not correspond with the name of the function called.
For example, it is possible to receive a
.Dv TLS_READ_AGAIN
even when calling
.Fn tls_write .
.Pp
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
.Fn tls_close
and the
.Fn tls_accept
and
.Fn tls_connect
function families, repeat the call.
.Sh EXAMPLES
Example showing how to handle partial TLS writes.
.Bd -literal -offset indent
\&...
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;
	}
}
\&...
.Ed
.Sh ERRORS
The
.Fn tls_error
function may be used to retrieve a string containing more information
about the most recent error.
.\" .Sh SEE ALSO
.Sh HISTORY
The
.Nm tls
API first appeared in
.Ox 5.6
as a response to the unnecessary challenges other APIs present in
order to use them safely.