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_load_file.3 | 197 +++++++++++++++++++++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 src/lib/libtls/man/tls_load_file.3 (limited to 'src/lib/libtls/man/tls_load_file.3') 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 +.\" +.\" 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 -- cgit v1.2.3-55-g6feb