Application Interface: Sockets and Identities¶
The face that the TLS Pool shows towards an application is modest, and certainly simpler than the customary tasks that the application faces. In essence, the application need only be aware of sockets and identities.
Applications feel a need to initiate TLS at some point during the execution of a network connection; either right when it is started (such as for HTTPS) or after a certain exchange (such as the STARTTLS command in IMAP, SMTP, XMPP and LDAP). It is at this point that the application initiates contact with the TLS Pool.
The TLS Pool itself is a daemon that listens on a UNIX domain socket (on
Windows, this is replaced by a NamedPipe
). In principle, the previously
unencrypted connection is passed over this interface to the TLS Pool, which then
initiates the TLS handshake. The application and TLS Pool setup a
socketpair(2)
between them that will carry the plaintext traffic, resulting
from the TLS Pool’s endeauvours in removing TLS.
Not many know this, but passing file descriptors (such as sockets) over an
AF_UNIX
socket is a POSIX standard, and thus available on most platform. The
one platform that is (or was) not POSIX-compatible is Windows; there, a similar
mechanism can be simulated by passing a HANDLE
between Process
instances.
Although the socket-level protocol between the application and TLS Pool has been described, it is subject of some developments and it is likely to change in the future. For the time being, the advised interface is therefore to go through the TLS Pool library, whose calls should be more stable over time. This library is also the main target for language porting, because it delivers better maintainable language ports than reinventing the socket protocol in each language.
In essence, the communication between an application and the TLS Pool is a request to take a socket and STARTTLS on it; this is embellished with parameters and settings. Once the handshake is complete (or has failed), a response (or an error) will be reported to the application. The response will include a local and remote identity, authenticated by the TLS Pool as part of the TLS handshake, and so a solid basis for further processing in the application. Usually, the next step for the application will be to subject the remote identity to authorisation inquiries, usually guided by access control lists.
The details of this interaction are documented in the following manual pages:
tlspool_socket(3)
— Setup the TLS Pool to use with a given socket pathtlspool_ping(3)
— Negotiate version and features with the TLS Pooltlspool_starttls(3)
— Switch wrapping a plaintext connection into TLStlspool_prng(3)
— Pseudo-Random Number Generation from TLS master secrettlspool_control_detach(3)
— Detach a TLS connection from the current processtlspool_control_reattach(3)
— Reattach a TLS connection to the current process
Of these, the main function is tlspool_starttls(3)
, and the data structure
tlsdata
passed in and out of it defines the identities exchanged; the rest of
the manual page explains the varieties of sockets passing in and out.