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
178
179
180
181
|
<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-tlsd program</title>
<meta name="Description" content="s6-networking: the s6-tlsd program" />
<meta name="Keywords" content="s6-networking s6-tlsd tlsd tls ssl ucspi tcp inet network tcp/ip server" />
<!-- <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-tlsd</tt> program </h1>
<p>
<tt>s6-tlsd</tt> is a program that performs the server side of
a TLS or SSL 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>
<p>
<a href="index.html">s6-networking</a> does not include
cryptographic software. All the crypto used in <tt>s6-tlsd</tt>
is provided by the chosen SSL backend:
<a href="https://bearssl.org/">BearSSL</a> or
<a href="https://www.libressl.org/">LibreSSL</a>, depending on
the options given when configuring <tt>s6-networking</tt>.
</p>
<h2> Interface </h2>
<pre>
s6-tlsd [ -S | -s ] [ -Y | -y ] [ -Z | -z ] [ -v <em>verbosity</em> ] [ -K <em>kimeout</em> ] [ -k <em>snilevel</em> ] [ -- ] <em>prog...</em>
</pre>
<ul>
<li> s6-tlsd expects to have an open TCP connection it
can talk to on its stdin (for reading) and stdout
(for writing). </li>
<li> It spawns a <a href="s6-tlsd-io.html">s6-tlsd-io</a>
child process that will be the server-side of a TLS connection,
perform the handshake (expecting a TLS client on the other side
of the network) and maintain the TLS tunnel. </li>
<li> When notified by <a href="s6-tlsd-io.html">s6-tlsd-io</a>
that the handshake has completed, s6-tlsd 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-tlsd does not exit, but execs
into <em>prog...</em> instead.
</p>
<h2> Environment variables </h2>
<h3> Read </h3>
<p>
s6-tlsd does not expect to have any particular
environment variables, but it spawns a
<a href="s6-tlsd-io.html">s6-tlsd-io</a> program that does.
So it should pay attention to the following variables:
</p>
<ul>
<li> <tt>KEYFILE</tt> and <tt>CERTFILE</tt>. Also (or alternatively),
if the <tt>-k</tt> option is given: a series of
<tt>KEYFILE:<em>x</em></tt> and <tt>CERTFILE:<em>x</em></tt> variables,
for every <em>x</em> in the set of server names </li>
<li> (if the -y or -Y option has been given) <tt>CADIR</tt> or <tt>CAFILE</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, KEYFILE:<em>x</em> and CERTFILE:<em>x</em> for
every <em>x</em>, TLS_UID and TLS_GID. They're passed to
the <a href="s6-tlsd-io.html">s6-tlsd-io</a> child but
not to <em>prog...</em>;
the <tt>-Z</tt> option keeps them accessible in <em>prog...</em> as well.
</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 the required SNI
server name, if any. It is removed from the environment if no SNI
has been sent by the client. </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-tlsd-io.html">s6-tlsd-io</a>
before execing <em>prog...</em>. </li>
<li> <tt>-z</tt> : clean the environment of
the variables used by <a href="s6-tlsd-io.html">s6-tlsd-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> : Request an optional client certificate. </li>
<li> <tt>-y</tt> : Request a mandatory client certificate.
The default, with neither the <tt>-Y</tt> nor the <tt>-y</tt> option,
is not to request a client certificate at all. </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>-k <em>snilevel</em></tt> : support alternative
certificate chains for SNI. If <em>snilevel</em> is nonzero, private
key file names are read from every environment variable of the form
<tt>KEYFILE:<em>x</em></tt>, where <em>x</em> is a server name that
the client may require, and a corresponding certificate chain for the name
<em>x</em> should exist in the file named after the contents of the
<tt>CERTFILE:<em>x</em></tt> environment variable. If <em>snilevel</em>
is 2 or more, <em>only</em> those files are read, and the generic
<tt>KEYFILE</tt> and <tt>CERTFILE</tt> variables are ignored.
If <em>snilevel</em> is 0, or if the option is not given, which is the
default, <tt>KEYFILE</tt> and <tt>CERTFILE</tt> are the only private
key / certificate chain pair that are loaded, no other environment
variable is read for keypairs. </li>
</ul>
<h2> Notes </h2>
<ul>
<li> The goal of the <tt>s6-tlsd</tt> interface (and its
client-side companion <a href="s6-tlsc.html">s6-tlsc</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>
|
