TLSPOOL README
==============
-The tlspool package concentrates TLS-use by client and server applications.
+The tlspool package concentrates TLS usage by client and server applications.
It gets passed a file descriptor of a socket, initiates TLS over it, and
-then passes back a new, TLS-protected socket to the originator. This makes
-it very straightforward to add TLS support to network software, and the
-central location of the TLS pool makes it easy to enforce consistent rules
-for authentication and authorization rules.
+then makes a callback with authenticated local/remote identities in a
+request for an additional file descriptor for the plaintext side. This
+approach makes it straightforward to add TLS support to network software,
+and the central location of the TLS Pool makes it easy to enforce consistent
+rules for authentication and authorization rules.
-Current Status
---------------
+Current development
+-------------------
-Currently, this work is in a proof-of-concept state, and programmed in
-Python. This has been the work of a couple of students who wrote in Python,
-and it should be seen as a first demonstration of the idea of a TLS pool.
-It is not at production level, documentation is rather limited, but it
-may be used for demonstration purposes.
+The actual daemon design is part of the plans of InternetWide.org,
+which aims to improve everyone's Internet quality through distribution of
+more protocols and facilities with strong encryption and privacy. The
+full stretch of this project is documented on http://internetwide.org
+The practical/project side of this project is called ARPA2.net, and the
+website for the TLS Pool can be found at
-Note that this early TLS daemon uses the major concept, namely that of
-file descriptor exchange between application and TLS pool, but the rest
-of the API has not been explicitly designed; expect this specific API
-to change.
+http://tlspool.arpa2.net
-Also note that the DANE implementation only works for the publication of
-hashes of certificates, not for its other forms. This means that the
-code is only usable in situations where the remote party can be trusted
-to implement this sort of thing.
+We are currently at a state where the daemon and a small stub library for
+applications are working for certificate authentication using X.509 certs
+and/or OpenPGP keys. We have built-in initial support for a few upcoming
+authentication approaches, namely Secure Remote Passwords and our own
+work on TLS-KDH,
+http://tls-kdh.arpa2.net
-Full-blown daemon development
------------------------------
+Please see the TODO file for work that has not yet been completed.
-This daemon design is part of the plans of the Network Effect Alliance,
-which aims to improve everyone's Internet quality through distribution of
-more protocols and facilities under privately owned domain names. The
-full stretch of this project is documented on the website,
-http://www.networkeffectalliance.org
-Future developments will provide include/library files that offer simple
-calls fd=starttls_client(fd,...) and fd=starttls_server(fd,...) to
-accommodate the switch from unencrypted traffic to TLS-encrypted traffic.
-Protocol support for TCP, UDP and SCTP over IPv4 or IPv6 will be provided.
+Using the library API
+---------------------
+
+The core logic used here is (client shown, server is similar):
-The daemon will provide configurable hooks for authorization; this can
-then be setup for the entire system at once. The resulting information
-of both authentication and authorization will be shared using memcached,
-to simplify sharing of outcome not just accross time and between protocols,
-but also between different servers. The design goal of memcached is to
-avoid repeated checks and repeated access to remotely stored information,
-until a certain caching time has passed.
+ #include <tlspool/starttls.h>
+ ...
+ plainfd = -1;
+ if (-1 == starttls_client (fd, &tlsparams, &plainfd, NULL)) {
+ if (plainfd >= 0) {
+ close (plainfd);
+ plainfd = -1;
+ }
+ ...error reporting...
+ } else {
+ ...continue to use plainfd...
+ }
+
+The daemon will cover TCP, UDP and SCTP over IPv4 and IPv6. Asynchronous
+versions of these calls are possible by directly talking to the UNIX domain
+socket of the API. The library routines above are only simple interfaces
+to these socket interactions.
+
+Unlike with common libraries, the identity forms (X.509 certificates,
+OpenPGP keys, Kerberos tickets, ...) are not made available to the
+application. What is provided, are authenticated identities contained
+in the tlsparams structure after this call.
The importance of PKCS #11
--------------------------
-The key material used by this daemon will be accessed over PKCS #11. This
-requires multi-layered attacks to key material: the material is protected
+The key material used by this daemon will be accessed over PKCS #11. Compromise
+will require multi-layered attacks to key material: the material is protected
by a secure key store of choice, in hardware or software, and even the PIN
for using the private keys without seeing them is stored in a separate
-program, namely the TLS pool. Specifically, the PIN and key material are
+program, namely the TLS Pool. Specifically, the PIN and key material are
not available to user agents such as a PHP-enabled web server which may
be running outdated software.
Note that this principle can easily be extended to other protocols that
can work through a proxy.
+Note that it is expressly not the task of the TLS Pool to manage the
+objects stored behind the PKCS #11 API. This is expressly left to
+external tools that manage certificates and keys on behalf of the
+application area covered. All the TLS Pool does is read tokens, looking
+for usable keys to authenticate its identities to the Internet, both over
+X.509 and over OpenPGP.
+
+One final, and hardly recognised use of having a central TLS Pool and
+potentially centralised PKCS #11 repositories is the ability to monitor
+the network traffic for intrusion attempts. To be able to do this in
+the presence of encrypted connections, the ability to decrypt the
+traffic must be offered to sniffers like Snort. The decryption usually
+involves manual input of certificates and private keys, which is no
+longer necessary with PKCS #11 with remote access to the API in place.
+So, large-scale organisations could setup a networked HSM and use it
+both for production use and for feeding the intrusion detectors.
+
+
+The use of Central Configuration
+--------------------------------
+
+It is common for TLS applications to have locally defined settings for
+things like cipher suites, keys, methods of authentication supported, and
+much more. Given the complexity of TLS and the application-specific
+format of configuration, the result is not ideal:
+
+ - Applications need to concern themselves with security issues. In most
+ cases, the ability to externalise these concerns is desirable for the
+ application programmer, system administrator and security officer.
+
+ - When changes are necessary, many applications need to be reconfigured,
+ each in their own format. This is a problem when such changes are
+ needed as a result of security disclosures.
+
+ - Not all applications cover the full range of features that TLS can
+ offer. This means that security policies are constrained to the
+ lowest common denominator.
+
+The TLS Pool resolves this situation by not interfacing with the application
+about security settings. All security settings are made out-of-band, and
+can be set in the same way for all applications at once; variations are
+supported per service, but even then the grammar is consistent.
+
+Configuration information for the TLS Pool is stored in simple key-value
+databases, whose contents may be modified without taking the TLS Pool
+offline. The databases can be managed from the commandline, over a
+web-based API or from a central configuration in LDAP, using the sister
+project SteamWorks, documented on http://steamworks.arpa2.net -- there
+is a SteamWorks Pulley plugin for TLS Pool configuration.
+
+
+Additional Rules: RADIUS
+------------------------
+
+TODO: Can RADIUS handle user@domain for both the user and the realm?
+
+Local environments may have their own added requirements to authentication,
+authorization and also pursue their own accounting of TLS connections. The
+common approach to these mechansims is RADIUS, which can independently
+handle these three types of request. RADIUS is designed as a fast local
+protocol, and it can be rerouted with FreeRADIUS and resolved with scripts
+or programs in just about any programming language.
+
+Any AAA facilities are stacked on top of the minimum requirements offered
+by the TLS Pool, that is the identities of the peers can be assumed to
+have been established (or perhaps be established in parallel) while the
+authentication and authorization is requested. Note that accounting
+will always wait for completion of the identity check, to avoid charging
+to an innocent account.
+
+Note that RADIUS combines authentication and authorization into one accept
+phase, which is supposed to do both. This means that in practice most
+people will declare RADIUS for either authentication or authorization.
+This is not a requirement though; the functions can be setup and, due to
+lack of expressiveness in the protocol, split over different servers.
+
+Accounting is not usually applied immediately when a TLS connection is
+setup; this is barely useful information. Instead, the TLS Pool is able
+to receive accounting requests over the same API as it uses for the
+authentication and authorization requests, and it can pass requests on
+to the accounting functions of a RADIUS service.
+
+Accounting in the style of the TLS Pool comes down to counting ticks or
+time; a series of values is supplied to both the start and end that is
+being accounted:
+
+ - an identifier for the kind of thing being accounted;
+ - an identifier for the instance being accounted;
+ - a local and remote identity of a user@domain or of a domain.
+
+For each of these, information is collected to support accounting:
+
+ - the identifier for the kind of thing being accounted;
+ - the identifier for the instance being accounted;
+ - the local and remote identity of a user@domain or of a domain;
+ - a timestamp for the start and, if present, the end of a period;
+ - a final count representing the number of items being accounted.
+
+
+Windows Porting
+---------------
+
+The TLS Pool makes heavy use of UNIX domain sockets, and specifically their
+ability to pass a file descriptor between processes using `SOL_SOCKET` and
+`SCM_RIGHTS`. For Windows, another approach is provisioned:
+
+TODO: This needs to be tried and built into the code base!
+
+ - The TLS Pool offers its services through a NamedPipe
+ - Waiting can be done with I/O Completion Ports
+ - File descriptor passing may be ported to random-name-passing for a NamedPipe
+ - This would require NamedPipe access being available only to the TLS Pool
+ - Alternatively, we could use CreatePipe and DuplicateHandle
+
+Links:
+
+http://comp.os.ms-windows.programmer.win32.narkive.com/wzRZJosf/anybody-used-createpipe-between-different-programs-prcesses
+
+http://tinyclouds.org/iocp-links.html
+
projects / tlspool / blobdiff