diff options
Diffstat (limited to 'doc/s6-ucspitlsc.html')
| -rw-r--r-- | doc/s6-ucspitlsc.html | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/doc/s6-ucspitlsc.html b/doc/s6-ucspitlsc.html new file mode 100644 index 0000000..4c1d2be --- /dev/null +++ b/doc/s6-ucspitlsc.html @@ -0,0 +1,178 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>s6-networking: the s6-ucspitlsc program</title> + <meta name="Description" content="s6-networking: the s6-ucspitlsc program" /> + <meta name="Keywords" content="s6-networking s6-ucspitlsc tlsc tls ssl ucspi ucspi-tls delayed encryption opportunistic tls tcp inet network tcp/ip client" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">s6-networking</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>s6-ucspitlsc</tt> program </h1> + +<p> +<tt>s6-ucspitlsc</tt> is a client-side program that establishes +communication channels according to the UCSPI-TLS protocol, +then execs into an application. Later, if the application sends +a command, a TLS tunnel will be started and the application will +be able to use it instead of communicating with the network via +cleartext. +</p> + +<p> + The point of this protocol, and this program, is to make it easy +to implement commands like SMTP's STARTTLS without embedding a +TLS stack in the client itself. +</p> + +<h2> Interface </h2> + +<pre> + s6-ucspitlsc [ -S | -s ] [ -Y | -y ] [ -Z | -z ] [ -v <em>verbosity</em> ] [ -K kimeout ] [ -k <em>servername</em> ] [ -6 <em>rfd</em> ] [ -7 <em>wfd</em> ] [ -- ] <em>prog...</em> +</pre> + +<ul> + <li> s6-ucspitlsc expects to have an open TCP connection it +can talk to on its (by default) descriptors 6 (for reading) +and 7 (for writing). </li> + <li> It forks and establishes communication channels between +the parent and the child. The parent executes into +<em>prog...</em>; the child remains and waits for a +command. </li> + <li> At any time, <em>prog...</em> can send a command to its +control socket provided by s6-ucspitlsc, following the +<a href="https://web.archive.org/web/20150311223933/http://www.suspectclass.com/sgifford/ucspi-tls/ucspi-tls.txt">UCSPI-TLS</a> +protocol. Then the s6-ucspitlsc child will exec into a +<a href="s6-tlsc-io.html">s6-tlsc-io</a> +process that will initiate the TLS connection, perform the +handshake (expecting a TLS server on the other side of the +network) and maintain a TLS tunnel. <em>prog</em> can +use that TLS tunnel instead of talking directly to the +network. </li> +</ul> + +<h2> Exit codes </h2> + +<ul> + <li> 100: wrong usage. </li> + <li> 111: system call failed. </li> +</ul> + +<p> + Normally the parent s6-ucspitlsc process execs into <em>prog...</em> +and the child process execs into <a href="s6-tlsc-io.html">s6-tlsc-io</a>. +If the parent dies or closes its control socket before sending a +command to start TLS, the child exits 0. +</p> + +<h2> Environment variables </h2> + +<h3> Read </h3> + +<p> + s6-ucspitlsc does not expect to have any particular +environment variables, but it spawns a +<a href="s6-tlsc-io.html">s6-tlsc-io</a> program that does. +So it should pay attention to the following variables: +</p> + +<ul> + <li> <tt>CADIR</tt> or <tt>CAFILE</tt> </li> + <li> (if the -y option has been given) <tt>CERTFILE</tt> and <tt>KEYFILE</tt> </li> + <li> <tt>TLS_UID</tt> and <tt>TLS_GID</tt> +</ul> + +<h3> Written </h3> + +<p> + By default, <em>prog...</em> is run with all these +variables <em>unset</em>: CADIR, CAFILE, +KEYFILE, CERTFILE, TLS_UID and TLS_GID. They're passed to +the <a href="s6-tlsc-io.html">s6-tlsc-io</a> child but +not to <em>prog...</em>. +The <tt>-Z</tt> option prevents that behaviour. +</p> + +<p> + However, <em>prog...</em> is run with the following additional +environment variables, following the UCSPI-TLS protocol: +</p> + +<ul> + <li> <tt>SSLCTLFD</tt> contains the file descriptor number of +the control socket. </li> + <li> <tt>SSLREADFD</tt> contains the file descriptor number of +the pipe used to read data from the TLS tunnel after it +has been activated. </li> + <li> <tt>SSLWRITEFD</tt> contains the file descriptor number of +the pipe used to write data to the TLS tunnel after it +has been activated. </li> +</ul> + +<p> + Since <em>prog</em> is exec'ed before the TLS handshake takes +place, it cannot get information about the TLS connection via +environment variables. However, if it starts the TLS connection +via a <tt>Y</tt> command (as opposed to a <tt>y</tt> command), +it will receive this information as a string sent over the +control socket. +</p> + +<h2> Options </h2> + +<ul> + <li> <tt>-v <em>verbosity</em></tt> : Be more or less +verbose. Default for <em>verbosity</em> is 1. 0 is quiet, 2 is +verbose, more than 2 is debug output. This option currently has +no effect. </li> + <li> <tt>-Z</tt> : do not clean the environment of +the variables used by <a href="s6-tlsc-io.html">s6-tlsc-io</a> +before execing <em>prog...</em>. </li> + <li> <tt>-z</tt> : clean the environment of +the variables used by <a href="s6-tlsc-io.html">s6-tlsc-io</a> +before execing <em>prog...</em>. This is the default. </li> + <li> <tt>-S</tt> : send a <tt>close_notify</tt> alert +and break the connection when <em>prog</em> sends EOF. </li> + <li> <tt>-s</tt> : transmit EOF by half-closing the TCP +connection without using <tt>close_notify</tt>. This is the default. </li> + <li> <tt>-Y</tt> : Do not send a client certificate. This is the default. </li> + <li> <tt>-y</tt> : Send a client certificate. </li> + <li> <tt>-k <em>servername</em></tt> : use Server Name +Indication, and send <em>servername</em>. The default is not to +use SNI, which may be a security risk. </li> + <li> <tt>-K <em>kimeout</em></tt> : close the connection +if <em>kimeout</em> milliseconds elapse without any data being +received from either side. The default is 0, which means +infinite timeout (never kill the connection). </li> + <li> <tt>-6 <em>fdr</em></tt> : expect an open file +descriptor numbered <em>fdr</em> to read network (ciphertext) +data from. Make sure <em>prog</em> also reads its data +from its own fd <em>fdr</em>. Default is 6. </li> + <li> <tt>-7 <em>fdw</em></tt> : expect an open file +descriptor numbered <em>fdw</em> to write network (ciphertext) +data to. Make sure <em>prog</em> also writes its data to +its own fd <em>fdw</em>. Default is 7. </li> +</ul> + +<h2> Notes </h2> + +<ul> + <li> It only makes sense to run s6-ucspitlsc if its application +program <em>prog</em> knows and understands the +<a href="https://web.archive.org/web/20150311223933/http://www.suspectclass.com/sgifford/ucspi-tls/ucspi-tls.txt">UCSPI-TLS</a> +protocol for opportunistic TLS. If it does not, you will not +be able to secure your connection, and what you need is a regular +immediate TLS program instead, which means +<a href="s6-tlsc.html">s6-tlsc</a>. </li> +</ul> + +</body> +</html> |