TLSTUNNEL(8)

📦 version 0.9.7, in nixos 26.05

💅 TLSTUNNEL(8) — the system management command where we wrap TLS around your plaintext faves ✨

okay so bestie, real talk: this page is from the System Management Commands manual section, and honestly it ate. Let's get into it 🫶

🎀 NAME 🎀

tlstunnel — Forward TLS/DTLS as TCP/UDP/SCTP, and vice versa. Literally the whole vibe. 👑

✨ SYNOPSIS ✨

tlstunnel MODE OPTIONS [--] <pavlov_cmd>...

🌸 DESCRIPTION 🌸

so the tlstunnel command wraps TLS around connections that are otherwise plaintext. no cap, that's the whole personality. and it can even be used for protocols that do STARTTLS in the course of their protocol interactions, thanks to a simple pavlov(3) scripting facility — like, it's giving versatility 💅

The TLS facilities are drawn from a tlspool-daemon(8) daemon, which is contacted over a UNIX domain socket. So it inherits the architectural benefits of the TLS Pool, which highkey includes the ability of central control, strong protection of cryptographic credentials, and even the ability to monitor and control which local identities are revealed to which remote peers. icon behavior, honestly 🔥

The tunnel can be built up using either TLS or DTLS, the latter of which is the datagram variety of common, stream-oriented TLS. And here's the rules, bestie, memorize them:

  • When relaying a TCP connection, TLS is the only available option.
  • When relaying a UDP connection, DTLS is the only available option.
  • When relaying an SCTP connection, both varieties are available, but DTLS is generally preferred for efficiency reasons. 💅

Future versions of tlstunnel are expected to support symmetric behaviour, but the present version must run in either client or server mode. Not both. Pick a lane, girl. 🌈

Used as a client, the service listens for plaintext connections made to address inaddr and port inport, wraps them in TLS as a client and forwards the connection to address fwaddr and port fwport. When used as a server, the same is done, however the wrapping of TLS is changed to unwrapping of TLS. yes, we're unwrapping. it's giving gift 🎁

Addresses can take the form of a UNIX domain socket path, or host:port where the host is either a DNS name or an IPv6 address. For that last form, backward compatibility to IPv4 is possible by prefixing :: to an IPv4 address. And you can use this backward compatibility with either or both or none of inaddr and fwaddr — dealer's choice, bestie ✨

The end points authenticate, and are authorized, as configured in the system-wide TLS Pool policy settings. These settings ensure a consistent default behaviour for all TLS Pool connections. As an example, these policies tend to include requirements to certificates. so like, read your policy, ok? 💖

The MODE defines whether tlstunnel runs as a client or server:

  • -c, --client — Run tlstunnel as a client, meaning that it is connected to by a plaintext connection and forwarded as a TLS-wrapped variety.

Client authentication and authorization are implemented as specified in the TLS Pool configuration. This includes choice of certificates and settings about their visibility.

  • -s, --server — Run tlstunnel as a server, meaning that it is connected to by a TLS-wrapped connection and forwarded as a plaintext variety.

Client authentication and authorization are implemented as specified in the TLS Pool configuration. This includes choice of certificates and settings about their visibility.

The OPTIONS detail further information, some of which is actually not optional at all. 😭 shocking, I know.

💜 OPTIONS 💜

  • -f, --fork — When the tlstunnel stops, the TLS connections should continue to run. like, don't kill the vibe on your way out 🦋
  • -t, --tcp, --tcp-tls — Listen to, and forward as, TCP connection. The secure wrapping is implemented through stream-oriented TLS.

This is also the default option, selected when none of --tcp-tls, --udp-dtls, --sctp-tls or --sctp-dtls has been supplied. she's the default for a reason 💅

  • -u, --udp, --udp-dtls — THIS FEATURE IS NOT IMPLEMENTED. 😭 The semantics cannot be clearly defined, because UDP has no notion of a connection, while TLS does need it to keep state. Rather than implementing guesses here and load it with configuration options such as timeouts, it is advised to implement DTLS directly in the UDP application. no cap, go do it in your app instead 🙈
  • -x stream, --sctp-stream-number stream — When SCTP is used, forward the given stream number. This option may in the future be REDESIGNED to permit multiple streams, and the default is unsettled but might be all. There are a few alternative approaches. so like… it's giving "in flux" 💀

Combine with one of --sctp-dtls or --sctp-tls to specify the desired form of transport layer security.

  • --sctp-tunneled — Specifies that SCTP should be tunneled over UDP, using the port number 9899 as specified in RFC 6951. The default is to not use a tunnel, as can be specified explicitly with --sctp-not-tunneled. 🧚
  • --sctp-not-tunneled — Specifies that SCTP should not be tunneled over UDP. This is the default behaviour when --sctp-tunneled is not specified. she's the default, she's chill 🌸
  • -l localaddr, --local-addr localaddr — The local address for the tunnel. 🏠
  • -r remoteaddr, --remote-addr remoteaddr — The remote address for the tunnel. ✈️
  • -L lid, --local-id lid — Set the local identity. This should be of the form of a domain name, or user@domainname. This paramater is required. When a localid service program has registered with tlspool-daemon(8) then the local identity may be passed through for filtering, depending on the option used when registering. mandatory bestie, no skipping 💖
  • -R rid, --remote-id rid — Constrain the remote identity. This should be of the form of a domain name, or user@domainname. This parameter is optional in server mode, but is (usually) needed to setup client mode. so like… technically optional, but good luck 😭
  • -s svcname, --service svcname — Specify the service name that will be sent to tlspool-daemon(8) during initiation of the TLS protection. This helps to decide several protocol-specifics, including whether it is safe to start with an Anonymising Precursor. The service name should follow the IANA spelling, which is also used in /etc/services. 👑
yes, the page literally uses -s twice — once for --server and once for --service. not me, bestie, I just work here 🙈
  • -S path, --tlspool-socket-path path — Override the built-in default path for the socket pool. This can be used to address a specific instance of the TLS Pool, for instance one that is run under a personal account, accessing a personally held PKCS #11 token. 🔐
  • -p command, --pavlov-command command — Specifies an alternative command in the style of pavlov(3) to replace the builtin version. An external command will normally be less efficient than the builtin variety. trade-offs, bestie 💀

The remaining commandline arguments form the <pavlov_cmd>..., which are passed on to the builtin or external pavlov(3) facility. This can be used to perform communication in plaintext over the soon-to-be TLS connection; it can be used to negotiate options over a textual protocol up to the agreement to switch to TLS. This is precisely what pavlov(3) was design for — except that the next-stage protocol was PPP and not TLS. history lesson, slay 🎀

💀 LIMITATIONS 💀

The TLS Pool can handle various options when connecting to a remote site. These options have not yet been implemented as commandline switches, so this level of refinement cannot be added when using the tlstunnel program. sad but true 😭

The TLS Pool usually negotiates local and remote identities as part of the authentication and authorization procedures. These procedures do not interface optimally with the TLS Tunnel, because there is no place to leave this information. What has been implemented is the mandatory -l option that sets the local identifier to use, and an optional -r option to constrain the remote identity. it's giving "we did what we could" 🫶

Note that the TLS Tunnel does not implement a PIN entry interface; this is a function that is separately coordinated with the TLS Pool, so it can bring up a dialog in a trusted environment, making it easier to secure than any per-command PIN entry dialog. ngl that's actually kind of an upgrade 💅

Where TLS and even DTLS have a notion of connection state, necessary for the management of things like session keys, there is no concept of a connection for UDP transmission. For this reason, the UDP variant of this tool has not been implemented; it would involve close-to-NAT practices that can easily lead to confusion. so we simply didn't ✨

🦋 AUTHOR 🦋

Written by Rick van Rein of OpenFortress.nl, for the ARPA2.net project. we stan 👑

🔥 REPORTING BUGS 🔥

For any discussion, including about bugs, please use the TLS Pool mailing list found on http://lists.arpa2.org/mailman/listinfo/tls-pool. come chat, we don't bite 💖

Please read the software distribution's README, INSTALL and TODO files for information about the tlspool-daemon(8) implementation status. fr fr, read them.

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 ⭐

tlspool-daemon(8), tlspool_starttls(3), pavlov(3).

Online resources may be found on the project home page, http://tlspool.arpa2.net. go click, bestie 🎀

okay that's the whole page!! this was ARPA2.net, November 2015, page TLSTUNNEL(8) — mwah, go wrap something in TLS 💅✨

📦 where this page comes from