1 files changed, 316 insertions, 0 deletions

diff --git a/src/lib/libtls/tls_init.3 b/src/lib/libtls/tls_init.3
new file mode 100644
index 0000000000..faa9b99539
--- /dev/null
+++ b/src/lib/libtls/tls_init.3
@@ -0,0 +1,316 @@
+.\" $OpenBSD: tls_init.3,v 1.1 2014/10/31 13:46:17 jsing 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: October 31 2014 $
+.Dt TLS 3
+.Os
+.Sh NAME
+.Nm tls_init ,
+.Nm tls_error ,
+.Nm tls_config_new ,
+.Nm tls_config_free ,
+.Nm tls_config_set_ca_file ,
+.Nm tls_config_set_ca_path ,
+.Nm tls_config_set_cert_file ,
+.Nm tls_config_set_cert_mem ,
+.Nm tls_config_set_ciphers ,
+.Nm tls_config_set_ecdhcurve ,
+.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_noverifyhost ,
+.Nm tls_config_insecure_noverifycert ,
+.Nm tls_config_verify ,
+.Nm tls_client ,
+.Nm tls_server ,
+.Nm tls_configure ,
+.Nm tls_reset ,
+.Nm tls_close ,
+.Nm tls_free ,
+.Nm tls_connect ,
+.Nm tls_connect_socket ,
+.Nm tls_read ,
+.Nm tls_write ,
+.Nd tls 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_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_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_ecdhcurve "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 "int"
+.Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols"
+.Ft "int"
+.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_noverifyhost "struct tls_config *config"
+.Ft "void"
+.Fn tls_config_insecure_noverifycert "struct tls_config *config"
+.Ft "void"
+.Fn tls_config_verify "struct tls_config *config"
+.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_socket "struct tls *ctx" "int s" "const char *hostname"
+.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"
+.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.
+.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.
+An already existing socket can be upgraded to a secure connection by calling
+.Fn tls_connect_socket .
+.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 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_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
+(all TLS versions) and
+.Dv TLS_PROTOCOLS_DEFAULT
+(currently all TLS versions) 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_noverifyhost
+disables hostname verification.
+Be careful when using this option.
+.Em (Client)
+.It
+.Fn tls_config_insecure_noverifycert
+disables certificate verification.
+Be extremely careful when using this option.
+.Em (Client)
+.It
+.Fn tls_config_verify
+reenables hostname and certificate verification.
+.Em (Client)
+.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.
+.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_socket
+connects a client context to an already established socket connection.
+.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.
+.\" .Sh ERRORS
+.\" .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.