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. --- doc/libstls/index.html | 127 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 doc/libstls/index.html (limited to 'doc/libstls/index.html') diff --git a/doc/libstls/index.html b/doc/libstls/index.html new file mode 100644 index 0000000..4c6819b --- /dev/null +++ b/doc/libstls/index.html @@ -0,0 +1,127 @@ + + + + + + s6-networking: the stls library interface + + + + + + +

+ +

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

+ + + -- cgit v1.3.1

The stls library interface