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/libsbearssl/index.html | 131 +++++++++++++++++++++++++++++++++------------ 1 file changed, 98 insertions(+), 33 deletions(-) (limited to 'doc/libsbearssl') 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.

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)

+ + +

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.

-- cgit v1.3.1