4 This explains how to install the TLS pool daemon, and how to play with the
5 test/demo programs for the client and server side.
11 Runtime dependencies are:
13 * libgnutls >= 3.4.4 for TLS handling (that implies libnettle-2.7)
14 * p11-kit >= 0.22.1 for PKCS #11 URI handling
15 * libdb >= 4.0 for key->value lookup with BerkeleyDB transactions/replication
16 * libtasn1 for parsing of BER and DER data structures
17 * libldns for DNS lookups
18 * libunbound for more DNS lookups
19 * Quick-DER >= 1.2.3 for DER manipulation
20 * libkrb5 for Kerberos support
21 * NOT-YET: libldap for LDAP lookups
22 * NOT-YET: libmemcached for caching of intermediate results
23 * NOT-YET: libradius to do additional authn / authz [/acct]
24 * the PKCS #11 implementation of your choice (for easy entrance: softhsm)
26 Include the development variants if your aim is to build your own TLS Pool.
28 TODO: We should probably consider build variations to avoid requiring all
29 these dependencies when only a bit is kwown to be required. That's the
30 sort of maturity that this project has not reached yet.
36 As a **sugestion** only, here are packages you should have installed
37 before trying to build TLSPOOL.
40 - libdb-dev libldns-dev libunbound-dev libkrb5-dev
41 - libgnutls-dev (you'll need one with DANE support)
46 Create a user and group "tlspool" if you wish to drop privileges to a
49 Use the common building approach:
55 When your purpose is to test, you will also need a PKCS #11 store for your
56 private keys. Then you can fill PKCS #11 and the databases.
62 There are three sub-targets with their own Makefiles:
64 * src/* hosts the daemon, which is an executable named "tlspool"
65 * lib/* hosts the stub library for applications, and provides:
66 - "libstarttls.a" and "libstarttls.so" to append to applications
67 - "tlspool.py" is similar, but used with Python
68 * tool/* hosts a few demonstration applications, and provides:
69 - "testcli" and "testsrv" test/demo apps, for line-based chat
70 - "tlstunnel" as a plaintext-to-TLS or TLS-to-plaintext passthrough
71 - "webclientdemo.py" and "webserverdemo.py" are Python demonstrations
72 - "lidsel" and "pinentry" plug into the TLS Pool's localid and PIN services
73 - "https_proxy.py" demonstrates an intervening HTTPS proxy
75 The main directory "make" will also make all these subdirectory projects.
81 The source package includes a "testdata" directory that can be filled
82 with databases that you can use for a quick and dirty test. You will
83 need to setup a PKCS #11 repository; we suggest to use SoftHSMv2 from the
84 OpenDNSSEC project to get started, you can always try hardware-based
85 tokens later on. The idea of PKCS #11 is that such choices are pluggable.
87 To create a SoftHSM token, you can use the following command::
89 softhsm2-util --init-token --free --label 'TLS_Pool_dev_data'
91 This label is configured in the default configuration for the TLS Pool.
92 The default configuration works with a PIN 1234; you can choose any
95 You can now build the private keys and from that, certificates that go
101 (If it fails, please run it again.)
102 The databases may also be rebuilt using the Makefile in the directory,
103 there are rebuild- clean- and fill- targets for -pkcs11, -cert, -pgp and
104 -db that will do this for you. Note that rebuilding PKCS #11 is heavy,
105 it wipes your private key and possibly even the store.
107 The PKCS #11 data may not be available to your TLS Pool if it runs under
108 another user, such as the default setup for daemon user "tlspool". If
109 that is the case, you may need to locate your PKCS #11 store and run
110 the command; this is for SoftHSMv2::
113 chown -R tlspool:tlspool testdata
115 chown -R tlspool:tlspool /var/lib/softhsm/tokens/XXX
117 To setup Kerberos authentication, you need to install the basic package,
118 usually named `krb5-user` or `krb5-client`, depending on your distro.
119 In `/etc/krb5.conf`, be sure to have this entry to guide the test
120 domain names to our KDC::
123 # ...other entries...
124 tlspool.arpa2.lab = ARPA2.NET
126 The following test demonstrates proper working of the TLS Pool based on
127 the testdata and under the warnings above:
131 ./tlspool -kc ../etc/tlspool.conf
141 This will setup a TLS connection over localhost:12345 and provide a simple
142 line-by-line chat session between terminals 2 and 3, while showing debugging
143 output from the TLS Pool in terminal 1. The test client and server are
144 written to test more functionality as well, and they show some of it too,
145 namely key agreement based on the master key, which show as matching
146 "PRNG bytes" in terminals 2 and 3.
148 A somewhat more complicated test is to actually wrap an existing service
152 ./tlspool -kc ../etc/tlspool.conf
153 ../tool/tlstunnel -s -l [::1]:22335 -L testsrv@tlspool.arpa2.lab -r [2001:db8::1234]:80
154 ../tool/tlstunnel -c -l [::1]:22334 -L testcli@tlspool.arpa2.lab -r [::1]:22335 -R testsrv@tlspool.arpa2.lab
157 The `tlspool` binary is the TLS Pool itself.
159 The `tlstunnel -s` is a server-side TLS unwrapper. It receives TLS traffic
160 on `[::1]:22335`, uses the TLS Pool to unwrap it, and forwards the traffic
161 to `[2001:db8::1234]:80`, which is a non-existent address but could be replaced
162 by something like a web server. You should provide your own
163 IPv6 server address of choice. Note that backward compatibility with IPv4
164 is available. The identity of the server is `testsrv@tlspool.arpa2.lab`
165 and that is all that the tunnel needs to know; it will ask the TLS Pool to
166 fill in the credentials belonging to this identity.
168 The `tlstunnel -c` is a client-side TLS wrapper. It receives plaintext
169 traffic on `[::1]:22334`, uses the TLS Pool to wrap it in TLS, and forwards
170 the traffic to `[::1]:22335`, which was not quite coincidentally configured
171 before as a TLS-unwrapping server. The client needs to know both its local
172 identity, `testcli@tlspool.arpa2.lab`, as the server's. The local identity
173 is used to access the client credentials, as was done on the server, and the
174 remote identity is used to determine if the client identity may be disclosed
175 to this server; furthermore, the identity is used for TLS' Server Name
176 Indication, which helps with virtual hosting of TLS-secured websites. (And
177 only websites, really, as all other protocols have embraced a `STARTTLS`
178 method -- it is mostly everyone's popular protocol in the World that has become
181 It is admittedly silly to run the client and server on the same machine, but
182 it serves as a quick test, and isolates any networking trouble that might
183 creep up in a distributed test.
185 The identities shown here are in fact a bit silly for a website, which does
186 not normally use a `user@` part --another thing in which the web is lagging
187 behind other protocols-- but the applications don't mind that because they
188 are not aware if the application used is a web server. It is assumed that
189 the application would not supply silly identifiers in a real setup.
191 Finally, and perhaps smashingly, this simple demonstration already shows a
192 power of the TLS Pool: both client and server are capable of using credentials
193 in the X.509 and OpenPGP formats. WireShark should show you that the client
194 offers both `cert_type` values in an extension, and the server selects one
195 that it likes. If the server prefers to use OpenPGP then your luck with
196 WireShark may change; at the time of this writing, even the newest versions
197 are unable to decode the OpenPGP certificate type. As a result, a perfectly
198 good exchange will cry for attention in WireShark, assuming packet formatting
202 Trusting well-known CAs
203 -----------------------
205 By default, the testdata is not setup to trust any well-known CA certificate.
206 We did however sample a Debian distribution of CA certificates, and installed
207 it under testdata -- where it will NOT BE KEPT UP-TO-DATE.
209 If you choose to rely on these CA's and need it for testing purposes, you can
215 Once more, TRUST THIS ONLY FOR TESTING PURPOSES -- use a proper distrubution
216 mechanism such as your OS or perhaps ARPA2 SteamWorks for anything that should
217 withstand the pressure of an Internet whose intent is in part criminal.
219 This is the reason why it must be installed as an explicit choice. We made it
220 really easy to install, but also won't keep the set secure.
226 The tlspool daemon can be run against a configfile of choice, which must
227 be explicitly configured. My suggestion is to standardise on
228 /etc/tlspool.conf so the normal script would implement actions with:
230 * "start" through "tlspool -c /etc/tlspool.conf"
231 * "stop" through "killall `cat /var/run/tlspool.pid`"
232 * "restart" through "tlspool -kc /etc/tlspool.conf"
234 The -k option indicates that any older TLS pool daemon should be kicked
235 out, if it exists. This will remove its locks on the PID file and sockets.
236 At present, this will also break off any existing connections. This also
237 assumes that the PID file is set to /var/run/tlspool.pid and although not
238 visible here, the socket's default location is /var/run/tlspool.sock
240 When running the TLS pool as a user without root privileges, a few things
241 need to be different than in the default configuration:
243 * "daemon_pidfile" should be in the user's area of control
244 * "socket_user" and "socket_group" should probably not be set
245 * "daemon_chroot" cannot be used
246 * "daemon_user" and "daemon_group" should probably not be set
247 * "socket_path" and "daemon_pidfile" should be in the user's area
248 * "memcache_host" should normally not be used
249 * "pkcs11_path" may be setup for a personally held token device
250 * "radius_XXX" should normally not be used
252 We could support a setup with defaults like ~/.tlspool/tlspool.conf for
253 the configuration, ~/.tlspool/tlspool.pid for the PID file and
254 ~/.tlspool/tlspool.sock for the socket. Note that it can make a lot of
255 sense to run your own TLS pool within your user account, to avoid
256 sharing access to your PKCS #11 credentials with others. But doing so
257 will not automatically incorporate it in system-wide key management
270 Assuming that the TLS pool daemon started successfully, the only thing
271 that clients and servers need to do is to connect to it and ask it to
272 STARTTLS over a given file descriptor or socket, and return another one
273 to replace it. This is implemented in the stub library, for which the
274 testcli and testsrv programs form a test client and test server,
277 The test programs are best started in their own terminals, so their
278 input and output does not confuse you. The server starts as any
279 normal server, creating a listening socket and waiting for input.
280 We have hardcoded address ::1 or localhost and port 12345 into the
281 test software. When the client connects, each immediately calls
282 the STARTTLS operation from their perspective; one starts a TLS client
283 connection and the other a TLS server connection. Then, typed lines
284 are passed from one to the other, going through the TLS pool which
285 takes care of the TLS encryption on the sending side, and the TLS
286 decryption on the other end.
288 The TLS pool takes care of authentication, authorization and, if so
289 desired, even accounting. The basic mode of authentication comes down
290 to validating certificates as proper online identitites, using such
291 technologies as LDAP, DANE and DNSSEC. External RADIUS tools can be
292 added to expand on this, and flag bits may also prove helpful to
293 modify the TLS pool behaviour in predetermined manners.
295 The TLS pool also handles teardown in all its forms with grace; that
296 is, it will detect it immediately and notify the other side.
302 The TLS Pool protocol is published and can be implemented in any language
303 that prefers to work at that level. It is important to understand that the
304 format may change with future versions however, and that would cause some
305 dismay related to versioning. We promise to confine API changes to major
306 versions only to make this somewhat bearable.
308 The golden way is to instead rely on the C library, built in lib/* and
309 installed for linking with a "-ltlspool" argument. We also provide a
310 .pc file for use with pkg-config.
312 Based on this C library, we build wrappers for other languages, usually
313 going through SWIG. If you desire a library, please build it separately
316 make -C lib/python all install
317 make -C lib/go all install
319 and so on. Some of the libraries may not have been completed yet, in that
320 case you will run into difficulties. These libraries are neither built
321 nor installed as part of the normal (main directory) builds! Only the
322 C library is made and/or installed by default.