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
|
<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-tlsc program</title>
<meta name="Description" content="s6-networking: the s6-tlsc program" />
<meta name="Keywords" content="s6-networking s6-tlsc tlsc tls ssl ucspi 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-tlsc</tt> program </h1>
<p>
<tt>s6-tlsc</tt> is a program that establishes a TLS or SSL
client connection over an existing TCP connection, then execs
into an application. It is meant to make network communications
secure even for applications that do not natively support
TLS/SSL.
</p>
<h2> Interface </h2>
<pre>
s6-tlsc [ -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-tlsc 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 spawns an <a href="s6-tlsc-io.html">s6-tlsc-io</a>
child process that will initiate the TLS connection, perform the
handshake (expecting a TLS server on the other side of the
network) and maintain the TLS tunnel. </li>
<li> When notified by <a href="s6-tlsc-io.html">s6-tlsc-io</a>
that the handshake has completed, s6-tlsc execs into
<em>prog...</em>. </li>
</ul>
<h2> Exit codes </h2>
<ul>
<li> 100: wrong usage. </li>
<li> 111: system call failed. </li>
</ul>
<p>
If everything goes smoothly, s6-tlsc does not exit, but execs
into <em>prog...</em> instead.
</p>
<h2> Environment variables </h2>
<h3> Read </h3>
<p>
s6-tlsc does not expect to have any particular
environment variables, but it spawns an
<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:
</p>
<ul>
<li> <tt>SSL_PROTOCOL</tt> contains the protocol version:
TLSv1, TLSv1.1, TLSv1.2... </li>
<li> <tt>SSL_CIPHER</tt> contains the name of the cipher
used. </li>
<li> <tt>SSL_TLS_SNI_SERVERNAME</tt> contains <em>servername</em>,
if the <tt>-k</tt> option has been given; otherwise it is removed
from the environment. </li>
<li> <tt>SSL_PEER_CERT_HASH</tt> contains the hash of the peer's
End Entity certificate, prefixed by the name of the hash and a colon
(typically <tt>SHA256:</tt>). </li>
<li> <tt>SSL_PEER_CERT_SUBJECT</tt> contains the decoded subjectDN
of the peer's End Entity certificate, i.e. identifying information.
What is traditionally called the "name" of the certificate is the
CN field in that data. </li>
<li> More similar environment variables containing information
about the connection may be added in the future. </li>
</ul>
<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> : if the handshake takes
more than <em>kimeout</em> milliseconds to complete, close the connection.
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> The goal of the s6-tlsc interface (and its
server-side companion <a href="s6-tlsd.html">s6-tlsd</a>) is to
make it so that if you have a client, run by the command line
<tt>client...</tt> that speaks a cleartext protocol to a server
run by the command line <tt>server...</tt>, then if the server
has the proper private key and certificate, and the client has
the proper list of trust anchors, you can just change the
client command line to <tt>s6-tlsc client...</tt> and the
server command line to <tt>s6-tlsd server...</tt>
without changing the client or the server themselves, and the
communication between them will be secure. </li>
</ul>
</body>
</html>
|
