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/tls_init.3 | 885 ---------------------------------------------- 1 file changed, 885 deletions(-) delete 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 deleted file mode 100644 index 5d4be14ede..0000000000 --- a/src/lib/libtls/tls_init.3 +++ /dev/null @@ -1,885 +0,0 @@ -.\" $OpenBSD: tls_init.3,v 1.86 2017/01/24 07:57:39 jmc 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 24 2017 $ -.Dt TLS_INIT 3 -.Os -.Sh NAME -.Nm tls_init , -.Nm tls_config_error , -.Nm tls_error , -.Nm tls_config_new , -.Nm tls_config_free , -.Nm tls_config_parse_protocols , -.Nm tls_config_add_keypair_file , -.Nm tls_config_add_keypair_mem , -.Nm tls_config_add_ticket_key , -.Nm tls_config_set_alpn , -.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_ciphers , -.Nm tls_config_set_dheparams , -.Nm tls_config_set_ecdhecurve , -.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_set_ocsp_staple_mem , -.Nm tls_config_set_ocsp_staple_file , -.Nm tls_config_set_protocols , -.Nm tls_config_set_session_id , -.Nm tls_config_set_session_lifetime , -.Nm tls_config_set_verify_depth , -.Nm tls_config_prefer_ciphers_client , -.Nm tls_config_prefer_ciphers_server , -.Nm tls_config_clear_keys , -.Nm tls_config_insecure_noverifycert , -.Nm tls_config_insecure_noverifyname , -.Nm tls_config_insecure_noverifytime , -.Nm tls_config_ocsp_require_stapling , -.Nm tls_config_verify , -.Nm tls_config_verify_client , -.Nm tls_config_verify_client_optional , -.Nm tls_peer_cert_provided , -.Nm tls_peer_cert_contains_name , -.Nm tls_peer_cert_issuer , -.Nm tls_peer_cert_subject , -.Nm tls_peer_cert_hash , -.Nm tls_peer_cert_notbefore , -.Nm tls_peer_cert_notafter , -.Nm tls_ocsp_process_response , -.Nm tls_peer_ocsp_cert_status , -.Nm tls_peer_ocsp_crl_reason , -.Nm tls_peer_ocsp_next_update , -.Nm tls_peer_ocsp_response_status , -.Nm tls_peer_ocsp_result_msg , -.Nm tls_peer_ocsp_revocation_time , -.Nm tls_peer_ocsp_this_update , -.Nm tls_peer_ocsp_url , -.Nm tls_conn_alpn_selected , -.Nm tls_conn_cipher , -.Nm tls_conn_servername , -.Nm tls_conn_version , -.Nm tls_load_file , -.Nm tls_client , -.Nm tls_server , -.Nm tls_configure , -.Nm tls_reset , -.Nm tls_free , -.Nm tls_connect , -.Nm tls_connect_fds , -.Nm tls_connect_servername , -.Nm tls_connect_socket , -.Nm tls_connect_cbs , -.Nm tls_accept_fds , -.Nm tls_accept_socket , -.Nm tls_accept_cbs , -.Nm tls_handshake , -.Nm tls_read , -.Nm tls_write , -.Nm tls_close -.Nd TLS client and server API -.Sh SYNOPSIS -.In tls.h -.Ft "int" -.Fn tls_init "void" -.Ft "const char *" -.Fn tls_config_error "struct tls_config *config" -.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_parse_protocols "uint32_t *protocols" "const char *protostr" -.Ft "int" -.Fn tls_config_add_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file" -.Ft "int" -.Fn tls_config_add_keypair_mem "struct tls_config *config" "const uint8_t *cert" "size_t cert_len" "const uint8_t *key" "size_t key_len" -.Ft "int" -.Fn tls_config_add_ticket_key "struct tls_config *config" "uint32_t keyrev" "unsigned char *key" "size_t keylen" -.Ft "int" -.Fn tls_config_set_alpn "struct tls_config *config" "const char *alpn" -.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_ca_mem "struct tls_config *config" "const uint8_t *cert" "size_t len" -.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_dheparams "struct tls_config *config" "const char *params" -.Ft "int" -.Fn tls_config_set_ecdhecurve "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_keypair_file "struct tls_config *config" "const char *cert_file" "const char *key_file" -.Ft "int" -.Fn tls_config_set_keypair_mem "struct tls_config *config" "const uint8_t *cert" "size_t cert_len" "const uint8_t *key" "size_t key_len" -.Ft "int" -.Fn tls_config_set_ocsp_staple_mem "struct tls_config *config" "const char *staple" "size_t len" -.Ft "int" -.Fn tls_config_set_ocsp_staple_file "struct tls_config *config" "const char *staple_file" -.Ft "int" -.Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols" -.Ft "int" -.Fn tls_config_set_session_id "struct tls_config *config" "const unsigned char *session_id" "size_t len" -.Ft "int" -.Fn tls_config_set_session_lifetime "struct tls_config *config" "int lifetime" -.Ft "int" -.Fn tls_config_set_verify_depth "struct tls_config *config" "int verify_depth" -.Ft "void" -.Fn tls_config_prefer_ciphers_client "struct tls_config *config" -.Ft "void" -.Fn tls_config_prefer_ciphers_server "struct tls_config *config" -.Ft "void" -.Fn tls_config_clear_keys "struct tls_config *config" -.Ft "void" -.Fn tls_config_insecure_noverifycert "struct tls_config *config" -.Ft "void" -.Fn tls_config_insecure_noverifyname "struct tls_config *config" -.Ft "void" -.Fn tls_config_insecure_noverifytime "struct tls_config *config" -.Ft "void" -.Fn tls_config_ocsp_require_stapling "struct tls_config *config" -.Ft "void" -.Fn tls_config_verify "struct tls_config *config" -.Ft "void" -.Fn tls_config_verify_client "struct tls_config *config" -.Ft "void" -.Fn tls_config_verify_client_optional "struct tls_config *config" -.Ft "int" -.Fn tls_peer_cert_provided "struct tls *ctx" -.Ft "int" -.Fn tls_peer_cert_contains_name "struct tls *ctx" "const char *name" -.Ft "const char *" -.Fn tls_peer_cert_issuer "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_cert_subject "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_cert_hash "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_cert_notbefore "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_cert_notafter "struct tls *ctx" -.Ft "int" -.Fn tls_ocsp_process_response "struct tls *ctx" "const unsigned char *response" "size_t size" -.Ft "int" -.Fn tls_peer_ocsp_cert_status "struct tls *ctx" -.Ft "int" -.Fn tls_peer_ocsp_crl_reason "struct tls *ctx" -.Ft time_t -.Fn tls_peer_ocsp_next_update "struct tls *ctx" -.Ft "int" -.Fn tls_peer_ocsp_response_status "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_ocsp_result_msg "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_ocsp_revocation_time "struct tls *ctx" -.Ft "time_t" -.Fn tls_peer_ocsp_this_update "struct tls *ctx" -.Ft "const char *" -.Fn tls_peer_ocsp_url "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_alpn_selected "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_cipher "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_servername "struct tls *ctx" -.Ft "const char *" -.Fn tls_conn_version "struct tls *ctx" -.Ft "uint8_t *" -.Fn tls_load_file "const char *file" "size_t *len" "char *password" -.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 "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_fds "struct tls *ctx" "int fd_read" "int fd_write" "const char *servername" -.Ft "int" -.Fn tls_connect_servername "struct tls *ctx" "const char *host" "const char *port" "const char *servername" -.Ft "int" -.Fn tls_connect_socket "struct tls *ctx" "int s" "const char *servername" -.Ft "int" -.Fn tls_connect_cbs "struct tls *ctx" "ssize_t (*tls_read_cb)(struct tls *ctx, void *buf, size_t buflen, void *cb_arg)" "ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg)" "void *cb_arg" "const char *servername" -.Ft "int" -.Fn tls_accept_fds "struct tls *tls" "struct tls **cctx" "int fd_read" "int fd_write" -.Ft "int" -.Fn tls_accept_socket "struct tls *tls" "struct tls **cctx" "int socket" -.Ft "int" -.Fn tls_accept_cbs "struct tls *ctx" "struct tls **cctx" "ssize_t (*tls_read_cb)(struct *ctx, void *buf, size_t buflen, void *cb_arg)" "ssize_t (*tls_write_cb)(struct tls *ctx, const void *buf, size_t buflen, void *cb_arg)" "void *cb_arg" -.Ft "int" -.Fn tls_handshake "struct tls *ctx" -.Ft "ssize_t" -.Fn tls_read "struct tls *ctx" "void *buf" "size_t buflen" -.Ft "ssize_t" -.Fn tls_write "struct tls *ctx" "const void *buf" "size_t buflen" -.Ft "int" -.Fn tls_close "struct tls *ctx" -.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. -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 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 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. -The -.Fn tls_connect_servername -function has the same behaviour, however the name to use for verification is -explicitly provided, rather than being inferred from the -.Ar host -value. -An already existing socket can be upgraded to a secure connection by calling -.Fn tls_connect_socket . -Alternatively, a secure connection can be established over a pair of existing -file descriptors by calling -.Fn tls_connect_fds . -Calling -.Fn tls_connect_cbs -allows read and write callback functions to handle data transfers. -The specified cb_arg parameter is passed back to the functions, -and can contain a pointer to any caller-specified data. -.Pp -A server can accept a new client connection by calling -.Fn tls_accept_socket -on an already established socket connection. -Alternatively, a new client connection can be accepted over a pair of existing -file descriptors by calling -.Fn tls_accept_fds . -Calling -.Fn tls_accept_cbs -allows read and write callback functions to handle data transfers. -The specified cb_arg parameter is passed back to the functions, -and can contain a pointer to any caller-specified data. -.Pp -The TLS handshake can be completed by calling -.Fn tls_handshake . -Two functions are provided for input and output, -.Fn tls_read -and -.Fn tls_write . -Both of these functions will result in the TLS handshake being performed if it -has not already completed. -.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 -.Fn tls_config_parse_protocols -function parses a protocol string and returns the corresponding value via the -.Ar protocols -argument. -This value can then be passed to the -.Fn tls_config_set_protocols -function. -The protocol string is a comma or colon separated list of keywords. -Valid keywords are tlsv1.0, tlsv1.1, tlsv1.2, all (all supported protocols), -default (an alias for secure), legacy (an alias for all) and secure (currently -TLSv1.2 only). -If a value has a negative prefix (in the form of a leading exclamation mark) -then it is removed from the list of available protocols, rather than being -added to it. -.Pp -The following functions modify a configuration by setting parameters (the -configuration options apply to both clients and servers, unless noted -otherwise): -.Bl -bullet -offset four -.It -.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). -.It -.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). -.It -.Fn tls_config_add_ticket_key -adds a key used for the encryption and authentication of TLS tickets. -By default keys are generated and rotated automatically based on their lifetime. -This function should only be used to synchronise ticket encryption key across -multiple processes. -Re-adding a known key will result in an error, unless it is the most recently -added key. -.It -.Fn tls_config_set_alpn -sets the ALPN protocols that are supported. -The alpn string is a comma separated list of protocols, in order of preference. -.It -.Fn tls_config_set_ca_file -sets the filename used to load a file -containing the root certificates. -.It -.Fn tls_config_set_ca_path -sets the path (directory) which should be searched for root -certificates. -.It -.Fn tls_config_set_ca_mem -sets the root certificates directly from memory. -.It -.Fn tls_config_set_cert_file -sets file from which the public certificate will be read. -.It -.Fn tls_config_set_cert_mem -sets the public certificate directly from memory. -.It -.Fn tls_config_set_ciphers -sets the list of ciphers that may be used. -Lists of ciphers are specified by name, and the -permitted names are: -.Pp -.Bl -tag -width "insecure" -offset indent -compact -.It Dv "secure" (or alias "default") -.It Dv "compat" -.It Dv "legacy" -.It Dv "insecure" (or alias "all") -.El -.Pp -Alternatively, libssl cipher strings can be specified. -See the CIPHERS section of -.Xr openssl 1 -for further information. -.It -.Fn tls_config_set_key_file -sets the file from which the private key will be read. -.It -.Fn tls_config_set_key_mem -directly sets the private key from memory. -.It -.Fn tls_config_set_keypair_file -sets the files from which the public certificate and private key will be read. -.It -.Fn tls_config_set_keypair_mem -directly sets the public certificate and private key from memory. -.It -.Fn tls_config_set_ocsp_staple_file -sets a DER-encoded OCSP response to be stapled during the TLS handshake from -the specified file. -.It -.Fn tls_config_set_ocsp_staple_mem -sets a DER-encoded OCSP response to be stapled during the TLS handshake from -memory. -.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 -(TLSv1.0, TLSv1.1 and TLSv1.2), -.Dv TLS_PROTOCOLS_ALL -(all supported protocols) and -.Dv TLS_PROTOCOLS_DEFAULT -(TLSv1.2 only) may be used. -.It -.Fn tls_config_set_session_id -sets the session identifier that will be used by the TLS server when -sessions are enabled. -By default a random value is used. -.It -.Fn tls_config_set_session_lifetime -sets the lifetime to be used for TLS sessions. -Session support is disabled if a lifetime of zero is specified, which is the -default. -.It -.Fn tls_config_set_verify_depth -limits the number of intermediate certificates that will be followed during -certificate validation. -.It -.Fn tls_config_prefer_ciphers_client -prefers ciphers in the client's cipher list when selecting a cipher suite -(server only). -This is considered to be less secure than preferring the server's list. -.It -.Fn tls_config_prefer_ciphers_server -prefers ciphers in the server's cipher list when selecting a cipher suite -(server only). -This is considered to be more secure than preferring the client's list and is -the default. -.It -.Fn tls_config_clear_keys -clears any secret keys from memory. -.It -.Fn tls_config_insecure_noverifycert -disables certificate verification and OCSP validation. -Be extremely careful when using this option. -.It -.Fn tls_config_insecure_noverifyname -disables server name verification (client only). -Be careful when using this option. -.It -.Fn tls_config_insecure_noverifytime -disables validity checking of certificates and OCSP validation. -Be careful when using this option. -.It -.Fn tls_config_ocsp_require_stapling -requires that a valid stapled OCSP response be provided during the TLS handshake. -.It -.Fn tls_config_verify -reenables server name and certificate verification. -.It -.Fn tls_config_verify_client -enables client certificate verification, requiring the client to send -a certificate (server only). -.It -.Fn tls_config_verify_client_optional -enables client certificate verification, without requiring the client -to send a certificate (server only). -.El -.Pp -The following functions return information about a TLS connection and will only -succeed after the handshake is complete (the connection information applies -to both clients and servers, unless noted otherwise): -.Bl -bullet -offset four -.It -.Fn tls_conn_alpn_selected -returns a string that specifies the ALPN protocol selected for use with the peer -connected to -.Ar ctx . -If no protocol was selected then NULL is returned. -.It -.Fn tls_conn_cipher -returns a string corresponding to the cipher suite negotiated with the peer -connected to -.Ar ctx . -.It -.Fn tls_conn_servername -returns a string corresponding to the servername that the client connected to -.Ar ctx -requested by sending a TLS Server Name Indication extension (server only). -.It -.Fn tls_conn_version -returns a string corresponding to a TLS version negotiated with the peer -connected to -.Ar ctx . -.It -.Fn tls_peer_cert_provided -checks if the peer of -.Ar ctx -has provided a certificate. -.It -.Fn tls_peer_cert_contains_name -checks if the peer of a TLS -.Ar ctx -has provided a certificate that contains a -SAN or CN that matches -.Ar name . -.It -.Fn tls_peer_cert_subject -returns a string -corresponding to the subject of the peer certificate from -.Ar ctx . -.It -.Fn tls_peer_cert_issuer -returns a string -corresponding to the issuer of the peer certificate from -.Ar ctx . -.It -.Fn tls_peer_cert_hash -returns a string -corresponding to a hash of the raw peer certificate from -.Ar ctx -prefixed by a hash name followed by a colon. -The hash currently used is SHA256, though this -could change in the future. -The hash string for a certificate in file -.Ar mycert.crt -can be generated using the commands: -.Bd -literal -offset indent -h=$(openssl x509 -outform der -in mycert.crt | sha256) -printf "SHA256:${h}\\n" -.Ed -.It -.Fn tls_peer_cert_notbefore -returns the time corresponding to the start of the validity period of -the peer certificate from -.Ar ctx . -.It -.Fn tls_peer_cert_notafter -returns the time corresponding to the end of the validity period of -the peer certificate from -.Ar ctx . -.It -.Fn tls_ocsp_process_response -processes a raw OCSP response in -.Ar response -of size -.Ar size -to check the revocation status of the peer certificate from -.Ar ctx . -A successful return code of 0 indicates that the certificate -has not been revoked. -.It -.Fn tls_peer_ocsp_url -returns the URL for OCSP validation of the peer certificate from -.Ar ctx -.El -.Pp -The following functions return information about the peer certificate from -.Ar ctx -that was obtained by validating a stapled OCSP response during the handshake, -or via a previous call to -.Fn tls_ocsp_process_response . -.Bl -bullet -offset four -.It -.Fn tls_peer_ocsp_cert_status -returns the OCSP certificate status code as per RFC 6960 section 2.2. -.It -.Fn tls_peer_ocsp_crl_reason -returns the OCSP certificate revocation reason status code as per RFC 5280 -section 5.3.1. -.It -.Fn tls_peer_ocsp_next_update -returns the OCSP next update time. -.It -.Fn tls_peer_ocsp_response_status -returns the OCSP response status as per RFC 6960 section 2.3. -.It -.Fn tls_peer_ocsp_revocation_time -returns the OCSP revocation time. -.It -.Fn tls_peer_ocsp_this_update -returns the OCSP this update time. -.El -.Pp -The following are TLS related utility functions: -.Bl -bullet -offset four -.It -.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. -.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_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_fds -connects a client context to a pair of existing file descriptors. -.It -.Fn tls_connect_socket -connects a client context to an already established socket connection. -.It -.Fn tls_accept_fds -creates a new context suitable for reading and writing on an existing pair of -file descriptors and returns it in -.Fa *cctx . -A configured server context should be passed in -.Fa ctx . -.It -.Fn tls_accept_socket -creates a new context suitable for reading and writing on an already -established socket connection and returns it in -.Fa *cctx . -A configured server context should be passed in -.Fa ctx . -.It -.Fn tls_handshake -performs the TLS handshake. -It is only necessary to call this function if you need to guarantee that the -handshake has completed, as both -.Fn tls_read -and -.Fn tls_write -will perform the TLS handshake if necessary. -.It -.Fn tls_read -reads -.Fa buflen -bytes of data from the socket into -.Fa buf . -It returns the amount of data read. -.It -.Fn tls_write -writes -.Fa buflen -bytes of data from -.Fa buf -to the socket. -It returns the amount of data written. -.It -.Fn tls_close -closes a connection after use. -Only the TLS layer will be shut down and the caller is responsible for closing -the file descriptors, unless the connection was established using -.Fn tls_connect -or -.Fn tls_connect_servername . -.El -.Sh RETURN VALUES -The -.Fn tls_peer_cert_provided -and -.Fn tls_peer_cert_contains_name -functions return 1 if the check succeeds, and 0 if it does not. -.Pp -Functions that return a -.Vt time_t -will return a time in epoch-seconds on success, and -1 on error. -.Pp -Functions that return a -.Vt ssize_t -will return a size on success, and -1 on error. -.Pp -The -.Fn tls_peer_ocsp_response_status -function returns one of -.Ar TLS_OCSP_RESPONSE_SUCCESSFUL , -.Ar TLS_OCSP_RESPONSE_MALFORMED , -.Ar TLS_OCSP_RESPONSE_INTERNALERROR , -.Ar TLS_OCSP_RESPONSE_TRYLATER , -.Ar TLS_OCSP_RESPONSE_SIGREQUIRED , -or -.Ar TLS_OCSP_RESPONSE_UNAUTHORIZED -on success, and -1 on error. -.Pp -The -.Fn tls_peer_ocsp_cert_status -function returns one of -.Ar TLS_OCSP_CERT_GOOD , -.Ar TLS_OCSP_CERT_REVOKED , -or -.Ar TLS_OCSP_CERT_UNKNOWN -on success, and -1 on error. -.Pp -The -.Fn tls_peer_ocsp_crl_reason -function returns one of -.Ar TLS_CRL_REASON_UNSPECIFIED , -.Ar TLS_CRL_REASON_KEY_COMPROMISE , -.Ar TLS_CRL_REASON_CA_COMPROMISE , -.Ar TLS_CRL_REASON_AFFILIATION_CHANGED , -.Ar TLS_CRL_REASON_SUPERSEDED , -.Ar TLS_CRL_REASON_CESSATION_OF_OPERATION , -.Ar TLS_CRL_REASON_CERTIFICATE_HOLD , -.Ar TLS_CRL_REASON_REMOVE_FROM_CRL , -.Ar TLS_CRL_REASON_PRIVILEGE_WITHDRAWN , -or -.Ar TLS_CRL_REASON_AA_COMPROMISE -on success, and -1 on error. -.Pp -All other functions that return -.Vt int -will return 0 on success and -1 on error. -.Pp -Functions that return a pointer will return NULL on error or an -out of memory condition. -.Pp -The -.Fn tls_handshake , -.Fn tls_read , -.Fn tls_write , -and -.Fn tls_close -functions have two special return values: -.Pp -.Bl -tag -width "TLS_WANT_POLLOUT" -offset indent -compact -.It Dv TLS_WANT_POLLIN -The underlying read file descriptor needs to be readable in order to continue. -.It Dv TLS_WANT_POLLOUT -The underlying write file descriptor needs to be writeable in order to continue. -.El -.Pp -In the case of blocking file descriptors, the same function call should be -repeated immediately. -In the case of non-blocking file descriptors, the same function call should be -repeated when the required condition has been met. -.Pp -Callers of these functions cannot rely on the value of the global -.Ar errno . -To prevent mishandling of error conditions, -.Fn tls_handshake , -.Fn tls_read , -.Fn tls_write , -and -.Fn tls_close -all explicitly clear -.Ar errno . -.Sh EXAMPLES -The following example demonstrates how to handle TLS writes on a blocking -file descriptor: -.Bd -literal -offset indent -\&... -while (len > 0) { - ssize_t ret; - - ret = tls_write(ctx, buf, len); - if (ret == TLS_WANT_POLLIN || ret == TLS_WANT_POLLOUT) - continue; - if (ret < 0) - err(1, "tls_write: %s", tls_error(ctx)); - buf += ret; - len -= ret; -} -\&... -.Ed -.Pp -The following example demonstrates how to handle TLS writes on a -non-blocking file descriptor using -.Xr poll 2 : -.Bd -literal -offset indent -\&... -pfd[0].fd = fd; -pfd[0].events = POLLIN|POLLOUT; -while (len > 0) { - nready = poll(pfd, 1, 0); - if (nready == -1) - err(1, "poll"); - if ((pfd[0].revents & (POLLERR|POLLNVAL))) - errx(1, "bad fd %d", pfd[0].fd); - if ((pfd[0].revents & (pfd[0].events|POLLHUP))) { - ssize_t ret; - - ret = tls_write(ctx, buf, len); - if (ret == TLS_WANT_POLLIN) - pfd[0].events = POLLIN; - else if (ret == TLS_WANT_POLLOUT) - pfd[0].events = POLLOUT; - else if (ret < 0) - err(1, "tls_write: %s", tls_error(ctx)); - else { - buf += ret; - len -= ret; - } - } -} -\&... -.Ed -.Sh ERRORS -The -.Fn tls_config_error -and -.Fn tls_error -functions may be used to retrieve a string containing more information -about the most recent error relating to a configuration or context. -.\" .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