diff options
Diffstat (limited to 'doc/libsbearssl/index.html')
| -rw-r--r-- | doc/libsbearssl/index.html | 131 |
1 files changed, 98 insertions, 33 deletions
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 *<em>t</em> does not represent a valid time. i.e. a <tt>tai_t</tt> plus nanoseconds (which are simply ignored). </p> +<h4> <code> void sbearssl_drop () </code> </h4> -<h3> Running the TLS/SSL engine (both clients and servers) </h3> +<p> + 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. +</p> + +<h3> Running the TLS/SSL engine (internal function for both clients and servers) </h3> -<h4> <code> int sbearssl_run (br_ssl_engine_context *ctx, int *fds, pid_t pid, unsigned int verbosity, uint32_t options, tain_t const *tto) </code> </h4> +<h4> <code> 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) </code> </h4> <p> 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. </p> <ul> <li> <em>ctx</em> is a pointer to a fully initialized context, connected to <em>fds</em>[2] and <em>fds</em>[3]. The TLS/SSL handshake does not have to be completed. </li> - <li> <em>fds</em> is an array of 5 file descriptors, in this + <li> <em>fds</em> 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. </li> - <li> <em>pid</em> 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 <em>pid</em>, then the function -returns as soon as it doesn't have anything left to write to -the network peer. </li> - <li> <em>verbosity</em> defines the engine's verbosity: the -higher the more verbose. This parameter is currently ignored. </li> +ciphertext, fd writing ciphertext. </li> + <li> <em>tto</em> is a pointer to a + <a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_t</a> +containing a relative time (i.e. a timeout) If *<em>tto</em> time elapses +with no application data being exchanged, the engine will forcibly close the +connection (with the method defined by <tt><em>options</em> & 1</tt>). + You can use <tt>&tain_infinite_relative</tt> as a value for <em>tto</em> +if you don't want the engine to ever timeout. </li> <li> <em>options</em> is a bitfield. <ul> <li> 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. </li> </ul> </li> - <li> <em>tto</em> is a pointer to a - <a href="//skarnet.org/software/skalibs/libstddjb/tai.html">tain_t</a> -containing a relative time (i.e. a timeout) If *<em>tto</em> time elapses -with no application data being exchanged, the engine will forcibly close the -connection (with the method defined by <tt><em>options</em> & 1</tt>). - You can use <tt>&tain_infinite_relative</tt> as a value for <em>tto</em> -if you don't want the engine to ever timeout. </li> + <li> <em>verbosity</em> defines the engine's verbosity: the +higher the more verbose. This parameter is currently ignored. </li> + <li> <em>cb</em> 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: <em>ctx</em> (a pointer to the current bearssl context), +and <em>cbarg</em> (a pointer to a caller-provided structure). </li> + <li> <em>cbarg</em> is a pointer to a structure provided by the caller. +It will be passed as a second argument to <em>cb</em> when the TLS +handshake has successfully completed. </li> </ul> <p> <tt>sbearssl_run</tt> 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, <tt>sbearssl_run</tt> returns the <em>wstat</em> -for that subprocess, i.e. the integer containing the information about -its exit code or crash signal. No matter how <tt>sbearssl_run</tt> returns, -the first four descriptors in <em>fds</em> are closed, but the -selfpipe is untouched and the caller should free <em>ctx</em> itself. +SSL/TLS connection closed cleanly, the process exits 0. </p> -<h4> <code> 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) </code> </h4> +<h3> Initializing and running the engine </h3> + +<h4> <code> 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) </code> </h4> + +<p> + This function initializes a TLS context for a client-side connection, +then runs the TLS engine via a call to <tt>sbearssl_run()</tt>. The +function does not return. +If the context cannot be initialized, the process exits 96 with an +appropriate error message. +</p> + +<p> + If the <tt>CADIR</tt> 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 <tt>CAFILE</tt> +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. +</p> <p> - This function implements <a href="../s6-tlsc.html">s6-tlsc</a> on top of BearSSL. -It has no other practical purpose; you're better off directly invoking -<a href="../s6-tlsc.html">s6-tlsc</a>. + The arguments are as follows: </p> -<h4> <code> 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) </code> </h4> +<ul> + <li> <tt>fds</tt> : 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. </li> + <li> <tt>preoptions : a bitfield. + <ul> + <li> Bit 0: if clear, no client authentication is performed. If set, +the <tt>CERTFILE</tt> and <tt>KEYFILE</tt> 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. <strong>This feature is currently +unsupported and will not work; leave that bit clear for now.</strong> </li> + </ul> </li> + <li> <tt>options : a bitfield, which will be passed to +<tt>sbearssl_run()</tt>. + <ul> + <li> 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. </li> + </ul> </li> + <li> <em>verbosity</em> defines the engine's verbosity: the +higher the more verbose. This parameter is currently ignored. </li> + <li> <tt>servername</tt> : the server name used for SNI. If NULL, then +no SNI is performed, which may be a security risk. </li> + <li> <tt>cb</tt> : a pointer to a callback function, that will be +passed as is to <tt>sbearssl_run()</tt>. </li> + <li> <tt>notif</tt> : an unsigned integer that will be embedded into +the <em>cbarg</em> structure that will be passed to <tt>sbearssl_run()</tt>. +It is used by <a href="../s6-tlsc-io.html">s6-tlsc-io</a> to identify a +valid fd on which to write SSL data information once the handshake has +completed. </li> +</ul> + +<h4> <code> 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) </code> </h4> <p> - This function implements <a href="../s6-tlsd.html">s6-tlsd</a> on top of BearSSL. -It has no other practical purpose; you're better off directly invoking -<a href="../s6-tlsd.html">s6-tlsd</a>. + Same as the previous function, but on the server side. No <em>servername</em> +argument is required. The <tt>CERTFILE</tt> and <tt>KEYFILE</tt> environment +variables are mandatory, they point to the server's certificate and private +key. It is only necessary to set <tt>CADIR</tt> or <tt>CAFILE</tt> when bit +0 of <em>preoptions</em> is set <strong>(this functionality <em>is</em> supported server-side)</strong>, +in which case client authentication will be +requested, and a list of trust anchors (read from either the directory +in <tt>CADIR</tt> or the PEM file in <tt>CAFILE</tt>) will be used to verify +the client certificate. </p> </body> |