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
|
<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-tlsclient program</title>
<meta name="Description" content="s6-networking: the s6-tlsclient program" />
<meta name="Keywords" content="s6-networking s6-tlsclient tlsclient 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-tlsclient</tt> program </h1>
<p>
<tt>s6-tlsclient</tt> is an
<a href="https://cr.yp.to/proto/ucspi.txt">UCSPI client tool</a> for
TLS/SSL connections over INET domain sockets. It establishes a TCP
connection to a server and a TLS transport over it,
then executes into a program.
</p>
<h2> Interface </h2>
<pre>
s6-tlsclient [ <em>options</em> ] [ -- ] <em>host</em> <em>port</em> <em>prog...</em>
</pre>
<ul>
<li> s6-tlsclient rewrites itself into a command line
involving:
<ul>
<li> <a href="s6-tcpclient.html">s6-tcpclient</a>, which
establishes a TCP connection to host <em>host</em> port <em>port</em>. </li>
<li> <a href="s6-tlsc.html">s6-tlsc</a>, which establishes
a TLS transport (client-side) over that connection. </li>
<li> <em>prog...</em>, your client program, which is executed into by
<a href="s6-tlsc.html">s6-tlsc</a> once the
<a href="s6-tlsc-io.html">s6-tlsc-io</a> child it has spawned has
set up the TLS connection and performed the handshake. </li>
</ul> </li>
<li> <em>prog...</em> is run with the same pid as s6-tlsclient. </li>
</ul>
<p>
<em>prog</em> is expected to read from its peer on
descriptor 6 and write to its peer on descriptor 7.
Since there will be a <a href="s6-tlsc-io.html">s6-tlsc-io</a>
program between <em>prog</em> and the network to perform
the TLS encryption/decryption, those descriptors will not
be a network socket - they will be pipes.
</p>
<h2> Server name determination for SNI </h2>
<p>
If the <tt>-H</tt> option is not given to <tt>s6-tlsclient</tt>,
then <em>host</em> will be used as the server name to verify.
You can use the <tt>-k</tt> option to override this default.
Please note that if you use the <tt>-H</tt> option and do not
provide a server name via <tt>-k</tt>, <strong>SNI will not be
used, which may be a security risk.</strong>
</p>
<h2> Environment variables </h2>
<h3> Read </h3>
<p>
The following variables should be set before invoking
<tt>s6-tlsclient</tt>, because they will be used by
<a href="s6-tlsc-io.html">s6-tlsc-io</a>:
</p>
<ul>
<li> CADIR </li>
<li> CAFILE (alternative to CADIR) </li>
<li> KEYFILE (if you're using a client certificate) </li>
<li> CERTFILE (if you're using a client certificate) </li>
<li> TLS_UID and TLS_GID (if you run <tt>s6-tlsclient</tt> as root) </li>
</ul>
<p>
Setting either CADIR or CAFILE is mandatory.
</p>
<h3> Written </h3>
<p>
<em>prog...</em> is run with the following variables added to,
or removed from, its environment by <a href="s6-tcpclient.html">s6-tcpclient</a>:
</p>
<ul>
<li> PROTO </li>
<li> TCPREMOTEIP </li>
<li> TCPREMOTEPORT </li>
<li> TCPREMOTEHOST </li>
<li> TCPLOCALHOST </li>
<li> TCPREMOTEINFO </li>
</ul>
<p>
Unless the <tt>-Z</tt> option is given to <tt>s6-tlsclient</tt>,
the CADIR, CAFILE, KEYFILE, CERTFILE, TLS_UID and TLS_GID
variables will not appear in <em>prog</em>'s environment.
</p>
<h2> Options </h2>
<p>
<tt>s6-tlsclient</tt> accepts a myriad of options, all of which are
passed as is to the correct executable. Not giving any options will
generally work: the defaults are sensible.
</p>
<h3> Options passed as is to s6-tcpclient </h3>
<ul>
<li> <tt>-q</tt>, <tt>-Q</tt>, <tt>-v</tt> : be quiet, normally verbose, or verbose </li>
<li> <tt>-4</tt>, <tt>-6</tt> : stick to IPv4 or IPv6 addresses </li>
<li> <tt>-d</tt>, <tt>-D</tt> : enable or disable Nagle's algorithm </li>
<li> <tt>-r</tt>, <tt>-R</tt> : enable or disable IDENT lookup </li>
<li> <tt>-h</tt>, <tt>-H</tt> : enable or disable DNS lookups </li>
<li> <tt>-l <em>localname</em></tt> : get the local name from the command line, not from a DNS lookup </li>
<li> <tt>-n</tt>, <tt>-N</tt> : qualify the host or not when resolving it </li>
<li> <tt>-t <em>timeout</em></tt> : global timeout on the connection attempt </li>
<li> <tt>-i <em>localip</em></tt>, <tt>-p <em>localport</em></tt> : force local socket parameters </li>
<li> <tt>-T <em>timeoutconn</em></tt> : configurable connection timeouts </li>
</ul>
<h3> Options passed as is to s6-tlsc </h3>
<ul>
<li> <tt>-Z</tt>, <tt>-z</tt> : keep or remove the <a href="s6-tlsc-io.html">s6-tlsc-io</a>-specific
variables from the application's environment </li>
<li> <tt>-S</tt>, <tt>-s</tt> : use close_notify or EOF to signal the end of a TLS connection </li>
<li> <tt>-J</tt>, <tt>-j</tt> : exit nonzero with an error message when the peer fails to close_notify, or ignore it </li>
<li> <tt>-Y</tt>, <tt>-y</tt> : don't send, or send, a client certificate </li>
<li> <tt>-k <em>servername</em></tt> : use SNI and provide a server name </li>
<li> <tt>-K <em>kimeout</em></tt> : set a timeout for the TLS handshake </li>
</ul>
<h2> Example </h2>
<p>
<code> CADIR=/etc/ssl/certs s6-tlsclient skarnet.org 443 s6-ioconnect </code>
</p>
<p>
This will open a connection to
<a href="https://skarnet.org/">the skarnet.org web server
over TLS</a> and verify its certificate via the trust anchors
listed in the <tt>/etc/ssl/certs</tt> directory. It will then
branch your terminal to it: try typing
<tt>GET / HTTP/1.0</tt> then hitting return twice.
</p>
</body>
</html>
|
