From 47cbbb1619ace4013856843ef8f7d68279c74faa Mon Sep 17 00:00:00 2001
From: Laurent Bercot
Date: Sun, 22 Nov 2020 00:16:06 +0000
Subject: Add documentation, fix tiny privdrop bug
---
doc/index.html | 7 +-
doc/libsbearssl/index.html | 131 +++++++++++++++++++-------
doc/libstls/index.html | 112 +++++++++++++++-------
doc/s6-tlsc-io.html | 217 +++++++++++++++++++++++++++++++++++++++++++
doc/s6-tlsc.html | 197 +++++++++------------------------------
doc/s6-tlsclient.html | 18 ++--
doc/s6-tlsd-io.html | 212 ++++++++++++++++++++++++++++++++++++++++++
doc/s6-tlsd.html | 193 ++++++++------------------------------
doc/s6-tlsserver.html | 11 ++-
doc/s6-ucspitlsc.html | 178 +++++++++++++++++++++++++++++++++++
doc/s6-ucspitlsd.html | 168 +++++++++++++++++++++++++++++++++
doc/tls-overview.html | 142 ++++++++++++++++++++++++++++
src/sbearssl/sbearssl_drop.c | 4 +-
src/stls/stls_drop.c | 4 +-
14 files changed, 1199 insertions(+), 395 deletions(-)
create mode 100644 doc/s6-tlsc-io.html
create mode 100644 doc/s6-tlsd-io.html
create mode 100644 doc/s6-ucspitlsc.html
create mode 100644 doc/s6-ucspitlsd.html
create mode 100644 doc/tls-overview.html
diff --git a/doc/index.html b/doc/index.html
index 049ed70..f402ab3 100644
--- a/doc/index.html
+++ b/doc/index.html
@@ -139,10 +139,15 @@ relevant page.
UCSPI tools for secure communication (TLS protocol) over TCP
TCP access control
diff --git a/doc/libsbearssl/index.html b/doc/libsbearssl/index.html
index 1579b2d..656c724 100644
--- a/doc/libsbearssl/index.html
+++ b/doc/libsbearssl/index.html
@@ -470,33 +470,44 @@ because *t does not represent a valid time.
i.e. a tai_t plus nanoseconds (which are simply ignored).
+ void sbearssl_drop ()
- Running the TLS/SSL engine (both clients and servers)
+
+ 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.
+
+
+ Running the TLS/SSL engine (internal function for both clients and servers)
- int sbearssl_run (br_ssl_engine_context *ctx, int *fds, pid_t pid, unsigned int verbosity, uint32_t options, tain_t const *tto)
+ void sbearssl_run (br_ssl_engine_context *ctx, int *fds, tain_t const *tto, uint32_t options, unsigned int verbosity, sbearssl_handshake_cb_t_ref cb, sbearssl_handshake_cb_context_t *cbarg)
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.
+with EOF). It does not return.
- 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 5 file descriptors, in this
+
- 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, 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.
+ciphertext, fd writing ciphertext.
+ - 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.
- options is a bitfield.
- bit 0 tells the engine how to behave when
@@ -514,40 +525,94 @@ 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.
+ - verbosity defines the engine's verbosity: the
+higher the more verbose. This parameter is currently ignored.
+ - cb is a pointer to a callback function that will be called
+once after the TLS handshake is performed. This function is called with
+two arguments: ctx (a pointer to the current bearssl context),
+and cbarg (a pointer to a caller-provided structure).
+ - cbarg is a pointer to a structure provided by the caller.
+It will be passed as a second argument to cb when the TLS
+handshake has successfully completed.
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 -1. If the application
-subprocess dies early, sbearssl_run returns the wstat
-for that subprocess, i.e. the integer containing the information about
-its exit code or crash signal. No matter how sbearssl_run returns,
-the first four descriptors in fds are closed, but the
-selfpipe is untouched and the caller should free ctx itself.
+SSL/TLS connection closed cleanly, the process exits 0.
- 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)
+ Initializing and running the engine
+
+ void sbearssl_client_init_and_run (int *fds, tain_t const *tto, uint32_t preoptions, uint32_t options, unsigned int verbosity, char const *servername, sbearssl_handshake_cb_t_ref cb, unsigned int notif)
+
+
+ This function initializes a TLS context for a client-side connection,
+then runs the TLS engine via a call to sbearssl_run(). The
+function does not return.
+If the context cannot be initialized, the process exits 96 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.
+
- This function implements s6-tlsc on top of BearSSL.
-It has no other practical purpose; you're better off directly invoking
-s6-tlsc.
+ The arguments are as follows:
- 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)
+
+ - fds : an array of 4 file descriptors, that are in this
+order: the fd reading from the application (cleartext), the fd writing to the
+application (cleartext), the fd reading from the network, the fd writing to
+the network.
+ - preoptions : a bitfield.
+
+ - Bit 0: if clear, no client authentication is performed. If set,
+the CERTFILE and KEYFILE environment variables are read,
+they must contain the path to a valid client certificate and private key
+(else the process exits 96); this certificate is then provided to the
+server for client authentication. This feature is currently
+unsupported and will not work; leave that bit clear for now.
+
+ - options : a bitfield, which will be passed to
+sbearssl_run().
+
+ - Bit 0: if clear, no close_notify is performed and the engine
+will transmit EOF as received. If set, close_notify will be performed to
+end the TLS connection.
+
+ - verbosity defines the engine's verbosity: the
+higher the more verbose. This parameter is currently ignored.
+ - servername : the server name used for SNI. If NULL, then
+no SNI is performed, which may be a security risk.
+ - cb : a pointer to a callback function, that will be
+passed as is to sbearssl_run().
+ - notif : an unsigned integer that will be embedded into
+the cbarg structure that will be passed to sbearssl_run().
+It is used by s6-tlsc-io to identify a
+valid fd on which to write SSL data information once the handshake has
+completed.
+
+
+ void sbearssl_server_init_and_run (int *fds, tain_t const *tto, uint32_t preoptions, uint32_t options, unsigned int verbosity, sbearssl_handshake_cb_t_ref cb, unsigned int notif)
- This function implements s6-tlsd on top of BearSSL.
-It has no other practical purpose; you're better off directly invoking
-s6-tlsd.
+ 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 (this functionality is supported server-side),
+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.