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/sysclock.lib`, where $sysdeps is your skalibs sysdeps directory.

Programming

Running the TLS/SSL engine

int stls_run (struct tls *ctx, int *fds, pid_t pid, 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) or a given subprocess dies.

• 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 5 file descriptors, in this order: fd reading clear text, fd writing clear text, fd reading ciphertext, fd writing ciphertext, selfpipe.
• pid is the pid of the application subprocess. When a SIGCHLD is detected on the selfpipe, the newly deceased process is reaped, and if it was pid, then the function returns as soon as it doesn't have anything left to write to the network peer.
• 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 unrecoverable error. If there were no problems and the SSL/TLS connection closed cleanly, it returns -1. If the application subprocess dies early, stls_run returns the wstat for that subprocess, i.e. the integer containing the information about its exit code or crash signal. No matter how stls_run returns, the first four descriptors in fds are closed, but the selfpipe is untouched and the caller should 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.