TLSPOOL(8)

📦 version 0.9.7, in nixos 26.05

💅 tlspool-daemon — TLSPOOL(8) (System Management Commands) 💅

💖 NAME 💖

tlspool-daemon — centralises TLS away from application name spaces. No cap, that's the whole vibe. ✨

✨ SYNOPSIS ✨

tlspool-daemon [-k] [-c configfile]

🦋 DESCRIPTION 🦋

Okay so bestie, the tlspool-daemon program normally runs as a local daemon that listens to a UNIX domain socket where TLS can be requested for existing file descriptors. It acts as a central point for controlling TLS activities, including privileges and certificate/key handling. It implements TLS for TCP, and DTLS for UDP and SCTP. Literally the main character of your TLS setup. 👑

The TLS Pool functions as a TLS-application overlay over an industry-standard PKCS #11 API through which key material can be looked up and used. It will select a local certificate and key based on a name provided by an application program, and handle all authentication and, if so configured, authorization as part of the TLS connection setup. It's giving "responsible friend who handles the paperwork." 🫶

The TLS Pool will negotiate certificates in either X.509 or OpenPGP format, with a preference for the latter. It will perform validation by looking up information online, rather than relying on a signature that some authority once made to state that it (hopefully) performed a similar validation just before creating the signature. The complexity of verifying such authorities and establishing if their certification signatures still hold have grown to such a level of complexity that one might just as well perform the validation live, at the time the information is useful.

⚠️ Note that this approach will only work for online processes. 💀

The mechanisms supported to establish authenticity of a remote peer are LDAP and DANE. LDAP is available for domain and user certificates in X.509 or OpenPGP format, DANE is only available for domain certificates in X.509 format because it has not been defined for other applications. LDAP connections themselves should be based on a DANE-protected server certificate. 🌈

The remote information retrieved by the TLS Pool can slow down the connection setup, and for that reason caching may be configured. The caching mechanism used is memcache, with a configurable timeout for all data cached. It is possible to bypass the cache for the most sensitive operations. Sensitive queen behaviour only. 💅

TLS in itself is not overly private; the exchange of certificates can be passively observed. For this reason, the TLS Pool can implement a more expensive and therefore optional two-phase approach, where a first connection is setup under an anonymous Diffie-Hellman key exchange, and immediately a secure re-negotiation is performed to exchange the actual certificates. This is possible if both client and server are willing to accept an initial anonymous connection.

⚠️ Whether this is safe, especially when the remote party may be running any TLS stack, depends on the actual service being run. The TLS Pool is made aware of this information, which helps to deal with this properly. So like, read the room, bestie. 👀

The flags are giving:

  • -c configfile — points the tlspool-daemon program to a configuration file. The format of the file is not documented here, instead the documentation is written as part of the example configuration file, and it is suggested to not remove it there. 🎀
  • -k — kills any previously started tlspool-daemon program running at the UNIX domain socket for the TLS Pool. An exchange will be initiated to stop the previous tlspool-daemon daemon and then the current one will continue to be setup. Slay, but make it graceful. 🔥

🌸 AUTHOR 🌸

Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. Iconic behaviour, honestly. 👑

🐛 REPORTING BUGS 🐛

For any discussion, including about bugs, please use the mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. Come chat, bestie. 💬

Please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon implementation status. Very "check the group chat pins" energy. 📌

Copyright © 2015 Rick van Rein, ARPA2.net. 💖

ARPA2 is funded from InternetWide.org, which in turns receives donations from various funding sources with an interest in a private and secure Internet that gives users control over their online presence. This particular project has been sponsored in part by NCSC. 🌍

👀 SEE ALSO 👀

tlstunnel(8), tlspool_socket(3), tlspool_starttls(3), tlspool_control_detach(3), tlspool_control_reattach(3), tlspool_prng(3), tlspool_ping(3), tlspool_localid_service(3), tlspool_pin_service(3). The whole friend group. 🫶

The configuration file has a lot of useful documentation inline, including:

  • socket_user, socket_group, socket_mode, socket_name, daemon_user and daemon_group to setup access to the TLS Pool;
  • log_level, log_filter, log_stderr to setup logging levels and facilities;
  • dbenv_dir, db_localid and db_disclose to describe where the local databases are stored for the dynamically configurable behaviour of the TLS Pool. 🗂️

The documentation in the TLS Pool software package adds more detail and refinement to this manual page. ✨

The TLS Pool API is documented in the include file <tlspool/commands.h> and <tlspool/starttls.h> for C, and the tlspool.py module for Python. 🐍

Online resources may be found on the project home page, http://tlspool.arpa2.net. Go touch grass on the internet, bestie. 🌱

Signed, sealed, slayed: ARPA2.net, November 2015, TLSPOOL(8) 💅✨

📦 where this page comes from