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 libtls API, whether that API is implemented via LibreSSL or via OpenSSL with the addition of LibreTLS. You can use it in your own programs, but since libtls is already relatively high-level, it's probably not very useful.





void stls_drop ()

If the process is running as root, then this function drops its privileges (else it does nothing). The gid to drop to is read from the TLS_GID environment variable; the uid to drop to is read from the TLS_UID environment variable. If those variables are not given, then the uid, or gid, or both, are not changed. If they contain something else than numerical uid/gids, the process exits 111 with an error message.

int stls_send_environment (struct tls *ctx, int fd)

Writes a series of null-terminated strings of the form key=value to file descriptor fd; the series is terminated with an additional null character. The strings represent information about the TLS connection represented by context ctx; it is only valid to call this function after the handshake has completed. The exact keys used will change over time, but at least SSL_PROTOCOL=value and SSL_CIPHER=value are transmitted. The function returns 1 if it succeeds and 0 if it fails.

Initializing the TLS engine

struct tls *stls_client_init_and_handshake (int const *fds, uint32_t preoptions, char const *servername)

This function initializes a TLS context for a client-side connection, then performs a TLS handshake. It then returns a non-null pointer to a struct tls context for the application to pass to the stls_run function when it wants to run the engine. If the context cannot be initialized or the handshake cannot be performed, the process exits (96 for configuration issues, 97 for context and handshake issues) with an appropriate error message.

If the CADIR environment variable is set, then it must contain the path of a directory containing the hashed names of the public certificates identifying the trust anchors. Else, if the CAFILE environment variable is set, then it must contain the path to a PEM file containing all the certificates for the trust anchors. Else, the process exits 100 with an error message.

The arguments are as follows:

struct tls *stls_server_init_and_handshake (int const *fds, uint32_t preoptions)

Same as the previous function, but on the server side. No servername argument is required. The CERTFILE and KEYFILE environment variables are mandatory, they point to the server's certificate and private key. It is only necessary to set CADIR or CAFILE when bit 0 of preoptions is set, in which case client authentication will be requested, and a list of trust anchors (read from either the directory in CADIR or the PEM file in CAFILE) will be used to verify the client certificate.

Running the TLS engine

void 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). It does not return.

stls_run will make the process die with an appropriate error message and exit code if it encounters an unrecoverable error. If there were no problems and the SSL/TLS connection closed cleanly, the process exits 0.