diff options
Diffstat (limited to '')
| -rw-r--r-- | man/tls_load_file.3 | 371 |
1 files changed, 371 insertions, 0 deletions
diff --git a/man/tls_load_file.3 b/man/tls_load_file.3 new file mode 100644 index 0000000..d836a04 --- /dev/null +++ b/man/tls_load_file.3 @@ -0,0 +1,371 @@ +.\" $OpenBSD: tls_load_file.3,v 1.11 2018/11/29 14:24:23 tedu Exp $ +.\" +.\" Copyright (c) 2014 Ted Unangst <tedu@openbsd.org> +.\" Copyright (c) 2015 Reyk Floeter <reyk@openbsd.org> +.\" Copyright (c) 2015 Bob Beck <beck@openbsd.org> +.\" Copyright (c) 2016, 2017 Joel Sing <jsing@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: November 29 2018 $ +.Dt TLS_LOAD_FILE 3 +.Os +.Sh NAME +.Nm tls_load_file , +.Nm tls_unload_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_crl_file , +.Nm tls_config_set_crl_mem , +.Nm tls_config_set_key_file , +.Nm tls_config_set_key_mem , +.Nm tls_config_set_ocsp_staple_mem , +.Nm tls_config_set_ocsp_staple_file , +.Nm tls_config_set_keypair_file , +.Nm tls_config_set_keypair_mem , +.Nm tls_config_set_keypair_ocsp_file , +.Nm tls_config_set_keypair_ocsp_mem , +.Nm tls_config_add_keypair_file , +.Nm tls_config_add_keypair_ocsp_mem , +.Nm tls_config_add_keypair_ocsp_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 , +.Nm tls_default_ca_cert_file +.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 void +.Fo tls_unload_file +.Fa "uint8_t *buf" +.Fa "size_t len" +.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_crl_file +.Fa "struct tls_config *config" +.Fa "const char *crl_file" +.Fc +.Ft int +.Fo tls_config_set_crl_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *crl" +.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_ocsp_staple_mem +.Fa "struct tls_config *config" +.Fa "const uint8_t *staple" +.Fa "size_t len" +.Fc +.Ft int +.Fo tls_config_set_ocsp_staple_file +.Fa "struct tls_config *config" +.Fa "const char *staple_file" +.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_set_keypair_ocsp_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fa "const char *staple_file" +.Fc +.Ft int +.Fo tls_config_set_keypair_ocsp_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" +.Fa "const uint8_t *staple" +.Fa "size_t staple_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 int +.Fo tls_config_add_keypair_ocsp_file +.Fa "struct tls_config *config" +.Fa "const char *cert_file" +.Fa "const char *key_file" +.Fa "const char *staple_file" +.Fc +.Ft int +.Fo tls_config_add_keypair_ocsp_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" +.Fa "const uint8_t *staple" +.Fa "size_t staple_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" +.Ft const char * +.Fn tls_default_ca_cert_file "void" +.Sh DESCRIPTION +.Fn tls_load_file +loads a certificate or key from disk into memory to be used with +.Fn tls_config_set_ca_mem , +.Fn tls_config_set_cert_mem , +.Fn tls_config_set_crl_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_unload_file +unloads the memory that was returned from an earlier +.Fn tls_load_file +call, ensuring that the memory contents is discarded. +.Pp +.Fn tls_default_ca_cert_file +returns the path of the file that contains the default root certificates. +.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_crl_file +sets the filename used to load a file containing the +Certificate Revocation List (CRL). +.Pp +.Fn tls_config_set_crl_mem +sets the CRL 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_ocsp_staple_file +sets a DER-encoded OCSP response to be stapled during the TLS handshake from +the specified file. +.Pp +.Fn tls_config_set_ocsp_staple_mem +sets a DER-encoded OCSP response to be stapled during the TLS handshake 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_set_keypair_ocsp_file +sets the files from which the public certificate, private key, and DER-encoded +OCSP staple will be read. +.Pp +.Fn tls_config_set_keypair_ocsp_mem +directly sets the public certificate, private key, and DER-encoded OCSP staple +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_add_keypair_ocsp_file +adds an additional public certificate, private key, and DER-encoded OCSP staple +from the specified files, used as an alternative certificate for Server Name +Indication (server only). +.Pp +.Fn tls_config_add_keypair_ocsp_mem +adds an additional public certificate, private key, and DER-encoded OCSP staple +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 +.Sh HISTORY +.Fn tls_config_set_ca_file , +.Fn tls_config_set_ca_path , +.Fn tls_config_set_cert_file , +.Fn tls_config_set_cert_mem , +.Fn tls_config_set_key_file , +.Fn tls_config_set_key_mem , +and +.Fn tls_config_set_verify_depth +appeared in +.Ox 5.6 +and got their final names in +.Ox 5.7 . +.Pp +.Fn tls_load_file , +.Fn tls_config_set_ca_mem , +and +.Fn tls_config_clear_keys +appeared in +.Ox 5.7 . +.Pp +.Fn tls_config_verify_client +and +.Fn tls_config_verify_client_optional +appeared in +.Ox 5.9 . +.Pp +.Fn tls_config_set_keypair_file +and +.Fn tls_config_set_keypair_mem +appeared in +.Ox 6.0 , +and +.Fn tls_config_add_keypair_file +and +.Fn tls_config_add_keypair_mem +in +.Ox 6.1 . +.Pp +.Fn tls_config_set_crl_file +and +.Fn tls_config_set_crl_mem +appeared in +.Ox 6.2 . +.Sh AUTHORS +.An Joel Sing Aq Mt jsing@openbsd.org +with contibutions from +.An Ted Unangst Aq Mt tedu@openbsd.org +and +.An Bob Beck Aq Mt beck@openbsd.org . +.Pp +.Fn tls_load_file +and +.Fn tls_config_set_ca_mem +were written by +.An Reyk Floeter Aq Mt reyk@openbsd.org . |