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
|
<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 kimeout ] [ -- ] <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> </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, 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 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> 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> : Require an optional client certificate. </li>
<li> <tt>-y</tt> : Require a mandatory client certificate.
The default, with neither the <tt>-Y</tt> nor the <tt>-y</tt> option,
is not to require a client certificate at all. </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>
</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>
|
