From cd85e00508e178758948e7a759609d0f1e7764df Mon Sep 17 00:00:00 2001 From: jsing <> Date: Fri, 31 Oct 2014 13:46:17 +0000 Subject: Rename libressl to libtls to avoid confusion and to make it easier to distinguish between LibreSSL (the project) and libressl (the library). Discussed with many. --- src/lib/libtls/tls_init.3 | 316 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 316 insertions(+) create mode 100644 src/lib/libtls/tls_init.3 (limited to 'src/lib/libtls/tls_init.3') 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 +.\" +.\" 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. -- cgit v1.2.3-55-g6feb