4 The tlspool package concentrates TLS usage by client and server applications.
5 It gets passed a file descriptor of a socket, initiates TLS over it, and
6 then makes a callback with authenticated local/remote identities in a
7 request for an additional file descriptor for the plaintext side. This
8 approach makes it straightforward to add TLS support to network software,
9 and the central location of the TLS Pool makes it easy to enforce consistent
10 rules for authentication and authorization rules.
16 The actual daemon design is part of the plans of InternetWide.org,
17 which aims to improve everyone's Internet quality through distribution of
18 more protocols and facilities with strong encryption and privacy. The
19 full stretch of this project is documented on http://internetwide.org
20 The practical/project side of this project is called ARPA2.net, and the
21 website for the TLS Pool can be found at
23 http://tlspool.arpa2.net
25 We are currently at a state where the daemon and a small stub library for
26 applications are working for certificate authentication using X.509 certs
27 and/or OpenPGP keys. We have built-in initial support for a few upcoming
28 authentication approaches, namely Secure Remote Passwords and our own
31 http://tls-kdh.arpa2.net
33 Please see the TODO file for work that has not yet been completed.
39 The core logic used here is (client shown, server is similar):
41 #include <tlspool/starttls.h>
44 if (-1 == starttls_client (fd, &tlsparams, &plainfd, NULL)) {
51 ...continue to use plainfd...
54 The daemon will cover TCP, UDP and SCTP over IPv4 and IPv6. Asynchronous
55 versions of these calls are possible by directly talking to the UNIX domain
56 socket of the API. The library routines above are only simple interfaces
57 to these socket interactions.
59 Unlike with common libraries, the identity forms (X.509 certificates,
60 OpenPGP keys, Kerberos tickets, ...) are not made available to the
61 application. What is provided, are authenticated identities contained
62 in the tlsparams structure after this call.
65 The importance of PKCS #11
66 --------------------------
68 The key material used by this daemon will be accessed over PKCS #11. Compromise
69 will require multi-layered attacks to key material: the material is protected
70 by a secure key store of choice, in hardware or software, and even the PIN
71 for using the private keys without seeing them is stored in a separate
72 program, namely the TLS Pool. Specifically, the PIN and key material are
73 not available to user agents such as a PHP-enabled web server which may
74 be running outdated software.
76 Aside from the improved key protection and the ability to choose a security
77 level by choosing the PKCS #11 implementation accordingly, it is useful to
78 have a central location for key storage; this simplifies maintenance tasks,
79 such as certificate renewals and (PIN encrypted) secret key backup.
81 One last advantage of using PKCS #11 is that this enables a form where
82 USB token manufacturers can provide a tool that functions as a HTTP proxy,
83 and that establishes secure connections to selected parties with an OpenPGP
84 key and no further infrastructure. End users can plugin their token to
85 get secured access, and remove it to stop further secure web connections.
86 Note that this principle can easily be extended to other protocols that
87 can work through a proxy.
89 Note that it is expressly not the task of the TLS Pool to manage the
90 objects stored behind the PKCS #11 API. This is expressly left to
91 external tools that manage certificates and keys on behalf of the
92 application area covered. All the TLS Pool does is read tokens, looking
93 for usable keys to authenticate its identities to the Internet, both over
94 X.509 and over OpenPGP.
96 One final, and hardly recognised use of having a central TLS Pool and
97 potentially centralised PKCS #11 repositories is the ability to monitor
98 the network traffic for intrusion attempts. To be able to do this in
99 the presence of encrypted connections, the ability to decrypt the
100 traffic must be offered to sniffers like Snort. The decryption usually
101 involves manual input of certificates and private keys, which is no
102 longer necessary with PKCS #11 with remote access to the API in place.
103 So, large-scale organisations could setup a networked HSM and use it
104 both for production use and for feeding the intrusion detectors.
107 The use of Central Configuration
108 --------------------------------
110 It is common for TLS applications to have locally defined settings for
111 things like cipher suites, keys, methods of authentication supported, and
112 much more. Given the complexity of TLS and the application-specific
113 format of configuration, the result is not ideal:
115 - Applications need to concern themselves with security issues. In most
116 cases, the ability to externalise these concerns is desirable for the
117 application programmer, system administrator and security officer.
119 - When changes are necessary, many applications need to be reconfigured,
120 each in their own format. This is a problem when such changes are
121 needed as a result of security disclosures.
123 - Not all applications cover the full range of features that TLS can
124 offer. This means that security policies are constrained to the
125 lowest common denominator.
127 The TLS Pool resolves this situation by not interfacing with the application
128 about security settings. All security settings are made out-of-band, and
129 can be set in the same way for all applications at once; variations are
130 supported per service, but even then the grammar is consistent.
132 Configuration information for the TLS Pool is stored in simple key-value
133 databases, whose contents may be modified without taking the TLS Pool
134 offline. The databases can be managed from the commandline, over a
135 web-based API or from a central configuration in LDAP, using the sister
136 project SteamWorks, documented on http://steamworks.arpa2.net -- there
137 is a SteamWorks Pulley plugin for TLS Pool configuration.
140 Additional Rules: RADIUS
141 ------------------------
143 TODO: Can RADIUS handle user@domain for both the user and the realm?
145 Local environments may have their own added requirements to authentication,
146 authorization and also pursue their own accounting of TLS connections. The
147 common approach to these mechansims is RADIUS, which can independently
148 handle these three types of request. RADIUS is designed as a fast local
149 protocol, and it can be rerouted with FreeRADIUS and resolved with scripts
150 or programs in just about any programming language.
152 Any AAA facilities are stacked on top of the minimum requirements offered
153 by the TLS Pool, that is the identities of the peers can be assumed to
154 have been established (or perhaps be established in parallel) while the
155 authentication and authorization is requested. Note that accounting
156 will always wait for completion of the identity check, to avoid charging
157 to an innocent account.
159 Note that RADIUS combines authentication and authorization into one accept
160 phase, which is supposed to do both. This means that in practice most
161 people will declare RADIUS for either authentication or authorization.
162 This is not a requirement though; the functions can be setup and, due to
163 lack of expressiveness in the protocol, split over different servers.
165 Accounting is not usually applied immediately when a TLS connection is
166 setup; this is barely useful information. Instead, the TLS Pool is able
167 to receive accounting requests over the same API as it uses for the
168 authentication and authorization requests, and it can pass requests on
169 to the accounting functions of a RADIUS service.
171 Accounting in the style of the TLS Pool comes down to counting ticks or
172 time; a series of values is supplied to both the start and end that is
175 - an identifier for the kind of thing being accounted;
176 - an identifier for the instance being accounted;
177 - a local and remote identity of a user@domain or of a domain.
179 For each of these, information is collected to support accounting:
181 - the identifier for the kind of thing being accounted;
182 - the identifier for the instance being accounted;
183 - the local and remote identity of a user@domain or of a domain;
184 - a timestamp for the start and, if present, the end of a period;
185 - a final count representing the number of items being accounted.
191 The TLS Pool makes heavy use of UNIX domain sockets, and specifically their
192 ability to pass a file descriptor between processes using `SOL_SOCKET` and
193 `SCM_RIGHTS`. For Windows, another approach is provisioned:
195 TODO: This needs to be tried and built into the code base!
197 - The TLS Pool offers its services through a NamedPipe
198 - Waiting can be done with I/O Completion Ports
199 - File descriptor passing may be ported to random-name-passing for a NamedPipe
200 - This would require NamedPipe access being available only to the TLS Pool
201 - Alternatively, we could use CreatePipe and DuplicateHandle
205 http://comp.os.ms-windows.programmer.win32.narkive.com/wzRZJosf/anybody-used-createpipe-between-different-programs-prcesses
207 http://tinyclouds.org/iocp-links.html
projects / tlspool / blob