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)`

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 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.

The stls library interface