.\" $OpenBSD: tls_init.3,v 1.67 2016/08/22 14:55:59 jsing 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: August 22 2016 $ .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_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_protocols , .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_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_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_accept_fds , .Nm tls_accept_socket , .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_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 "void" .Fn tls_config_set_protocols "struct tls_config *config" "uint32_t protocols" .Ft "void" .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_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 "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_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_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 . .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 . .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 may only apply to clients, to servers or to both): .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. .Em (Server) .It .Fn tls_config_set_keypair_mem adds an additional public certificate and private key from memory, used as an alternative certificate for Server Name Indication. .Em (Server) .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. .Em (Client and Server) .It .Fn tls_config_set_ca_file sets the filename used to load a file containing the root certificates. .Em (Client and Server) .It .Fn tls_config_set_ca_path sets the path (directory) which should be searched for root certificates. .Em (Client and Server) .It .Fn tls_config_set_ca_mem sets the root certificates directly from memory. .Em (Client and Server) .It .Fn tls_config_set_cert_file sets file from which the public certificate will be read. .Em (Client and server) .It .Fn tls_config_set_cert_mem sets the public certificate directly from memory. .Em (Client and server) .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. .Pp .Em (Client and server) .It .Fn tls_config_set_key_file sets the file from which the private key will be read. .Em (Client and server) .It .Fn tls_config_set_key_mem directly sets the private key from memory. .Em (Client and server) .It .Fn tls_config_set_keypair_file sets the files from which the public certificate and private key will be read. .Em (Client and server) .It .Fn tls_config_set_keypair_mem directly sets the public certificate and private key from memory. .Em (Client and server) .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. .Em (Client and server) .It .Fn tls_config_prefer_ciphers_client prefers ciphers in the client's cipher list when selecting a cipher suite. This is considered to be less secure than preferring the server's list. .Em (Server) .It .Fn tls_config_prefer_ciphers_server prefers ciphers in the server's cipher list when selecting a cipher suite. This is considered to be more secure than preferring the client's list and is the default. .Em (Server) .It .Fn tls_config_clear_keys clears any secret keys from memory. .Em (Server) .It .Fn tls_config_insecure_noverifycert disables certificate verification. Be extremely careful when using this option. .Em (Client and server) .It .Fn tls_config_insecure_noverifyname disables server name verification. Be careful when using this option. .Em (Client) .It .Fn tls_config_insecure_noverifytime disables validity checking of certificates. Be careful when using this option. .Em (Client and server) .It .Fn tls_config_verify reenables server name and certificate verification. .Em (Client) .It .Fn tls_config_verify_client enables client certificate verification, requiring the client to send a certificate. .Em (Server) .It .Fn tls_config_verify_client_optional enables client certificate verification, without requiring the client to send a certificate. .Em (Server) .El .Pp The following functions return information about a TLS connection and will only succeed after the handshake is complete (the connection information may only apply to clients, to servers or to both): .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. .Em (Server and Client) .It .Fn tls_conn_cipher returns a string corresponding to the cipher suite negotiated with the peer connected to .Ar ctx . .Em (Server and client) .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. .Em (Server) .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. .Em (Server and client) .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 . .Em (Server and client) .It .Fn tls_peer_cert_subject returns a string corresponding to the subject of the peer certificate from .Ar ctx . .Em (Server and client) .It .Fn tls_peer_cert_issuer returns a string corresponding to the issuer of the peer certificate from .Ar ctx . .Em (Server and client) .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 . .Em (Server and client) .It .Fn tls_peer_cert_notafter returns the time corresponding to the end of the validity period of the peer certificate from .Ar ctx . .Em (Server and client) .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. .Em (Client and server) .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. Functions that return a .Vt time_t will return a time in epoch-seconds on success, and -1 on error. Functions that return a .Vt ssize_t will return a size on success, and -1 on error. All other functions that return .Vt int will return 0 on success and -1 on error. Functions that return a pointer will return NULL on error, which indicates 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.