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/libstls/index.html | 112 ++++++++++++++++++++++++++++++++++--------------- 1 file changed, 79 insertions(+), 33 deletions(-) (limited to 'doc/libstls') diff --git a/doc/libstls/index.html b/doc/libstls/index.html index fcd839a..f81396c 100644 --- a/doc/libstls/index.html +++ b/doc/libstls/index.html @@ -52,30 +52,97 @@ sysdeps directory.

Programming

-

Running the TLS/SSL engine

+

Utilities

-

int stls_run (struct tls *ctx, int *fds, pid_t pid, unsigned int verbosity, uint32_t options, tain_t const *tto)

+

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

+ +

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) or a given subprocess dies. +with EOF). It does not return.