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):
+
+ #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 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.
+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.
-CURRENT STATUS: The daemon starts, parses configuration directives and
-processes most of them. There is no actual service yet, just a loop that
-makes the tool infinitely sleepy.
+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
+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
+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: Perhaps prefer TACACS+?
-TODO: Are authn and authz indeed separated? And is this desirable?
TODO: Can RADIUS handle user@domain for both the user and the realm?
Local environments may have their own added requirements to authentication,
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
+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.
-Accounting is not usually applied immediately though. It may be flagged
-when the TLS pool is requested to setup TLS over a connection, but it may
-also be requested separately at some later time.
+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