From 35fdef4d614c3469f40e63e53b292de178a9e20c Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Wed, 25 Jan 2017 23:53:18 +0000 Subject: split the tls_init(3) that had grown fat to allow healthy future growth; suggested by jsing@; "i would just chuck it in" jmc@ --- src/lib/libtls/man/tls_init.3 | 126 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 126 insertions(+) create mode 100644 src/lib/libtls/man/tls_init.3 (limited to 'src/lib/libtls/man/tls_init.3') diff --git a/src/lib/libtls/man/tls_init.3 b/src/lib/libtls/man/tls_init.3 new file mode 100644 index 0000000000..af0eec3802 --- /dev/null +++ b/src/lib/libtls/man/tls_init.3 @@ -0,0 +1,126 @@ +.\" $OpenBSD: tls_init.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $ +.Dt TLS_INIT 3 +.Os +.Sh NAME +.Nm tls_init , +.Nm tls_config_new , +.Nm tls_config_free , +.Nm tls_config_error +.Nd initialize TLS client and server API +.Sh SYNOPSIS +.In tls.h +.Ft int +.Fn tls_init void +.Ft struct tls_config * +.Fn tls_config_new void +.Ft void +.Fn tls_config_free "struct tls_config *config" +.Ft const char * +.Fn tls_config_error "struct tls_config *config" +.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 initializes global data structures. +It should be called once before any other functions. +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 allocates, initializes, and returns a new default configuration +object that can be used for future connections. +Several functions exist to change the options of the configuration; see +.Xr tls_config_set_protocols 3 , +.Xr tls_load_file 3 , +.Xr tls_config_ocsp_require_stapling 3 , +and +.Xr tls_config_verify 3 . +.Pp +The +.Fn tls_config_error +function may be used to retrieve a string containing more information +about the most recent error relating to a configuration. +.Pp +A TLS connection object is created by +.Xr tls_client 3 +or +.Xr tls_server 3 +and configured with +.Xr tls_configure 3 . +.Pp +A client connection is initiated after configuration by calling +.Xr tls_connect 3 . +A server can accept a new client connection by calling +.Xr tls_accept_socket 3 +on an already established socket connection. +.Pp +Two functions are provided for input and output, +.Xr tls_read 3 +and +.Xr tls_write 3 . +Both automatically perform the +.Xr tls_handshake 3 +when needed. +.Pp +The properties of established TLS connections +can be inspected with the functions described in +.Xr tls_conn_version 3 +and +.Xr tls_ocsp_process_response 3 . +.Pp +After use, a TLS connection should be closed with +.Xr tls_close 3 +and then freed by calling +.Xr tls_free 3 . +.Pp +When no more contexts are to be created, +the configuration object should be freed by calling +.Fn tls_config_free . +.Sh RETURN VALUES +.Fn tls_init +returns 0 on success or -1 on error. +.Pp +.Fn tls_config_new +returns +.Dv NULL +on error or an out of memory condition. +.Sh SEE ALSO +.Xr tls_accept_socket 3 , +.Xr tls_client 3 , +.Xr tls_config_ocsp_require_stapling 3 , +.Xr tls_config_set_protocols 3 , +.Xr tls_config_verify 3 , +.Xr tls_conn_version 3 , +.Xr tls_connect 3 , +.Xr tls_load_file 3 , +.Xr tls_ocsp_process_response 3 , +.Xr tls_read 3 +.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