Runtime dependencies are:
- * libgnutls for TLS handling
+ * libgnutls >= 3.4.4 for TLS handling (that implies libnettle-2.7)
+ * p11-kit >= 0.22.1 for PKCS #11 URI handling
+ * libdb >= 4.0 for key->value lookup with BerkeleyDB transactions/replication
+ * libtasn1 for parsing of BER and DER data structures
* libldns for DNS lookups
- * libldap for LDAP lookups
- * libmemcached for caching of intermediate results
- * TODO: libradius to do additional authn / authz [/acct]
+ * libunbound for more DNS lookups
+ * Quick-DER >= 1.2.3 for DER manipulation
+ * libkrb5 for Kerberos support
+ * NOT-YET: libldap for LDAP lookups
+ * NOT-YET: libmemcached for caching of intermediate results
+ * NOT-YET: libradius to do additional authn / authz [/acct]
+ * the PKCS #11 implementation of your choice (for easy entrance: softhsm)
-Include the development variants if your aim is to build it yourself.
+Include the development variants if your aim is to build your own TLS Pool.
TODO: We should probably consider build variations to avoid requiring all
these dependencies when only a bit is kwown to be required. That's the
sort of maturity that this project has not reached yet.
-First-time setup
+Build Packages
+--------------
+
+As a **sugestion** only, here are packages you should have installed
+before trying to build TLSPOOL.
+
+ - Debian
+ - libdb-dev libldns-dev libunbound-dev libkrb5-dev
+ - libgnutls-dev (you'll need one with DANE support)
+
+First-time build
----------------
Create a user and group "tlspool" if you wish to drop privileges to a
separate account.
+Use the common building approach:
+
+ ./configure
+ make
+ make install
+
+When your purpose is to test, you will also need a PKCS #11 store for your
+private keys. Then you can fill PKCS #11 and the databases.
-Building
---------
-There is no ./configure, because automake and such tend to clutter
-development and Makefile readability. If you'd care to donate one
-of these confusing structures, talk to me and I'll probably let you.
+Build details
+-------------
-There are two sub-targets with their own Makefiles:
+There are three sub-targets with their own Makefiles:
* src/* hosts the daemon, which is an executable named "tlspool"
* lib/* hosts the stub library for applications, and provides:
- "libstarttls.a" and "libstarttls.so" to append to applications
+ - "tlspool.py" is similar, but used with Python
+ * tool/* hosts a few demonstration applications, and provides:
- "testcli" and "testsrv" test/demo apps, for line-based chat
+ - "tlstunnel" as a plaintext-to-TLS or TLS-to-plaintext passthrough
+ - "webclientdemo.py" and "webserverdemo.py" are Python demonstrations
+ - "lidsel" and "pinentry" plug into the TLS Pool's localid and PIN services
+ - "https_proxy.py" demonstrates an intervening HTTPS proxy
+
+The main directory "make" will also make all these subdirectory projects.
+
+
+Testing
+-------
-You should simpy "make" in each of the directories.
+The source package includes a "testdata" directory that can be filled
+with databases that you can use for a quick and dirty test. You will
+need to setup a PKCS #11 repository; we suggest to use SoftHSMv2 from the
+OpenDNSSEC project to get started, you can always try hardware-based
+tokens later on. The idea of PKCS #11 is that such choices are pluggable.
+
+To create a SoftHSM token, you can use the following command::
+
+ softhsm2-util --init-token --free --label 'TLS_Pool_dev_data'
+
+This label is configured in the default configuration for the TLS Pool.
+The default configuration works with a PIN 1234; you can choose any
+SO-PIN you like.
+
+You can now build the private keys and from that, certificates that go
+into the databases::
+
+ cd testdata
+ make
+
+(If it fails, please run it again.)
+The databases may also be rebuilt using the Makefile in the directory,
+there are rebuild- clean- and fill- targets for -pkcs11, -cert, -pgp and
+-db that will do this for you. Note that rebuilding PKCS #11 is heavy,
+it wipes your private key and possibly even the store.
+
+The PKCS #11 data may not be available to your TLS Pool if it runs under
+another user, such as the default setup for daemon user "tlspool". If
+that is the case, you may need to locate your PKCS #11 store and run
+the command; this is for SoftHSMv2::
+
+ useradd tlspool
+ chown -R tlspool:tlspool testdata
+
+ chown -R tlspool:tlspool /var/lib/softhsm/tokens/XXX
+
+To setup Kerberos authentication, you need to install the basic package,
+usually named `krb5-user` or `krb5-client`, depending on your distro.
+In `/etc/krb5.conf`, be sure to have this entry to guide the test
+domain names to our KDC::
+
+ [domain_realm]
+ # ...other entries...
+ tlspool.arpa2.lab = ARPA2.NET
+
+The following test demonstrates proper working of the TLS Pool based on
+the testdata and under the warnings above:
+
+ # terminal 1
+ cd src
+ ./tlspool -kc ../etc/tlspool.conf
+
+ # terminal 2
+ cd src
+ ../tool/testsrv
+
+ # termainl 3
+ cd src
+ ../tool/testcli
+
+This will setup a TLS connection over localhost:12345 and provide a simple
+line-by-line chat session between terminals 2 and 3, while showing debugging
+output from the TLS Pool in terminal 1. The test client and server are
+written to test more functionality as well, and they show some of it too,
+namely key agreement based on the master key, which show as matching
+"PRNG bytes" in terminals 2 and 3.
+
+A somewhat more complicated test is to actually wrap an existing service
+with tunnels:
+
+ cd src
+ ./tlspool -kc ../etc/tlspool.conf
+ ../tool/tlstunnel -s -l [::1]:22335 -L testsrv@tlspool.arpa2.lab -r [2001:db8::1234]:80
+ ../tool/tlstunnel -c -l [::1]:22334 -L testcli@tlspool.arpa2.lab -r [::1]:22335 -R testsrv@tlspool.arpa2.lab
+ nc ::1 22334
+
+The `tlspool` binary is the TLS Pool itself.
+
+The `tlstunnel -s` is a server-side TLS unwrapper. It receives TLS traffic
+on `[::1]:22335`, uses the TLS Pool to unwrap it, and forwards the traffic
+to `[2001:db8::1234]:80`, which is a non-existent address but could be replaced
+by something like a web server. You should provide your own
+IPv6 server address of choice. Note that backward compatibility with IPv4
+is available. The identity of the server is `testsrv@tlspool.arpa2.lab`
+and that is all that the tunnel needs to know; it will ask the TLS Pool to
+fill in the credentials belonging to this identity.
+
+The `tlstunnel -c` is a client-side TLS wrapper. It receives plaintext
+traffic on `[::1]:22334`, uses the TLS Pool to wrap it in TLS, and forwards
+the traffic to `[::1]:22335`, which was not quite coincidentally configured
+before as a TLS-unwrapping server. The client needs to know both its local
+identity, `testcli@tlspool.arpa2.lab`, as the server's. The local identity
+is used to access the client credentials, as was done on the server, and the
+remote identity is used to determine if the client identity may be disclosed
+to this server; furthermore, the identity is used for TLS' Server Name
+Indication, which helps with virtual hosting of TLS-secured websites. (And
+only websites, really, as all other protocols have embraced a `STARTTLS`
+method -- it is mostly everyone's popular protocol in the World that has become
+unable to evolve.)
+
+It is admittedly silly to run the client and server on the same machine, but
+it serves as a quick test, and isolates any networking trouble that might
+creep up in a distributed test.
+
+The identities shown here are in fact a bit silly for a website, which does
+not normally use a `user@` part --another thing in which the web is lagging
+behind other protocols-- but the applications don't mind that because they
+are not aware if the application used is a web server. It is assumed that
+the application would not supply silly identifiers in a real setup.
+
+Finally, and perhaps smashingly, this simple demonstration already shows a
+power of the TLS Pool: both client and server are capable of using credentials
+in the X.509 and OpenPGP formats. WireShark should show you that the client
+offers both `cert_type` values in an extension, and the server selects one
+that it likes. If the server prefers to use OpenPGP then your luck with
+WireShark may change; at the time of this writing, even the newest versions
+are unable to decode the OpenPGP certificate type. As a result, a perfectly
+good exchange will cry for attention in WireShark, assuming packet formatting
+errors.
+
+
+Trusting well-known CAs
+-----------------------
+
+By default, the testdata is not setup to trust any well-known CA certificate.
+We did however sample a Debian distribution of CA certificates, and installed
+it under testdata -- where it will NOT BE KEPT UP-TO-DATE.
+
+If you choose to rely on these CA's and need it for testing purposes, you can
+import them with
+
+ cd testdata
+ make anchors
+
+Once more, TRUST THIS ONLY FOR TESTING PURPOSES -- use a proper distrubution
+mechanism such as your OS or perhaps ARPA2 SteamWorks for anything that should
+withstand the pressure of an Internet whose intent is in part criminal.
+
+This is the reason why it must be installed as an explicit choice. We made it
+really easy to install, but also won't keep the set secure.
Running
The TLS pool also handles teardown in all its forms with grace; that
is, it will detect it immediately and notify the other side.
+
+Language Wrappers
+-----------------
+
+The TLS Pool protocol is published and can be implemented in any language
+that prefers to work at that level. It is important to understand that the
+format may change with future versions however, and that would cause some
+dismay related to versioning. We promise to confine API changes to major
+versions only to make this somewhat bearable.
+
+The golden way is to instead rely on the C library, built in lib/* and
+installed for linking with a "-ltlspool" argument. We also provide a
+.pc file for use with pkg-config.
+
+Based on this C library, we build wrappers for other languages, usually
+going through SWIG. If you desire a library, please build it separately
+with:
+
+ make -C lib/python all install
+ make -C lib/go all install
+
+and so on. Some of the libraries may not have been completed yet, in that
+case you will run into difficulties. These libraries are neither built
+nor installed as part of the normal (main directory) builds! Only the
+C library is made and/or installed by default.
+
projects / tlspool / blobdiff