1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<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 an
<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. </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
the handshake takes more than <em>kimeout</em> milliseconds to complete.
The default is 0, which means infinite timeout: let the handshake complete
at its own pace, no matter how slow. </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>
|
