Difference between revisions of "Stunnel"

From ArchWiki
Jump to navigation Jump to search
m (Byte order mark (BOM): expects -> should have)
m (forgot ja: prefix)
 
(17 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[Category:Secure Shell]]
 
[[Category:Secure Shell]]
 
+
[[ja:Stunnel]]
 
[https://www.stunnel.org stunnel] (“Secure Tunnel”) is a
 
[https://www.stunnel.org stunnel] (“Secure Tunnel”) is a
 
: multi-platform application used to provide a universal TLS/SSL tunneling service. It is sort of proxy designed to add TLS encryption functionality to existing clients and servers without any changes in the programs' code. It is designed for security, portability, and scalability (including load-balancing), making it suitable for large deployments. It uses [[openssl]], and distributed under GNU GPL version 2 or later with OpenSSL exception.
 
: multi-platform application used to provide a universal TLS/SSL tunneling service. It is sort of proxy designed to add TLS encryption functionality to existing clients and servers without any changes in the programs' code. It is designed for security, portability, and scalability (including load-balancing), making it suitable for large deployments. It uses [[openssl]], and distributed under GNU GPL version 2 or later with OpenSSL exception.
Can tunnel only TCP packets. Its [https://www.stunnel.org/faq.html FAQ] has some work around for UDP.
+
Can tunnel only TCP packets. Its [https://www.stunnel.org/faq.html FAQ] has some work around for UDP. [[WireGuard]] also has UDP capabilities.
  
 
Authentication can also be used by the server to allow access only to approved clients.
 
Authentication can also be used by the server to allow access only to approved clients.
Line 13: Line 13:
  
 
== setup ==
 
== setup ==
The main configuration file is read from {{ic|/etc/stunnel/stunnel.conf}}.
+
The main configuration file is read from {{ic|/etc/stunnel/stunnel.conf}}. It is an ini-style file. It is composed from a global section, followed by one, or more, service sections.  
  
 
A client is one to accept non TLS encrypted data. Stunnel will TLS encrypts its data and connects to the stunnel server. The stunnel server accepts TLS encrypted data and extracts it. It then connects to where the data should be sent to.
 
A client is one to accept non TLS encrypted data. Stunnel will TLS encrypts its data and connects to the stunnel server. The stunnel server accepts TLS encrypted data and extracts it. It then connects to where the data should be sent to.
 +
 +
The default {{ic|debug}} value is 5, which is very verbose. After verifying correct operation, it is worth explicitly setting lower value in the configuration file.
 +
{{hc|/etc/stunnel/stunnel.conf|2=debug = 3}}
 +
 +
For better security, it is advised to explicitly set an appropriate uid and gid, other then root, for the global section and the per service sections. The configuration tokens {{ic|setuid}} and {{ic|setgid}} are available for this purpose.
  
 
=== Byte order mark (BOM) ===
 
=== Byte order mark (BOM) ===
The configuration file should have a UTF-8 [https://en.wikipedia.org/wiki/Byte_order_mark byte order mark (BOM)], at the beginning of the file. A BOM is the unicode character U+FEFF. Its UTF-8 representation is the (hexadecimal) byte sequence 0xEF, 0xBB, 0xBF. Inserting those bytes into the beginning of a file can be done by
+
The configuration file should have a UTF-8 [https://en.wikipedia.org/wiki/Byte_order_mark byte order mark (BOM)], at the beginning of the file. A BOM is the unicode character U+FEFF. Its UTF-8 representation is the (hexadecimal) byte sequence 0xEF, 0xBB, 0xBF. Creating a file with these bytes at its beginning can be done by
  
  # echo -e '\xEF\xBB\xBF' > /etc/stunnel/stunnel.conf
+
  # echo -e '\x'''ef'''\x'''bb'''\x'''bf'''; BOM composed of non printable characters. It is here, before the semicolon!' > /etc/stunnel/stunnel.conf
  
 
To test if those bytes appear, one can use
 
To test if those bytes appear, one can use
  
{{bc|1=% od -address-radix=n -–format=x1c --read-bytes=4 /etc/stunnel/stunnel.conf
+
{{bc|1=% od --address-radix=n --format=x1c --read-bytes=8 /etc/stunnel/stunnel.conf
   ef  bb  bf  0a
+
   '''ef  bb  bf'''  3b  20 42  4f  4d
  357 273 277 \n}}
+
  357 273 277   ;      B  O  M}}
  
 
Note that when printing the file to the screen, such as with {{ic|cat}}, or when editing the file with a text editor, the BOM bytes are usually not displayed. They should be there, though. Which is why you might want to verify that they are still there after editing is completed with the above {{ic|od}}, or similar, command.
 
Note that when printing the file to the screen, such as with {{ic|cat}}, or when editing the file with a text editor, the BOM bytes are usually not displayed. They should be there, though. Which is why you might want to verify that they are still there after editing is completed with the above {{ic|od}}, or similar, command.
Line 32: Line 37:
 
=== Authentication ===
 
=== Authentication ===
  
At least one of the client and the server, and optionally both, should be authenticated. Either a pre shared secret, or a key and certificate pair, can be used for authentication. A pre shared secret has to be transfered to all the involved machines a priory by other means, such as [[SCP and SFTP]]. When such transfer is acceptable, pre shared key is the fastest method. Its speed might help defending attacks. A simple configuration for a server with a single client that are using a pre shared secret is:
+
At least one of the client and the server, and optionally both, should be authenticated. Either a pre shared secret, or a key and certificate pair, can be used for authentication. A pre shared secret has to be transferred to all involved machines a priory by other means, such as [[SCP and SFTP]]. When such transfer is acceptable, pre shared key is the fastest method. Its speed might help mitigating attacks. A simple configuration for a single server with a single client that are using a pre shared secret is:
{{hc|client:/etc/stunnel/stunnel.conf|2=[trivial client]
+
{{hc|client:/etc/stunnel/stunnel.conf|2=
client = yes
+
; BOM composed of non printable characters. It is here, before the semicolon!
accept = 127.0.0.1:<src_port>
+
setuid = stunnel
connect = <server_host>:<server_port>
+
setgid = stunnel
PSKsecrets = psk.txt}}
+
 
 +
[trivial client]
 +
client     = yes
 +
accept     = 127.0.0.1:<src_port>
 +
connect   = <server_host>:<server_port>
 +
debug      = 3
 +
PSKsecrets = /etc/stunnel/psk.txt
 +
setuid    = stunnel
 +
setgid    = stunnel}}
 +
 
 +
{{hc|server:/etc/stunnel/stunnel.conf|2=
 +
; BOM composed of non printable characters. It is here, before the semicolon!
 +
setuid = stunnel
 +
setgid = stunnel
  
{{hc|server:/etc/stunnel/stunnel.conf|2=[trivial server]
+
[trivial server]
accept = <server_port>
+
accept     = <server_port>
connect = <dst_port>
+
connect   = <dst_port>
ciphers = PSK
+
ciphers   = PSK
PSKsecrets = psk.txt}}
+
debug      = 3
 +
PSKsecrets = /etc/stunnel/psk.txt
 +
setuid    = stunnel
 +
setgid    = stunnel}}
  
 
where {{ic|/etc/stunnel/psk.txt}} could be created on one machine by
 
where {{ic|/etc/stunnel/psk.txt}} could be created on one machine by
  
  # openssl rand -base64 -out /etc/stunnel/psk.txt 40
+
  # openssl rand -base64 -out /etc/stunnel/psk.txt 180
 +
# sed --in-place '1s/^/psk:/' /etc/stunnel/psk.txt
  
and copied to the other machine by secure means before starting stunnel. The files [[permissions]] for each {{ic|psk.txt}} file should be set appropriately.
+
and copied to the other machine by secure means before starting stunnel. The [[permissions]] for each {{ic|psk.txt}} file should be set appropriately. The psk string from the {{ic|sed}} command is just a random name for the sake of the example. Do read {{man|8|stunnel}}.
  
 
== Tips and Tricks ==
 
== Tips and Tricks ==

Latest revision as of 15:10, 4 July 2019

stunnel (“Secure Tunnel”) is a

multi-platform application used to provide a universal TLS/SSL tunneling service. It is sort of proxy designed to add TLS encryption functionality to existing clients and servers without any changes in the programs' code. It is designed for security, portability, and scalability (including load-balancing), making it suitable for large deployments. It uses openssl, and distributed under GNU GPL version 2 or later with OpenSSL exception.

Can tunnel only TCP packets. Its FAQ has some work around for UDP. WireGuard also has UDP capabilities.

Authentication can also be used by the server to allow access only to approved clients.

Installation

Install stunnel from official repositories.

Depending on your usage, you might also Systemd#Editing_provided_units to better Systemd#Handling_dependencies. In order for the stunnel to start up automatically at system boot you must enable it.

setup

The main configuration file is read from /etc/stunnel/stunnel.conf. It is an ini-style file. It is composed from a global section, followed by one, or more, service sections.

A client is one to accept non TLS encrypted data. Stunnel will TLS encrypts its data and connects to the stunnel server. The stunnel server accepts TLS encrypted data and extracts it. It then connects to where the data should be sent to.

The default debug value is 5, which is very verbose. After verifying correct operation, it is worth explicitly setting lower value in the configuration file.

/etc/stunnel/stunnel.conf
debug = 3

For better security, it is advised to explicitly set an appropriate uid and gid, other then root, for the global section and the per service sections. The configuration tokens setuid and setgid are available for this purpose.

Byte order mark (BOM)

The configuration file should have a UTF-8 byte order mark (BOM), at the beginning of the file. A BOM is the unicode character U+FEFF. Its UTF-8 representation is the (hexadecimal) byte sequence 0xEF, 0xBB, 0xBF. Creating a file with these bytes at its beginning can be done by

# echo -e '\xef\xbb\xbf; BOM composed of non printable characters. It is here, before the semicolon!' > /etc/stunnel/stunnel.conf

To test if those bytes appear, one can use

% od --address-radix=n --format=x1c --read-bytes=8 /etc/stunnel/stunnel.conf
  ef  bb  bf  3b  20  42  4f  4d
 357 273 277   ;       B   O   M

Note that when printing the file to the screen, such as with cat, or when editing the file with a text editor, the BOM bytes are usually not displayed. They should be there, though. Which is why you might want to verify that they are still there after editing is completed with the above od, or similar, command.

Authentication

At least one of the client and the server, and optionally both, should be authenticated. Either a pre shared secret, or a key and certificate pair, can be used for authentication. A pre shared secret has to be transferred to all involved machines a priory by other means, such as SCP and SFTP. When such transfer is acceptable, pre shared key is the fastest method. Its speed might help mitigating attacks. A simple configuration for a single server with a single client that are using a pre shared secret is:

client:/etc/stunnel/stunnel.conf
; BOM composed of non printable characters. It is here, before the semicolon!
setuid = stunnel
setgid = stunnel

[trivial client]
client     = yes
accept     = 127.0.0.1:<src_port>
connect    = <server_host>:<server_port>
debug      = 3
PSKsecrets = /etc/stunnel/psk.txt
setuid     = stunnel
setgid     = stunnel
server:/etc/stunnel/stunnel.conf
; BOM composed of non printable characters. It is here, before the semicolon!
setuid = stunnel
setgid = stunnel

[trivial server]
accept     = <server_port>
connect    = <dst_port>
ciphers    = PSK
debug      = 3
PSKsecrets = /etc/stunnel/psk.txt
setuid     = stunnel
setgid     = stunnel

where /etc/stunnel/psk.txt could be created on one machine by

# openssl rand -base64 -out /etc/stunnel/psk.txt 180
# sed --in-place '1s/^/psk:/' /etc/stunnel/psk.txt

and copied to the other machine by secure means before starting stunnel. The permissions for each psk.txt file should be set appropriately. The psk string from the sed command is just a random name for the sake of the example. Do read stunnel(8).

Tips and Tricks

DNS over TLS

bind does not offer builtin facilities for encryption of queries and answers. Bind knowledge base suggests using stunnel. See https://kb.isc.org/docs/aa-01386. The link mentions unbound at the bottom of the page. A user that have only shell accounts on both the client and the server can still tunnel DNS traffic even when both the resolver and the NS do not support DNS over TLS.

Encrypting NFSv4 with Stunnel TLS

See Encrypting NFSv4 with Stunnel TLS

See also