split the tls_init(3) that had grown fat to allow healthy future growth;

suggested by jsing@; "i would just chuck it in" jmc@

1 files changed, 197 insertions, 0 deletions

diff --git a/src/lib/libtls/man/tls_load_file.3 b/src/lib/libtls/man/tls_load_file.3
new file mode 100644
index 0000000000..2b2f01a8a9
--- /dev/null
+++ b/src/lib/libtls/man/tls_load_file.3
@@ -0,0 +1,197 @@
+.\" $OpenBSD: tls_load_file.3,v 1.1 2017/01/25 23:53:18 schwarze 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: January 25 2017 $
+.Dt TLS_LOAD_FILE 3
+.Os
+.Sh NAME
+.Nm tls_load_file ,
+.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_key_file ,
+.Nm tls_config_set_key_mem ,
+.Nm tls_config_set_keypair_file ,
+.Nm tls_config_set_keypair_mem ,
+.Nm tls_config_add_keypair_file ,
+.Nm tls_config_add_keypair_mem ,
+.Nm tls_config_clear_keys ,
+.Nm tls_config_set_verify_depth ,
+.Nm tls_config_verify_client ,
+.Nm tls_config_verify_client_optional
+.Nd TLS certificate and key configuration
+.Sh SYNOPSIS
+.In tls.h
+.Ft uint8_t *
+.Fo tls_load_file
+.Fa "const char *file"
+.Fa "size_t *len"
+.Fa "char *password"
+.Fc
+.Ft int
+.Fo tls_config_set_ca_file
+.Fa "struct tls_config *config"
+.Fa "const char *ca_file"
+.Fc
+.Ft int
+.Fo tls_config_set_ca_path
+.Fa "struct tls_config *config"
+.Fa "const char *ca_path"
+.Fc
+.Ft int
+.Fo tls_config_set_ca_mem
+.Fa "struct tls_config *config"
+.Fa "const uint8_t *cert"
+.Fa "size_t len"
+.Fc
+.Ft int
+.Fo tls_config_set_cert_file
+.Fa "struct tls_config *config"
+.Fa "const char *cert_file"
+.Fc
+.Ft int
+.Fo tls_config_set_cert_mem
+.Fa "struct tls_config *config"
+.Fa "const uint8_t *cert"
+.Fa "size_t len"
+.Fc
+.Ft int
+.Fo tls_config_set_key_file
+.Fa "struct tls_config *config"
+.Fa "const char *key_file"
+.Fc
+.Ft int
+.Fo tls_config_set_key_mem
+.Fa "struct tls_config *config"
+.Fa "const uint8_t *key"
+.Fa "size_t len"
+.Fc
+.Ft int
+.Fo tls_config_set_keypair_file
+.Fa "struct tls_config *config"
+.Fa "const char *cert_file"
+.Fa "const char *key_file"
+.Fc
+.Ft int
+.Fo tls_config_set_keypair_mem
+.Fa "struct tls_config *config"
+.Fa "const uint8_t *cert"
+.Fa "size_t cert_len"
+.Fa "const uint8_t *key"
+.Fa "size_t key_len"
+.Fc
+.Ft int
+.Fo tls_config_add_keypair_file
+.Fa "struct tls_config *config"
+.Fa "const char *cert_file"
+.Fa "const char *key_file"
+.Fc
+.Ft int
+.Fo tls_config_add_keypair_mem
+.Fa "struct tls_config *config"
+.Fa "const uint8_t *cert"
+.Fa "size_t cert_len"
+.Fa "const uint8_t *key"
+.Fa "size_t key_len"
+.Fc
+.Ft void
+.Fn tls_config_clear_keys "struct tls_config *config"
+.Ft int
+.Fo tls_config_set_verify_depth
+.Fa "struct tls_config *config"
+.Fa "int verify_depth"
+.Fc
+.Ft void
+.Fn tls_config_verify_client "struct tls_config *config"
+.Ft void
+.Fn tls_config_verify_client_optional "struct tls_config *config"
+.Sh DESCRIPTION
+.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.
+.Pp
+.Fn tls_config_set_ca_file
+sets the filename used to load a file
+containing the root certificates.
+.Pp
+.Fn tls_config_set_ca_path
+sets the path (directory) which should be searched for root
+certificates.
+.Pp
+.Fn tls_config_set_ca_mem
+sets the root certificates directly from memory.
+.Pp
+.Fn tls_config_set_cert_file
+sets file from which the public certificate will be read.
+.Pp
+.Fn tls_config_set_cert_mem
+sets the public certificate directly from memory.
+.Pp
+.Fn tls_config_set_key_file
+sets the file from which the private key will be read.
+.Pp
+.Fn tls_config_set_key_mem
+directly sets the private key from memory.
+.Pp
+.Fn tls_config_set_keypair_file
+sets the files from which the public certificate and private key will be read.
+.Pp
+.Fn tls_config_set_keypair_mem
+directly sets the public certificate and private key from memory.
+.Pp
+.Fn tls_config_add_keypair_file
+adds an additional public certificate and private key from the specified files,
+used as an alternative certificate for Server Name Indication (server only).
+.Pp
+.Fn tls_config_add_keypair_mem
+adds an additional public certificate and private key from memory,
+used as an alternative certificate for Server Name Indication (server only).
+.Pp
+.Fn tls_config_clear_keys
+clears any secret keys from memory.
+.Pp
+.Fn tls_config_set_verify_depth
+limits the number of intermediate certificates that will be followed during
+certificate validation.
+.Pp
+.Fn tls_config_verify_client
+enables client certificate verification, requiring the client to send
+a certificate (server only).
+.Pp
+.Fn tls_config_verify_client_optional
+enables client certificate verification, without requiring the client
+to send a certificate (server only).
+.Sh RETURN VALUES
+.Fn tls_load_file
+returns
+.Dv NULL
+on error or an out of memory condition.
+.Pp
+The other functions return 0 on success or -1 on error.
+.Sh SEE ALSO
+.Xr tls_config_ocsp_require_stapling 3 ,
+.Xr tls_config_set_protocols 3 ,
+.Xr tls_config_set_session_id 3 ,
+.Xr tls_configure 3 ,
+.Xr tls_init 3