summaryrefslogtreecommitdiff
path: root/doc/libsbearssl
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2017-03-22 21:37:30 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2017-03-22 21:37:30 +0000
commitdddbfab568d42e443f102d35c84432824cc59fee (patch)
tree4983b1f5b44f861a3abc60ba7d47476820fcbb2f /doc/libsbearssl
parent6278e21405c40df65f8de6a9799576d1eb346164 (diff)
downloads6-networking-dddbfab568d42e443f102d35c84432824cc59fee.tar.xz
Fix case where s6-tls[cd] would sometimes not detect an application and remain there forever with its zombie, both condemned to err in limbo for all eternity, the living and the dead, hand in hand
Diffstat (limited to 'doc/libsbearssl')
-rw-r--r--doc/libsbearssl/index.html26
1 files changed, 16 insertions, 10 deletions
diff --git a/doc/libsbearssl/index.html b/doc/libsbearssl/index.html
index 1c797c7..20cdb06 100644
--- a/doc/libsbearssl/index.html
+++ b/doc/libsbearssl/index.html
@@ -473,23 +473,28 @@ i.e. a <tt>tai_t</tt> plus nanoseconds (which are simply ignored).
<h3> Running the TLS/SSL engine (both clients and servers) </h3>
-<h4> <code> int sbearssl_run (br_ssl_engine_context *ctx, int *fds, unsigned int verbosity, uint32_t options, tain_t const *tto) </code> </h4>
+<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>
<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).
+with EOF) or a given subprocess dies.
</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 4 file descriptors, in this
+ <li> <em>fds</em> is an array of 5 file descriptors, in this
order: fd reading clear text, fd writing clear text, fd reading
-ciphertext, fd writing ciphertext. </li>
+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>
<li> <em>options</em> is a bitfield.
@@ -520,12 +525,13 @@ if you don't want the engine to ever timeout. </li>
<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 0. If a SSL/TLS-level
-error occurred, it returns nonzero; a corresponding error message for the
-return value can be obtained via <tt>sbearssl_error_str()</tt>.
-All four descriptors in <em>fds</em> are closed when
-<tt>sbearssl_run</tt> returns.
+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.
</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>