Provided by: tlswrapper_0~20241101-1_amd64 
NAME
tlswrapper - TLS encryption wrapper
SYNOPSIS
tlswrapper [ options ] prog
DESCRIPTION
The tlswrapper is an TLS encryption wrapper between remote client and local program prog.
Systemd.socket/inetd/tcpserver/... creates the server connection, tlswrapper
encrypts/decrypts data stream and reads/writes data from/to the program prog as follows:
Internet <--> systemd.socket/inetd/tcpserver/... <--> tlswrapper <--> prog
OPTIONS
-q Quiet mode. No error messages.
-Q Normal mode (default). The tlswrapper prints only fatal messages, which means
system errors (e.g. memory allocation problems), configuration errors (e.g. syntax
errors) and problems with PEM certificates (missing files, etc... ). In this mode
the tlswrapper doesn't print any information about TLS connections.
-v Verbose mode. The tlswrapper prints also information/warnings/errors about TLS
connection, but after TLS handshake is successfully done. In this mode TLS errors
before the complete TLS handshake are suppressed.
-vv Debug mode. The tlswrapper prints also debug information about TLS connection,
including all TLS connection warnings/errors.
-vvv Tracing mode. The tlswrapper prints also tracing messages, useful for bug hunting.
-f certfile
Add a file containing key+certificate(s) in PEM format.
-d certdir
Add a directory containing multiple key+certificate(s) files in PEM format. The
file in the directory is selected by hostname extracted from SNI extension.
Warning: For security reasons tlswrapper does not allow dots immediately after
slashes in certdir name. It changes these dots to colons before attempting to open
the PEM file.
-a anchorfile
Enable client certificate authentication. Use CA trust anchor anchorfile. Only one
-a option supported.
-c cipher
Add symmetric encryption cipher. See ALGORITHMS. (default: -c
CHACHA20_POLY1305_SHA256 -c AES_256_GCM_SHA384 -c AES_128_GCM_SHA256). The cipher
preference depends on the -c option order.
-e ephemeral
Add ephemeral algorithm ephemeral. See ALGORITHMS. (default: -e x25519 -e
secp256r1). The algorithm preference currently doesn't depend on the -e option
order. Right now we use a fixed preference order x25519, secp256r1, secp384r1,
secp521r1.
-m The minimal TLS version. See ALGORITHMS. (default: tls12).
-M The maximal TLS version. See ALGORITHMS. (default: tls12).
-t seconds
Set the network timeout to seconds seconds. (default 60).
-T seconds
Set the TLS handshake timeout to seconds seconds. (default 30).
-u user
Run program prog under a specified user's uid and gid
-U ASN.1 object
Extract the user from ASN.1 object from the client certificate and run program prog
under user's uid and gid. Supported ASN.1 object objects are 'commonName' and
'emailAddress'.
-p version
Enable incoming proxy-protocol version version string. The tlswrapper receives the
-s Enforce TLS server preferences. (default).
-S Don't enforce TLS server preferences.
-J jaildir
Chroot network-process and key-process into a specified jaildir (default:
/var/lib/tlswraper/empty).
-j jailuser
Run network-process and key-process under a specified jailuser's uid and gid. If
unset run network-process and key-process under random uid and gid.
-n Enable delayed encryption. It's experimental feature! This is useful for protocols
which uses STARTTLS. tlswrapper creates to the child control pipe on filedescriptor
5 for writing. The child process starts communication in plaintext a encryption
starts in the moment when child use the control pipe instead of startdard output,
writes the initialization string (e.g. for SMTP protocol '220 ready to start
TLS\r\n') and closes the control pipe. See e.g. tlswrapper-smtp(1).
-N Disable delayed encryption (default).
prog program
SECURITY
Separate process for every connection
The tlswrapper is executed from systemd.socket/inetd/tcpserver/... which runs separate
instance of tlswrapper for each TLS connection. It ensures that a vulnerability in the
code (e.g. bug in the TLS library) can't be used to compromise the memory of another
connection.
Separate process for network connection and separate process for secret-key operation
To protect against secret-information leaks to the network connection (such Heartbleed)
tlswrapper runs two independent processes for every TLS connection. One process holds
secret-keys and runs secret-keys operations and second talks to the network. Processes
communicate with each other through UNIX pipes.
JAIL - Privilege separation, filesystem isolation, limits
The tlswrapper processes run under dedicated non-zero uid to prohibit kill, ptrace, etc.
Is chrooted into an empty, unwritable directory to prohibit filesystem access. Sets
ulimits to prohibit new files, sockets, etc. Sets ulimits to prohibit forks.
PEM files
The tlswrapper uses for simplicity both secret-key and certificates in one PEM file. When
the server starts, runs two independent UNIX processes, one for network communication,
second for secret-key operations. The network-process is immediately jailed and starts
TLS handshake. Secret-key-process starts under root privileges, waits when
network-process receives SNI extension from client-hello packet. Then the network-process
assemble the PEM filename and sends the name to the secret-key-process.
Secret-key-process loads the PEM file and immediately is jailed and drops it's privileges.
Since here both processes runs jailed (see JAIL above). Note that PEM files are loaded
under root privileges, but parsed in jailed unpriviledged process. It ensures that a
vulnerability in the parsing code can't be used to gain root privileges/information.
Warning: For security reasons tlswrapper does not allow dots immediately after slashes in
file names. It changes these dots to colons before attempting to open the PEM file.
TLS library
The tlswrapper uses BearSSL. BearSSL is an implementation of the SSL/TLS protocol (RFC
5246) written in C. It aims at offering the following features:
- Be correct and secure. In particular, insecure protocol versions and choices of
algorithms are not supported, by design; cryptographic algorithm implementations are
constant-time by default.
- Be small, both in RAM and code footprint. For instance, a minimal server implementation
may fit in about 20 kilobytes of compiled code and 25 kilobytes of RAM.
- Be highly portable. BearSSL targets not only big operating systems like Linux and
Windows, but also small embedded systems and even special contexts like bootstrap code.
- Be feature-rich and extensible. SSL/TLS has many defined cipher suites and extensions;
BearSSL should implement most of them, and allow extra algorithm implementations to be
added afterwards, possibly from third parties.
ALGORITHMS
┌──────────────────────────────────┐
│TLS version (-m option -M option) │
├─────────┬───────────┬────────────┤
│tls10 │TLS 1.0 │ optional │
├─────────┼───────────┼────────────┤
│tls11 │TLS 1.1 │ optional │
├─────────┼───────────┼────────────┤
│tls12 │TLS 1.2 │ default │
├─────────┼───────────┼────────────┤
│tls13 │TLS 1.3 │ TODO │
└─────────┴───────────┴────────────┘
┌──────────────────────────────────────────────────────────────────────────────┐
│ ciphers (-c option) │
├─────────────────────────┬─────────────────────────────────────────┬──────────┤
│CHACHA20_POLY1305_SHA256 │ ChaCha20+Poly1305 encryption (TLS 1.2+) │ default │
├─────────────────────────┼─────────────────────────────────────────┼──────────┤
│AES_256_GCM_SHA384 │ AES-256/GCM encryption (TLS 1.2+) │ default │
├─────────────────────────┼─────────────────────────────────────────┼──────────┤
│AES_128_GCM_SHA256 │ AES-128/GCM encryption (TLS 1.2+) │ default │
├─────────────────────────┼─────────────────────────────────────────┼──────────┤
│AES_256_CBC_SHA384 │ AES-256/CBC + SHA-384 (TLS 1.2+) │ optional │
├─────────────────────────┼─────────────────────────────────────────┼──────────┤
│AES_128_CBC_SHA256 │ AES-128/CBC + SHA-384 (TLS 1.2+) │ optional │
├─────────────────────────┼─────────────────────────────────────────┼──────────┤
│AES_256_CBC_SHA │ AES-256/CBC + SHA-1 │ optional │
├─────────────────────────┼─────────────────────────────────────────┼──────────┤
│AES_128_CBC_SHA │ AES-128/CBC + SHA-1 │ optional │
└─────────────────────────┴─────────────────────────────────────────┴──────────┘
┌──────────────────────────────────────────────┐
│ ephemeral (-e option) │
├──────────┬────────────────────────┬──────────┤
│x25519 │ ECDHE using X25519 │ default │
├──────────┼────────────────────────┼──────────┤
│secp256r1 │ ECDHE using NIST P-256 │ default │
├──────────┼────────────────────────┼──────────┤
│secp384r1 │ ECDHE using NIST P-384 │ optional │
├──────────┼────────────────────────┼──────────┤
│secp521r1 │ ECDHE using NIST P-521 │ optional │
└──────────┴────────────────────────┴──────────┘
EXAMPLES
Run tlswrapper using tcpserver/busybox/inetd on port 443.
tcpserver -HRDl0 0 443 tlswrapper [ options ] prog
busybox tcpsvd 0 443 tlswrapper [ options ] prog
inetd.conf line: https stream tcp nowait root /usr/bin/tlswrapper tlswrapper [ options ] prog
Simple usage, use one '/etc/.../rsa.pem' certificate:
... tlswrapper -f '/etc/.../rsa.pem' ...
Use '/etc/.../ecdsa.pem' certificate and fall-back to '/etc/.../rsa.pem' certificate, if
the client doesn't support previous one.
... tlswrapper -f '/etc/.../ecdsa.pem' -f '/etc/.../rsa.pem' ...
Use certificate '/etc/.../rsa.d/{hostname}' where {hostname} is extracted from the SNI
extension:
... tlswrapper -d '/etc/.../rsa.d/' ...
Use certificate '/etc/.../ecdsa.d/{hostname}' where {hostname} is extracted from the SNI
extension, and fall-back to '/etc/.../rsa.d/{hostname}', if the client doesn't support
previous one.
... tlswrapper -d '/etc/.../ecdsa.d/' -d '/etc/.../rsa.d/' ...
Use certificate '/etc/.../ecdsa.d/{hostname}' where {hostname} is extracted from the SNI
extension, and fall-back to '/etc/.../rsa.pem', if the client doesn't support previous
one.
... tlswrapper -d '/etc/.../ecdsa.d/' -f '/etc/.../rsa.pem' ...
Enable TLS 1.0 - TLS 1.2 and all supported algorithms:
... tlswrapper -m tls10 \
-M tls12 \
-c CHACHA20_POLY1305_SHA256 \
-c AES_256_GCM_SHA384 \
-c AES_128_GCM_SHA256 \
-c AES_256_CBC_SHA384 \
-c AES_128_CBC_SHA256 \
-c AES_256_CBC_SHA \
-c AES_128_CBC_SHA \
-e x25519 \
-e secp256r1 \
-e secp384r1 \
-e secp521r1 \
...
Enable TLS 1.0 - TLS 1.2 and all supported algorithms, but different order (prefer
AES128):
... tlswrapper -m tls10 \
-M tls12 \
-c CHACHA20_POLY1305_SHA256 \
-c AES_128_GCM_SHA256 \
-c AES_128_CBC_SHA256 \
-c AES_128_CBC_SHA \
-c AES_256_GCM_SHA384 \
-c AES_256_CBC_SHA384 \
-c AES_256_CBC_SHA \
-e x25519 \
-e secp256r1 \
-e secp384r1 \
-e secp521r1 \
...
Enable only 256-bit symmetric ciphers:
... tlswrapper -c CHACHA20_POLY1305_SHA256 \
-c AES_256_GCM_SHA384 \
-c AES_256_CBC_SHA384 \
-c AES_256_CBC_SHA \
...
Enable client certificate authentication:
... tlswrapper -a anchorCA.pem -f rsa.pem ...
Enable client certificate authentication, and run program under user extracted from client
cert. from commonName:
... tlswrapper -a anchorCA.pem -U commonName -f rsa.pem ...
Enable client certificate authentication, and run program under user extracted from client
cert. from emailAddress:
... tlswrapper -a anchorCA.pem -U emailAddress -f rsa.pem ...
SEE ALSO
tlswrapper-tcp(1), tlswrapper-smtp(1), systemd.socket(5), inetd(8), tcpserver(1)
tlswrapper(1)