From bdb38fdeb4183371b8ad8669c2821526133c39c8 Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sat, 3 Dec 2016 01:05:40 +0000 Subject: s6-tls*: small bugfixes. Add documentation. --- INSTALL | 30 ++- doc/index.html | 16 +- doc/libsbearssl/index.html | 548 ++++++++++++++++++++++++++++++++++++++++++ doc/libstls/index.html | 127 ++++++++++ doc/s6-tlsc.html | 268 +++++++++++++++++++++ doc/s6-tlsclient.html | 168 +++++++++++++ doc/s6-tlsd.html | 280 +++++++++++++++++++++ doc/s6-tlsserver.html | 216 +++++++++++++++++ doc/upgrade.html | 2 +- src/conn-tools/s6-tlsserver.c | 12 +- src/sbearssl/sbearssl_run.c | 7 +- src/stls/stls_run.c | 5 +- src/stls/stls_s6tlsc.c | 2 +- 13 files changed, 1658 insertions(+), 23 deletions(-) create mode 100644 doc/libsbearssl/index.html create mode 100644 doc/libstls/index.html create mode 100644 doc/s6-tlsc.html create mode 100644 doc/s6-tlsclient.html create mode 100644 doc/s6-tlsd.html create mode 100644 doc/s6-tlsserver.html diff --git a/INSTALL b/INSTALL index 87e065a..d12dfc0 100644 --- a/INSTALL +++ b/INSTALL @@ -177,16 +177,40 @@ source tree if parallel builds are needed. * SSL support ----------- - s6-networking implements UCSPI tools for TLS1.2 connections: s6-tlsclient, + s6-networking implements UCSPI tools for SSL/TLS connections: s6-tlsclient, s6-tlsserver, s6-tlsc and s6-tlsd. Those are built if you give the --enable-ssl= flag to configure. There are two supported values for : libressl (in which case the tools will be built against libtls) and bearssl (in which case the tools will be built against libbearssl). You should install the relevant header and library -files for your chosen implementation before building a SSL-enabled -s6-networking. +files for your chosen implementation, be it LibreSSL or BearSSL, before +building a SSL-enabled s6-networking. + If your SSL headers and library files are not installed in /usr/include and /usr/lib, you can use the --with-ssl-path=DIR configure option: headers will be searched in DIR/include and libraries will be searched in DIR/lib. For more complex setups, use the generic --with-include and --with-dir configure options. + + If you choose --enable-ssl=bearssl, then s6-networking will build a +"libsbearssl" support library, which s6-tlsc and s6-tlsd will be linked +against. This support library depends on libbearssl interfaces. + + If you choose --enable-ssl=libressl, then s6-networking will build +a "libstls" support library, which s6-tlsc and s6-tlsd will be linked +against. This support library depends on libtls interfaces, but not +on libssl or libcrypto interfaces - so it is possible to use alternative +implementations of the libtls API. + + If your SSL implementation library needs nonstandard -l options to link +against it, you can override the CRYPTO_LIB make variable. +By default, CRYPTO_LIB is "-lbearssl" when building against BearSSL, +and "-ltls -lssl -lcrypto" when building against LibreSSL. + + As of 2016-12-02, please note that BearSSL is experimental and not +considered production-ready by its author yet. Nevertheless, it's an +incredibly promising library with high-quality interfaces and likely +high-quality implementation. When statically linked against BearSSL, +the s6-tlsc and s6-tlsd binaries are 1/10th the size of what they are +when statically linked against LibreSSL, with a smaller RAM footprint +too. diff --git a/doc/index.html b/doc/index.html index 8ad4264..9ba1daf 100644 --- a/doc/index.html +++ b/doc/index.html @@ -24,6 +24,8 @@ It includes command-line client and server management, TCP access control, privilege escalation across UNIX domain sockets, IDENT protocol management and clock synchronization. +Optionally, it also includes command-line TLS/SSL tools for +secure communications.

@@ -53,9 +55,9 @@ library. 2.1.0.0 or later. It's a build-time requirement. It's also a run-time requirement if you link against the shared version of the s6-dns libraries. -

If you want to build the TLS tools: +

If you want to build the TLS/SSL tools:

Either LibreSSL version 2.5.0 +
Either LibreSSL version 2.4.4 or later
Or BearSSL version 0.1 or later. THIS IS EXPERIMENTAL.
The s6-tcpserver6d program

UCSPI tools for TLS 1.2 over TCP

UCSPI tools for SSL/TLS over TCP

The s6-tlsclient program

Libraries

The s6net library, containing:
The ident library interface
The stls library
The sbearssl library
The s6net library, containing: +
- The ident library interface

s6-networking: the sbearssl library interface

+s6-networking
+Software
+skarnet.org +

The `sbearssl` library interface

General information

+ libsbearssl is a support library for the +s6-tlsc and +s6-tlsd executables when they're built +against the BearSSL +backend. Among other things, it offers interfaces to read private +keys and certificates from a Unix filesystem, which BearSSL does +not provide on its own. +

Compiling

Make sure the s6-networking headers, as well as the skalibs headers, +and the bearssl.h header, are visible in your header search path.
Use #include <s6-networking/sbearssl.h>

Linking

Make sure the s6-networking libraries, as well as the skalibs +libraries, and the BearSSL libraries, are visible in your library search path.
Link against -lsbearssl, -lskarnet, -lbearssl, +`cat $sysdeps/socket.lib`, `cat $sysdeps/spawn.lib`, and +`cat $sysdeps/tainnow.lib`, where $sysdeps is your skalibs +sysdeps directory.

Programming

General concepts

+ BearSSL provides engines +to decode PEM objects and X.509 certificates, and to run a +TLS/SSL connection. However, it does not store such objects: +it never allocates memory, and does not interact with the +filesystem. sbearssl provides functions to +address this. +

+ When reading an object into memory, sbearssl stores all +the bytes of the object in a +stralloc, +and the sbearssl_* structures contain indices of bytes in that +stralloc. That allows the structures to remain valid even when the stralloc +contents get reallocated and move to some other place in the heap. After +you have finished adding data to the stralloc and are sure its contents +will not move again, you can use the +sbearssl_*_to functions to convert sbearssl_* structures +to the corresponding br_* structures (native BearSSL), which +contain pointers to memory. +

Private keys (typically for servers)

+ BearSSL handles two types of private keys: RSA keys and +EC keys (i.e. points on an elliptic curve). sbearssl +adds some generic functions to handle keys no matter their +type. +

`int sbearssl_rsa_skey_from (sbearssl_rsa_skey l, br_rsa_private_key const k, stralloc *sa)`

+ Converts the RSA private key from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_rsa_skey_to (sbearssl_rsa_skey const l, br_rsa_private_key k, char *s)`

+ Converts the RSA private key from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_ec_skey_from (sbearssl_ec_skey l, br_ec_private_key const k, stralloc *sa)`

+ Converts the EC private key from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_ec_skey_to (sbearssl_ec_skey const l, br_ec_private_key k, char *s)`

+ Converts the EC private key from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_skey_from (sbearssl_skey l, br_skey const k, stralloc *sa)`

+ Converts the private key from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_skey_to (sbearssl_skey const l, br_skey k, char *s)`

+ Converts the private key from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_skey_readfile (char const fn, sbearssl_skey key, stralloc *sa)`

+ Reads a private key from the file named fn and stores it +in sbearssl format into the structure in *key, +the bytes of the key being added to the stralloc in *sa. +

+The private key in fn can be either DER-encoded (binary format) +or PEM-encoded (text format). +

+ The function returns 0 on success. It returns a negative value in +case of a system error, in which case errno identifies the +error. It returns a positive value in case of an error returned by +a BearSSL decoder, in which case an appropriate message can be +obtained with the sbearssl_error_str() function. +

Public keys

+ BearSSL handles two types of public keys: RSA keys and +EC keys (i.e. points on an elliptic curve). sbearssl +adds some generic functions to handle keys no matter their +type. +

+ You normally should not handle public keys directly; +you should handle x509 certificate chains instead. +

`int sbearssl_rsa_pkey_from (sbearssl_rsa_pkey l, br_rsa_public_key const k, stralloc *sa)`

+ Converts the RSA public key from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_rsa_pkey_to (sbearssl_rsa_pkey const l, br_rsa_public_key k, char *s)`

+ Converts the RSA public key from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_ec_pkey_from (sbearssl_ec_skey l, br_ec_public_key const k, stralloc *sa)`

+ Converts the EC public key from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_ec_pkey_to (sbearssl_ec_pkey const l, br_ec_public_key k, char *s)`

+ Converts the EC public key from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_pkey_from (sbearssl_pkey l, br_x509_pkey const k, stralloc *sa)`

+ Converts the public key from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_pkey_to (sbearssl_pkey const l, br_x509_pkey k, char *s)`

+ Converts the public key from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

Generic PEM objects

+ You normally should not have to call these functions +directly. Instead, you should use the higher-level functions for +private keys, X509 certificate chains and trust anchors, which +will perform the PEM decoding for you. +

`int sbearssl_pem_decode_from_buffer (buffer b, genalloc list, stralloc *sa)`

+ Decodes a PEM object, reading from the +buffer +in *b. The decoded bytes are appended to *sa. +list points to a +genalloc +containing objects of type sbearssl_pemobject. +One sbearssl_pemobject is appended to the genalloc per PEM entity +decoded from the byte stream read from the buffer. +

`int sbearssl_pem_decode_from_string (char const s, size_t len, genalloc list, stralloc *sa)`

+ Decodes a PEM object from the len bytes pointed to by s. +The decoded bytes are appended to *sa. +list points to a +genalloc +containing objects of type sbearssl_pemobject. +One sbearssl_pemobject is appended to the genalloc per PEM entity +found in the bytes in s. +

X.509 certificates (typically for servers)

`int sbearssl_cert_from (sbearssl_cert l, br_x509_certificate const k, stralloc *sa)`

+ Converts a certificate from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_cert_to (sbearssl_cert const l, br_x509_certificate k, char *s)`

+ Converts a certificate from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_cert_readfile (char const fn, genalloc list, stralloc *sa)`

+ Reads one or more certificates from the file named fn and appends +them to the genalloc +in *list, which is a dynamically growing list of +sbearssl_cert structures. The bytes of the +(maybe PEM-decoded, but still DER-encoded) certificate are +appended to the stralloc in *sa. +

+ The fn file can be either DER-encoded (binary format) +or PEM-encoded (text format). If it is DER-encoded, it must +contain exactly one X.509 certificate. If it is PEM-encoded, +it may contain a chain of certificates as long as the PEM +file fits within the size limits. +

+ fn must not be bigger than SBEARSSL_MAXCERTFILESIZE, +which is 8 kB. This function is meant to read individual +certificates, not files containing large certificate chains or +sets of trust anchors. To do that, use +sbearssl_cert_readbigpem() instead. +

`int sbearssl_cert_readbigpem (char const fn, genalloc , stralloc *sa)`

+ Reads one or more PEM-encoded certificates from the file named +fn and appends them to the +genalloc +in *list, which is a dynamically growing list of +sbearssl_cert structures. The bytes of the PEM-decoded (but +still DER-encoded) certificates are appended to the stralloc +in *sa. +

+ The function will refuse to read a file that is not valid PEM. +Inside the file, It will ignore PEM objects that are +not X.509 certificates. +

Trust anchors (typically for clients)

+ BearSSL clients do not use X.509-encoded certificates, +they use sets of trust anchors, i.e. structures +decoded from certificates representing (intermediate or) +root CAs. +

`int sbearssl_ta_from (sbearssl_ta l, br_x509_trust_anchor const k, stralloc *sa)`

+ Converts a trust anchor from BearSSL format (reading from a structure pointed to by k) +to sbearssl format (writing to a structure pointed to by l). +The data from *k's contents are copied into the stralloc in *sa. +The function returns 1 on success and 0 (and sets errno) on failure. +

`void sbearssl_ta_to (sbearssl_ta const l, br_x509_trust_anchor k, char *s)`

+ Converts a trust anchor from sbearssl format (reading from a structure pointed to by l) +to BearSSL format (writing to a structure pointed to by k). +The indices in l must refer to data stored in the string s. +

`int sbearssl_ta_readfile (char const fn, genalloc list, stralloc *sa)`

+ Reads a set of trust anchors from a PEM file named fn +which must contain a list of (intermediate or) root CA certificates. +The trust anchors are appended to the +genalloc +in *list, which is a dynamically growing list of +sbearssl_ta structures. The contents of the trust anchors +are appended to *sa, which is a +stralloc +used for storage. +

`int sbearssl_ta_readdir (char const dir, genalloc list, stralloc *sa)`

+ Reads a set of trust anchors from a directory named dir, +which must contain a list of (intermediate or) root CA certificates +stored as individual DER- or PEM-encoded files. +The trust anchors are appended to the +genalloc +in *list, which is a dynamically growing list of +sbearssl_ta structures. The contents of the trust anchors +are appended to *sa, which is a +stralloc +used for storage. +

+ The function ignores files that do not contain valid DER +or PEM objects containing X.509 certificates representing +certification authorities. +

Miscellaneous utilities

+ You probably shouldn't need to call any of these functions +directly, except for the first one. +

`char const *sbearssl_error_str (int err)`

+ Returns a fixed string containing an error message corresponding +to the err code, which must be non-negative. The return +value from a few sbearssl functions, if positive, can be +interpreted via this function. +

`int sbearssl_isder (unsigned char const *s, size_t len)`

+ Tests whether the array of len bytes pointed to by s +looks like a DER-encoded object. Returns 1 if it does and 0 otherwise. +

`int sbearssl_x509_minimal_set_tai (br_x509_minimal_context *ctx, tai_t t)`

+ Sets the validation time for the X.509 context in *ctx to +the absolute time contained in *t, which is a +tai_t. +Returns 1 if it succeeds, or 0 if it fails - probably +because *t does not represent a valid time. +

`int sbearssl_x509_minimal_set_tain (br_x509_minimal_context *ctx, tain_t a)`

+ Same as the above function, except the time is given as a +tain_t, +i.e. a tai_t plus nanoseconds (which are simply ignored). +

Running the TLS/SSL engine (both clients and servers)

`int sbearssl_run (br_ssl_engine_context ctx, int fds, unsigned int verbosity, uint32_t options, tain_t const *tto)`

+ This function runs a full-duplex TLS/SSL engine, reading/writing +clear text from/to two file descriptors, and writing/reading +ciphertext to/from two other file descriptors, until the +connection is closed both ways (either with a SSL close, or +with EOF). +

ctx is a pointer to a fully initialized context, +connected to fds[2] and fds[3]. The +TLS/SSL handshake does not have to be completed.
fds is an array of 4 file descriptors, in this +order: fd reading clear text, fd writing clear text, fd reading +ciphertext, fd writing ciphertext.
verbosity defines the engine's verbosity: the +higher the more verbose. This parameter is currently ignored.
options is a bitfield. +
- bit 0 tells the engine how to behave when +the local application closes the connection (i.e. when the engine +reads EOF on fds[0]). If the bit is clear, then the +engine will perform as SSL close: it will send a SSL close_notify, +and stop processing incoming records, waiting for a peer +acknowledgement of the close_notify. If the bit is set, then the +engine will not send a close_notify but simply transmit EOF to +the peer, while continuing to process incoming records until it +gets EOF back. close_notify is secure when handling protocols that +are not auto-terminated (such as HTTP 0.9), but it does not permit +separate closing of both ways. EOF allows full-duplex until the +very end, but is insecure if the application protocol does not +know in advance how many bytes it should get. Modern application +protocols should all work with EOF.
tto is a pointer to a + tain_t +containing a relative time (i.e. a timeout) If *tto time elapses +with no application data being exchanged, the engine will forcibly close the +connection (with the method defined by options & 1). + You can use &tain_infinite_relative as a value for tto +if you don't want the engine to ever timeout.

+ sbearssl_run will make the process die with an appropriate error +message if it encounters an unrecoverable error. If there were no problems +and the SSL/TLS connection closed cleanly, it returns 0. If a SSL/TLS-level +error occurred, it returns nonzero; a corresponding error message for the +return value can be obtained via sbearssl_error_str(). +All four descriptors in fds are closed when +sbearssl_run returns. +

`int sbearssl_s6tlsc (char const const argv, char const const envp, tain_t const tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const servername, int *sfd)`

+ This function implements s6-tlsc on top of BearSSL. +It has no other practical purpose; you're better off directly invoking +s6-tlsc. +

`int sbearssl_s6tlsd (char const const argv, char const const envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity)`

+ This function implements s6-tlsd on top of BearSSL. +It has no other practical purpose; you're better off directly invoking +s6-tlsd. +

s6-networking: the stls library interface

+s6-networking
+Software
+skarnet.org +

The `stls` library interface

General information

+ libstls is a small support library for the +s6-tlsc and +s6-tlsd executables when they're built +against the LibreSSL +backend. You can use it in your own programs, but since +libtls +is already relatively high-level, it's probably not very useful. +

Compiling

Make sure the s6-networking headers, as well as the skalibs headers, +and the tls.h header, are visible in your header search path.
Use #include <s6-networking/stls.h>

Linking

Make sure the s6-networking libraries, as well as the skalibs +libraries, and the LibreSSL libraries, are visible in your library search path.
Link against -lstls, -lskarnet, -ltls, +-lssl, -lcrypto, +`cat $sysdeps/socket.lib`, `cat $sysdeps/spawn.lib`, and +`cat $sysdeps/tainnow.lib`, where $sysdeps is your skalibs +sysdeps directory.

Programming

Running the TLS/SSL engine

`int stls_run (struct tls ctx, int fds, unsigned int verbosity, uint32_t options, tain_t const *tto)`

ctx is a pointer to a fully initialized context, +connected to fds[2] and fds[3]. The TLS +handshake must already be completed.
fds is an array of 4 file descriptors, in this +order: fd reading clear text, fd writing clear text, fd reading +ciphertext, fd writing ciphertext.
verbosity defines the engine's verbosity: the +higher the more verbose. This parameter is currently ignored.
options is a bitfield. +
- bit 0 tells the engine how to behave when +the local application closes the connection (i.e. when the engine +reads EOF on fds[0]). If the bit is clear, then the +engine will perform as SSL close: it will send a SSL close_notify, +and stop processing incoming records, waiting for a peer +acknowledgement of the close_notify. If the bit is set, then the +engine will not send a close_notify but simply transmit EOF to +the peer, while continuing to process incoming records until it +gets EOF back. close_notify is secure when handling protocols that +are not auto-terminated (such as HTTP 0.9), but it does not permit +separate closing of both ways. EOF allows full-duplex until the +very end, but is insecure if the application protocol does not +know in advance how many bytes it should get. Modern application +protocols should all work with EOF.
tto is a pointer to a + tain_t +containing a relative time (i.e. a timeout). If *tto time elapses +with no application data being exchanged, the engine will forcibly close the +connection (with the method defined by options & 1). + You can use &tain_infinite_relative as a value for tto +if you don't want the engine to ever timeout.

+ stls_run will make the process die with an appropriate error +message if it encounters an error. If there were no problems and the +SSL/TLS connection closed cleanly, it returns 0. All four descriptors +in fds are closed when stls_run returns, but the +caller should still free ctx itself. +

`int stls_s6tlsc (char const const argv, char const const envp, tain_t const tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const servername, int *sfd)`

+ This function implements s6-tlsc on top of LibreSSL. +It has no other practical purpose; you're better off directly invoking +s6-tlsc. +

`int stls_s6tlsd (char const const argv, char const const envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity)`

+ This function implements s6-tlsd on top of LibreSSL. +It has no other practical purpose; you're better off directly invoking +s6-tlsd. +

s6-networking: the s6-tlsc program

+s6-networking
+Software
+skarnet.org +

The `s6-tlsc` program

+s6-tlsc is a program that establishes a TLS or SSL +client connection over an existing TCP connection, then spawns +an application. It is meant to make network communications +secure even for applications that do not natively support +TLS/SSL. +

+ s6-networking does not include +cryptographic software. All the crypto used in s6-tlsc +is provided by the chosen SSL backend: +BearSSL or +LibreSSL, depending on +the options given when configuring s6-networking. +

Interface

+     s6-tlsc [ -S | -s ] [ -Y | -y ] [ -Z | -z ] [ -v verbosity ] [ -K kimeout ] [ -k servername ] [ -6 rfd ] [ -7 wfd ] [ -- ] prog...
+

s6-tlsc expects to have an open TCP connection it +can talk to on its (by default) descriptors 6 (for reading) +and 7 (for writing).
It spawns prog... as a child process, +interposing itself between it and the network.
It initiates a TLS/SSL handshake over the +network connection, expecting a TLS/SSL server on the other +side.
It manages the encryption/decryption of all the +messages between prog and the server. +prog speaks plaintext, but only ciphertext is sent +on the network.
When prog exits, s6-tlsc exits. +

Exit codes

96: error while configuring the TLS/SSL context - for instance, invalid trust anchor set.
97: error while setting up the TLS/SSL client engine.
98: TLS/SSL error while running the engine.
100: wrong usage.
111: system call failed.

+ If the TLS/SSL connection closes cleanly, s6-tlsc +waits for prog to exit, then exits with an +approximation +of prog's exit code. +

Protocol version and parameters

+ During the TLS/SSL handshake, s6-tlsc tries +every version of the protocol that is supported by the +backend, with all supported algorithms and cipher suites; +the backend normally ensures that the most secure combination +is tried first, with slow degradation until the client and +the server agree. +

For BearSSL, this means use of the +br_ssl_client_init_full() +function. The supported protocol versions are described +here.
For LibreSSL, this means use of the +tls_config_set_protocols(TLS_PROTOCOLS_ALL) +call.

+ As a client, it is better for s6-tlsc to adapt to as many servers +as possible, that's why it adopts a liberal approach to protocol +versions. +

Environment variables

Read

+ s6-tlsc expects to have one of the +CADIR or CAFILE environment variables set. +It will refuse to run if both are unset. If both are set, +CADIR has priority. The value of that variable is: +

for CADIR: a directory where trust anchors +(i.e. root or intermediate CA certificates) can be found, +one per file, DER- or PEM-encoded.
for CAFILE: a file containing the whole set +of trust anchors, PEM-encoded.

+ If you are using client certificates, s6-tlsc also reads +two more environment variables: KEYFILE contains +the path to a file containing the private key, DER- or +PEM-encoded; and CERTFILE contains the path to +a file containing the client certificate, DER- or +PEM-encoded. Please note that for now, support for client +certificates is experimental, and only works +with the LibreSSL +backend (BearSSL does not support client certificates yet). +

+ If s6-tlsc is run as root, it can also read two +other environment variables, TLS_UID and TLS_GID, +which contain a numeric uid and a numeric gid; s6-tlsc +then drops its root privileges to this uid/gid after spawning +prog.... This ensures that the TLS/engine and the +application run with different privileges. Note that prog... +should drop its own root privileges by its own means: the +s6-applyuidgid +program is a way of doing it. +

Written

+ Unless the -Z option has been given to +s6-tlsc, prog... is run with all the +TLS/SSL variables unset: CADIR, CAFILE, +KEYFILE, CERTFILE, TLS_UID and TLS_GID. The goal is +for s6-tlsc to be, by default, as invisible +as possible. +

Server name determination for SNI

+ The -k servername option is important to +s6-tlsc: it tells it to send servername +as the name to require a certificate for. +Not setting this option allows s6-tlsc to +proceed without SNI, +which may be a security risk. +

+ The s6-tlsclient program can +automatically craft a -k option for s6-tlsc +if the host argument that is given to it is a +host name. But if you're invoking s6-tlsc directly, +do not forget to give it this option. +

SSL close handling

+ If prog initiates the end of the session by sending +EOF, there are two ways for the TLS/SSL layer to handle it. +

It can send a close_notify alert, and wait for +an acknowledgement from the peer, at which point the connection +is closed. The advantage of this setup is that it is secure +even when the application protocol is not auto-terminated, i.e. +when it does not know when its data stops. Old protocols such +as HTTP-0.9 are in this case. The drawback of this setup is +that it breaks full-duplex: once a peer has sent the +close_notify, it must discard all the incoming +records that are not a close_notify from the +other peer. So if a client sends EOF while it is still +receiving data from the server, the connection closes +immediately and the data can be truncated.
It can simply transmit the EOF, shutting down +half the TCP connection, and wait for the EOF back. +The advantage of this setup is that it maintains +full-duplex: a client can send EOF after its initial +request, and still receive a complete answer from the +server. The drawback is that it is insecure when the application +protocol is not auto-terminated.

+ Nowadays (2016), most protocols are auto-terminated, so +it is not dangerous anymore to use EOF tranmission, and that +is the default fo s6-tlsc. Nevertheless, by +using the -S option, you can +force it to use the close_notify method if your +application requires it to be secure. +

`s6-tlsc` options

-v verbosity : Be more or less +verbose. Default for verbosity is 1. 0 is quiet, 2 is +verbose, more than 2 is debug output. This option currently has +no effect.
-Z : do not clean the environment of +s6-tlsc-related variables before spawning prog....
-z : clean the environment of +s6-tlsc-related variables before spawning prog.... +This is the default.
-S : send a close_notify alert +and break the connection when prog sends EOF.
-s : transmit EOF by half-closing the TCP +connection without using close_notify. This is the default.
-Y : Do not send a client certificate. This is the default.
-y : Send a client certificate. This is experimental and +for now unsupported by BearSSL.
-k servername : use Server Name +Indication, and send servername. The default is not to +use SNI, which may be a security risk.
-K kimeout : close the connection +if kimeout milliseconds elapse without any data being +received from either side. The default is 0, which means +infinite timeout (never kill the connection).
-6 rfd : expect an open file +descriptor numbered rfd to read network (ciphertext) +data from. Make sure prog also reads its data +from its own fd rfd. Default is 6.
-7 wfd : expect an open file +descriptor numbered wfd to write network (ciphertext) +data to. Make sure prog also writes its data to +its own fd wfd. Default is 7.

Notes

The goal of the s6-tlsc interface (and its +server-side companion s6-tlsd is to +make it so that if you have a client, run by the command line +client... that speaks a cleartext protocol to a server +run by the command line server..., then if the server +has the proper private key and certificate, and the client has +the proper list of trust anchors, you can just change the +client command line to s6-tlsc client... and the +server command line to s6-tlsd server... +without changing the client or the server themselves, and the +communication between them will be secure.

s6-networking: the s6-tlsclient program

+s6-networking
+Software
+skarnet.org +

The `s6-tlsclient` program

+s6-tlsclient is an +UCSPI client tool for +TLS/SSL connections over INET domain sockets. It establishes a TCP +connection to a server and a TLS transport over it, +then executes into a program. +

Interface

+     s6-tlsclient [ options ] [ -- ] host port prog...
+

s6-tlsclient rewrites itself into a command line +involving: +
- s6-tcpclient, which +establishes a TCP connection to host host port port.
- s6-tlsc, which establishes +a TLS transport (client-side) over that connection.
- prog..., your client program, which is run as a +child of s6-tlsc.
It runs until the connection closes.
It exits either with a s6-tlsc +error code (and error message), or with an +approximation +of prog's exit code.

+ prog is expected to read from its peer on +descriptor 6 and write to its peer on descriptor 7. +Since there will be a s6-tlsc +program between prog and the network to perform +the SSL encryption/decryption, those descriptors will not +be a network socket - they will be pipes. +

Server name determination for SNI

+ + If the -H option is not given to s6-tlsclient, +then host will be used as the server name to verify. +You can use the -k option to override this default. +Please note that if you use the -H option and do not +provide a server name via -k, SNI will not be +used, which may be a security risk. +

Environment variables

Read

+ The following variables should be set before invoking +s6-tlsclient, because they will be used by +s6-tlsc: +

CADIR
CAFILE (alternative to CADIR)
KEYFILE (if you're using a client certificate)
CERTFILE (if you're using a client certificate)
TLS_UID and TLS_GID (if you run s6-tlsclient as root)

+ Setting either CADIR or CAFILE is mandatory. +

Written

+ prog... is run with the following variables added to, +or removed from, its environment by s6-tcpclient: +

PROTO
TCPREMOTEIP
TCPREMOTEPORT
TCPREMOTEHOST
TCPLOCALHOST
TCPREMOTEINFO

+ Unless the -Z option is given to s6-tlsclient, +the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID +variables will not appear in prog's environment. +

Options

+ s6-tlsclient accepts a myriad of options, most of which are +passed as is to the correct executable. Not giving any options will +generally work: the defaults are sensible. +

Options passed as is to s6-tcpclient

-q, -Q, -v
-4, -6
-d, -D
-r, -R
-h, -H, -l localname
-n, -N
-t timeout
-i localip, -p localport
-T timeoutconn

Options passed as is to s6-tlsc

-Z, -z
-S, -s
-Y, -y
-k servername
-K kimeout

Example

+ CADIR=/etc/ssl/certs s6-tlsclient skarnet.org 443 s6-ioconnect +

+ This will open a connection to +the skarnet.org web server +over TLS and verify its certificate via the trust anchors +listed in the /etc/ssl/certs directory. It will then +branch your terminal to it: try typing +GET / HTTP/1.0 then hitting return twice. +

s6-networking: the s6-tlsd program

+s6-networking
+Software
+skarnet.org +

The `s6-tlsd` program

+s6-tlsd is a program that performs the server side of +a TLS or SSL connection over an existing TCP connection, then spawns +an application. It is meant to make network communications +secure even for applications that do not natively support +TLS/SSL. +

Interface

+     s6-tlsd [ -S | -s ] [ -Y | -y ] [ -Z | -z ] [ -v verbosity ] [ -K kimeout ] [ -- ] prog...
+

s6-tlsd expects to have an open TCP connection it +can talk to on its stdin (for reading) and stdout +(for writing).
It spawns prog... as a child process, +interposing itself between it and the network. +In other words: prog still reads cleartext +on its stdin and writes cleartext on its stdout, but +those will actually be pipes to s6-tlsd, which +will read ciphertext from its own stdin (the network) +and write ciphertext to its own stdout (the network).
It initiates the server side of a TLS/SSL handshake +over the network connection, expecting a TLS/SSL client on +the other side.
It manages the encryption/decryption of all the +messages between prog and the client. +prog speaks plaintext, but only ciphertext is sent +on the network.
When prog exits, s6-tlsd exits. +

Exit codes

96: error while configuring the TLS/SSL context - for instance, invalid +private key or server certificate files.
97: error while setting up the TLS/SSL client engine.
98: TLS/SSL error while running the engine.
100: wrong usage.
111: system call failed.

+ If the TLS/SSL connection closes cleanly, s6-tlsd +waits for prog to exit, then exits with an +approximation +of prog's exit code. +

Protocol version and parameters

+ During the TLS/SSL handshake, s6-tlsd tries the +versions of the protocol that is supported by default by the +backend, with the default algorithms and cipher suites; +the backend normally ensures that the most secure combination +is tried first, with slow degradation until the client and +the server agree. +

For BearSSL, this means use of the +br_ssl_server_init_full_rsa() or +br_ssl_server_init_full_ec() +function. The supported protocol versions are described +here.
For LibreSSL, this means use of the +tls_config_set_protocols(TLS_PROTOCOLS_DEFAULT) +call.

+ As a server, s6-tlsd can be conservative in its +choice of protocols. It is currently not very conservative +when using the BearSSL backend; it could become more so in +the future, by defining a custom server profile that supports +only TLS-1.2 but with several algorithms and cipher suites. +

Environment variables

Read

+ s6-tlsd expects to have the following +environment variables set: +

KEYFILE: a path to the file +containing the server's private key, DER- or PEM-encoded.
CERTFILE: a path to the file +containing the server's certificate, DER- or PEM-encoded. +If PEM-encoded, the file can actually contain a chain +of certificates.

+ If one of those variables is unset, s6-tlsd +will refuse to run. +

+ If you are using client certificats, s6-tlsd +also requires either one of the following variables to be set: +

CADIR: a directory where trust anchors +(i.e. root or intermediate CA certificates) can be found, +one per file, DER- or PEM-encoded.
CAFILE: a file containing the whole set +of trust anchors, PEM-encoded.

+Please note that for now, support for client +certificates is experimental, and only works +with the LibreSSL +backend (BearSSL does not support client certificates yet). +

+ If s6-tlsd is run as root, it can also read two +more environment variables, TLS_UID and TLS_GID, +which contain a numeric uid and a numeric gid; s6-tlsd +then drops its root privileges to this uid/gid after spawning +prog.... This ensures that the TLS/engine and the +application run with different privileges. +

+ Note that prog... +should drop its own root privileges by its own means: the +s6-applyuidgid +program is a way of doing it. If the s6-tlsd +invocation actually comes from a +s6-tlsserver command line, +and privilege-dropping options (-G, -g, +-u or -U) have been given to +s6-tlsserver, then +s6-applyuidgid +directly follows s6-tlsd on the command line, in order +to also drop the child's privileges before executing the application. +The point of that setup is: +

To read the private key file as root
To run the application as a non-root user
To run s6-tlsd as a different non-root user
That way, even if s6-tlsd, the application, or both, +get compromised, the private key is still secure.

Written

+ Unless the -Z option has been given to +s6-tlsd, prog... is run with all the +TLS/SSL variables unset: CADIR, CAFILE, +KEYFILE, CERTFILE, TLS_UID and TLS_GID. The goal is +for s6-tlsd to be, by default, as invisible +as possible. +

SSL close handling

+ If prog initiates the end of the session by sending +EOF, there are two ways for the TLS/SSL layer to handle it. +

It can send a close_notify alert, and wait for +an acknowledgement from the peer, at which point the connection +is closed. The advantage of this setup is that it is secure +even when the application protocol is not auto-terminated, i.e. +when it does not know when its data stops. Old protocols such +as HTTP-0.9 are in this case. The drawback of this setup is +that it breaks full-duplex: once a peer has sent the +close_notify, it must discard all the incoming +records that are not a close_notify from the +other peer. So if a client sends EOF while it is still +receiving data from the server, the connection closes +immediately and the data can be truncated.
It can simply transmit the EOF, shutting down +half the TCP connection, and wait for the EOF back. +The advantage of this setup is that it maintains +full-duplex: a client can send EOF after its initial +request, and still receive a complete answer from the +server. The drawback is that it is insecure when the application +protocol is not auto-terminated.

+ Nowadays (2016), most protocols are auto-terminated, so +it is not dangerous anymore to use EOF tranmission, and that +is the default fo s6-tlsd. Nevertheless, by +using the -S option, you can +force it to use the close_notify method if your +application requires it to be secure. +

`s6-tlsd` options

-v verbosity : Be more or less +verbose. Default for verbosity is 1. 0 is quiet, 2 is +verbose, more than 2 is debug output. This option currently has +no effect.
-Z : do not clean the environment of +s6-tlsd-related variables before spawning prog....
-z : clean the environment of +s6-tlsd-related variables before spawning prog.... +This is the default.
-S : send a close_notify alert +and break the connection when prog sends EOF.
-s : transmit EOF by half-closing the TCP +connection without using close_notify. This is the default.
-Y : Do not require a client certificate. This is the default.
-y : Require a client certificate. This is experimental and +for now unsupported by BearSSL.
-K kimeout : close the connection +if kimeout milliseconds elapse without any data being +received from either side. The default is 0, which means +infinite timeout (never kill the connection).

Notes

The goal of the s6-tlsd interface (and its +client-side companion s6-tlsc is to +make it so that if you have a client, run by the command line +client... that speaks a cleartext protocol to a server +run by the command line server..., then if the server +has the proper private key and certificate, and the client has +the proper list of trust anchors, you can just change the +client command line to s6-tlsc client... and the +server command line to s6-tlsd server... +without changing the client or the server themselves, and the +communication between them will be secure.

s6-networking: the s6-tlsserver program

+s6-networking
+Software
+skarnet.org +

The `s6-tlsserver` program

+s6-tlsserver is an +UCSPI server tool for +TLS/SSL connections over INET domain sockets. It acts as a TCP superserver +that listens to connections, accepts them, and for each connection, +establishes a TLS transport over it, then executes into a program. +

Interface

+     s6-tlsserver [ options ] [ -- ] ip port prog...
+

s6-tlsserver rewrites itself into a command line +involving: +
- s6-tcpserver, which +listens to TCP connections on IP address ip port port +and forks a command line for every connection. Note that +s6-tcpserver also rewrites +itself into a more complex commnd line (the final long-lived +process being s6-tcpserver4d +or s6-tcpserver6d), +so your end command line may look a lot longer in ps +than what you originally wrote. This is normal and healthy.
- (if applicable) s6-tcpserver-access, +which performs TCP access control and various operations on the +TCP connection.
- s6-tlsd, which establishes +a TLS transport (server-side) over a connection.
- (if applicable) +s6-applyuidgid, +which drops root privileges.
- prog..., your client program, which is run as a +child of s6-tlsd.
It runs until it is killed by a signal.

+ prog is expected to read from its peer on its +standard input and write to its peer on its standard output. +Since there will be a s6-tlsd +program between prog and the network to perform +the SSL encryption/decryption, those descriptors will not +be a network socket - they will be pipes. +

Signals

+ s6-tlsserver reacts to the same signals as +s6-tcpserver4d or +s6-tcpserver6d, +one of which is the long-lived process hanging around. +

Environment variables

Read

+ The following variables should be set before invoking +s6-tlsserver, because they will be used by +every s6-tlsd invocation: +

KEYFILE
CERTFILE
TLS_UID and TLS_GID (if you run s6-tlsserver as root)
CADIR (if you want client certificates)
CAFILE (if you want client certificates, alternative to CADIR)

+ Setting both KEYFILE and CERTFILE is mandatory. +

Written

+ prog... is run with the following variables added to, +or removed from, its environment by s6-tcpserver4d +or s6-tcpserver6d, and possibly +by s6-tcpserver-access: +

PROTO
TCPREMOTEIP
TCPREMOTEPORT
TCPCONNNUM
TCPLOCALIP
TCPLOCALPORT
TCPREMOTEHOST
TCPLOCALHOST
TCPREMOTEINFO

+ Depending on TCP access rules (if the -i or -x +option has been given), it is possible that prog's +environment undergoes more modifications. Also, since +s6-tlsd is always run +after s6-tcpserver-access, +it is possible to set different TLS/SSL parameters (typically +a different KEYFILE and CERTFILE) depending on the client +connection, by writing the correct set of TCP access rules. +

+ Unless the -Z option is given to s6-tlsserver, +the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID +variables will not appear in prog's environment. +

Options

+ s6-tlsserver accepts a myriad of options, most of which are +passed as is to the correct executable. Not giving any options will +generally work, but unless you're running a very public server +(such as a Web server) or base your access control on client +certificates, you probably still want TCP access rules. +

Options passed as is to s6-tcpserver

-q, -Q, -v
-4, -6
-1
-c maxconn
-C localmaxconn
-b backlog

Options passed as is to s6-tcpserver-access

The verbosity level, if not default, as -v0 or -v2
-w, -W
-d, -D
-r, -R
-p, -P
-h, -H, -l localname
-B banner
-t timeout
-i rulesdir, -x rulesfile

Options passed as is to s6-tlsd

-Z, -z
-S, -s
-Y, -y
-k servername
-K kimeout

Options passed to s6-applyuidgid

-u uid, -g gid, -G gidlist
-U (passed as -Uz)

Example

+ As root: + KEYFILE=/etc/ssl/private/mykey.der CERTFILE=/etc/ssl/public/mycert.pem \ + TLS_UID=65534 TLS_UID=65536 \ + s6-envuidgid www + s6-tlsserver -U -- 1.2.3.4 443 httpd +

+This will start a server listening to 1.2.3.4 on TCP port 443, + and for every connection, spawn the httpd program +reading queries on stdin and replying on stdout, as user www, +with a TLS layer protecting the connection, the TLS engine running +as user nobody (65534:65534). The server is +authentified by the certificate in /etc/ssl/public/mycert.pem +that it sends to the client, and the private key in +/etc/ssl/private/mykey.der that it keeps to itself. +

skalibs dependency bumped to 2.4.0.1.
TLS 1.2 support added: +
SSL/TLS support added:
- s6-tlsclient
- s6-tlsserver

UCSPI tools for TLS 1.2 over TCP

UCSPI tools for SSL/TLS over TCP

Libraries

The sbearssl library interface

General information

Compiling

Linking

Programming

General concepts

Private keys (typically for servers)

int sbearssl_rsa_skey_from (sbearssl_rsa_skey *l, br_rsa_private_key const *k, stralloc *sa)

void sbearssl_rsa_skey_to (sbearssl_rsa_skey const *l, br_rsa_private_key *k, char *s)

int sbearssl_ec_skey_from (sbearssl_ec_skey *l, br_ec_private_key const *k, stralloc *sa)

void sbearssl_ec_skey_to (sbearssl_ec_skey const *l, br_ec_private_key *k, char *s)

int sbearssl_skey_from (sbearssl_skey *l, br_skey const *k, stralloc *sa)

void sbearssl_skey_to (sbearssl_skey const *l, br_skey *k, char *s)

int sbearssl_skey_readfile (char const *fn, sbearssl_skey *key, stralloc *sa)

Public keys

int sbearssl_rsa_pkey_from (sbearssl_rsa_pkey *l, br_rsa_public_key const *k, stralloc *sa)

void sbearssl_rsa_pkey_to (sbearssl_rsa_pkey const *l, br_rsa_public_key *k, char *s)

int sbearssl_ec_pkey_from (sbearssl_ec_skey *l, br_ec_public_key const *k, stralloc *sa)

void sbearssl_ec_pkey_to (sbearssl_ec_pkey const *l, br_ec_public_key *k, char *s)

int sbearssl_pkey_from (sbearssl_pkey *l, br_x509_pkey const *k, stralloc *sa)

void sbearssl_pkey_to (sbearssl_pkey const *l, br_x509_pkey *k, char *s)

Generic PEM objects

int sbearssl_pem_decode_from_buffer (buffer *b, genalloc *list, stralloc *sa)

int sbearssl_pem_decode_from_string (char const *s, size_t len, genalloc *list, stralloc *sa)

X.509 certificates (typically for servers)

int sbearssl_cert_from (sbearssl_cert *l, br_x509_certificate const *k, stralloc *sa)

void sbearssl_cert_to (sbearssl_cert const *l, br_x509_certificate *k, char *s)

int sbearssl_cert_readfile (char const *fn, genalloc *list, stralloc *sa)

int sbearssl_cert_readbigpem (char const *fn, genalloc *, stralloc *sa)

Trust anchors (typically for clients)

int sbearssl_ta_from (sbearssl_ta *l, br_x509_trust_anchor const *k, stralloc *sa)

void sbearssl_ta_to (sbearssl_ta const *l, br_x509_trust_anchor *k, char *s)

int sbearssl_ta_readfile (char const *fn, genalloc *list, stralloc *sa)

int sbearssl_ta_readdir (char const *dir, genalloc *list, stralloc *sa)

Miscellaneous utilities

char const *sbearssl_error_str (int err)

int sbearssl_isder (unsigned char const *s, size_t len)

int sbearssl_x509_minimal_set_tai (br_x509_minimal_context *ctx, tai_t t)

int sbearssl_x509_minimal_set_tain (br_x509_minimal_context *ctx, tain_t a)

Running the TLS/SSL engine (both clients and servers)

int sbearssl_run (br_ssl_engine_context *ctx, int *fds, unsigned int verbosity, uint32_t options, tain_t const *tto)

int sbearssl_s6tlsc (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const *servername, int *sfd)

int sbearssl_s6tlsd (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity)

The stls library interface

General information

Compiling

Linking

Programming

Running the TLS/SSL engine

int stls_run (struct tls *ctx, int *fds, unsigned int verbosity, uint32_t options, tain_t const *tto)

int stls_s6tlsc (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const *servername, int *sfd)

int stls_s6tlsd (char const *const *argv, char const *const *envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity)

The s6-tlsc program

Interface

Exit codes

Protocol version and parameters

Environment variables

Read

Written

Server name determination for SNI

SSL close handling

s6-tlsc options

Notes

The s6-tlsclient program

Interface

Server name determination for SNI

Environment variables

Read

Written

Options

Options passed as is to s6-tcpclient

Options passed as is to s6-tlsc

Example

The s6-tlsd program

Interface

Exit codes

Protocol version and parameters

The `sbearssl` library interface

`int sbearssl_rsa_skey_from (sbearssl_rsa_skey l, br_rsa_private_key const k, stralloc *sa)`

`void sbearssl_rsa_skey_to (sbearssl_rsa_skey const l, br_rsa_private_key k, char *s)`

`int sbearssl_ec_skey_from (sbearssl_ec_skey l, br_ec_private_key const k, stralloc *sa)`

`void sbearssl_ec_skey_to (sbearssl_ec_skey const l, br_ec_private_key k, char *s)`

`int sbearssl_skey_from (sbearssl_skey l, br_skey const k, stralloc *sa)`

`void sbearssl_skey_to (sbearssl_skey const l, br_skey k, char *s)`

`int sbearssl_skey_readfile (char const fn, sbearssl_skey key, stralloc *sa)`

`int sbearssl_rsa_pkey_from (sbearssl_rsa_pkey l, br_rsa_public_key const k, stralloc *sa)`

`void sbearssl_rsa_pkey_to (sbearssl_rsa_pkey const l, br_rsa_public_key k, char *s)`

`int sbearssl_ec_pkey_from (sbearssl_ec_skey l, br_ec_public_key const k, stralloc *sa)`

`void sbearssl_ec_pkey_to (sbearssl_ec_pkey const l, br_ec_public_key k, char *s)`

`int sbearssl_pkey_from (sbearssl_pkey l, br_x509_pkey const k, stralloc *sa)`

`void sbearssl_pkey_to (sbearssl_pkey const l, br_x509_pkey k, char *s)`

`int sbearssl_pem_decode_from_buffer (buffer b, genalloc list, stralloc *sa)`

`int sbearssl_pem_decode_from_string (char const s, size_t len, genalloc list, stralloc *sa)`

`int sbearssl_cert_from (sbearssl_cert l, br_x509_certificate const k, stralloc *sa)`

`void sbearssl_cert_to (sbearssl_cert const l, br_x509_certificate k, char *s)`

`int sbearssl_cert_readfile (char const fn, genalloc list, stralloc *sa)`

`int sbearssl_cert_readbigpem (char const fn, genalloc , stralloc *sa)`

`int sbearssl_ta_from (sbearssl_ta l, br_x509_trust_anchor const k, stralloc *sa)`

`void sbearssl_ta_to (sbearssl_ta const l, br_x509_trust_anchor k, char *s)`

`int sbearssl_ta_readfile (char const fn, genalloc list, stralloc *sa)`

`int sbearssl_ta_readdir (char const dir, genalloc list, stralloc *sa)`

`char const *sbearssl_error_str (int err)`

`int sbearssl_isder (unsigned char const *s, size_t len)`

`int sbearssl_x509_minimal_set_tai (br_x509_minimal_context *ctx, tai_t t)`

`int sbearssl_x509_minimal_set_tain (br_x509_minimal_context *ctx, tain_t a)`

`int sbearssl_run (br_ssl_engine_context ctx, int fds, unsigned int verbosity, uint32_t options, tain_t const *tto)`

`int sbearssl_s6tlsc (char const const argv, char const const envp, tain_t const tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const servername, int *sfd)`

`int sbearssl_s6tlsd (char const const argv, char const const envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity)`

The `stls` library interface

`int stls_run (struct tls ctx, int fds, unsigned int verbosity, uint32_t options, tain_t const *tto)`

`int stls_s6tlsc (char const const argv, char const const envp, tain_t const tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity, char const servername, int *sfd)`

`int stls_s6tlsd (char const const argv, char const const envp, tain_t const *tto, uint32_t preoptions, uint32_t options, uid_t uid, gid_t gid, unsigned int verbosity)`

The `s6-tlsc` program

`s6-tlsc` options

The `s6-tlsclient` program

The `s6-tlsd` program

`s6-tlsd` options

The `s6-tlsserver` program