stunnel TLS Proxy

NAZWA

stunnel - uniwersalny tunel protokołu TLS

SKŁADNIA

OPIS

Program stunnel został zaprojektowany do opakowywania w protokół TLS połączeń pomiędzy zdalnymi klientami a lokalnymi lub zdalnymi serwerami. Przez serwer lokalny rozumiana jest aplikacja przeznaczona do uruchamiania przy pomocy inetd. Stunnel pozwala na proste zestawienie komunikacji serwerów nie posiadających funkcjonalności TLS poprzez bezpieczne kanały TLS.

stunnel pozwala dodać funkcjonalność TLS do powszechnie stosowanych demonów inetd, np. pop3 lub imap, do samodzielnych demonów, np. nntp, smtp lub http, a nawet tunelować ppp poprzez gniazda sieciowe bez zmian w kodzie źródłowym.

OPCJE

PLIK KONFIGURACYJNY

Linia w pliku konfiguracyjnym może być:

Parametr adres może być:

OPCJE GLOBALNE

OPCJE USŁUG

Każda sekcja konfiguracji usługi zaczyna się jej nazwą ujętą w nawias kwadratowy. Nazwa usługi używana jest do kontroli dostępu przez bibliotekę libwrap (TCP wrappers) oraz pozwala rozróżnić poszczególne usługi w logach.

Jeżeli stunnel ma zostać użyty w trybie inetd, gdzie za odebranie połączenia odpowiada osobny program (zwykle inetd, xinetd lub tcpserver), należy przeczytać sekcję TRYB INETD poniżej.

ZWRACANA WARTOŚĆ

stunnel zwraca zero w przypadku sukcesu, lub wartość niezerową w przypadku błędu.

SIGNAŁY

Następujące sygnały mogą być użyte do sterowania programem w systemie Unix:

Skutek wysłania innych sygnałów jest niezdefiniowany.

PRZYKŁADY

Szyfrowanie połączeń do lokalnego serwera imapd można użyć:

[imapd]
accept = 993
exec = /usr/sbin/imapd
execArgs = imapd

albo w trybie zdalnym:

[imapd]
accept = 993
connect = 143

Aby umożliwić lokalnemu klientowi poczty elektronicznej korzystanie z serwera imapd przez TLS należy skonfigurować pobieranie poczty z adresu localhost i portu 119, oraz użyć następującej konfiguracji:

[imap]
client = yes
accept = 143
connect = serwer:993

W połączeniu z programem pppd stunnel pozwala zestawić prosty VPN. Po stronie serwera nasłuchującego na porcie 2020 jego konfiguracja może wyglądać następująco:

[vpn]
accept = 2020
exec = /usr/sbin/pppd
execArgs = pppd local
pty = yes

Poniższy plik konfiguracyjny może być wykorzystany do uruchomienia programu stunnel w trybie inetd. Warto zauważyć, że w pliku konfiguracyjnym nie ma sekcji [nazwa_usługi].

exec = /usr/sbin/imapd
execArgs = imapd

Aby skonfigurować VPN można użyć następującej konfiguracji klienta:

[socks_client]
client = yes
accept = 127.0.0.1:1080
connect = vpn_server:9080
verifyPeer = yes
CAfile = stunnel.pem

Odpowiadająca jej konfiguracja serwera vpn_server:

[socks_server]
protocol = socks
accept = 9080
cert = stunnel.pem
key = stunnel.key

Do przetestowania konfiguracji można wydać na maszynie klienckiej komendę:

curl --socks4a localhost http://www.example.com/

Przykładowa konfiguracja serwera SNI:

[virtual]
; usługa nadrzędna
accept = 443
cert =  default.pem
connect = default.internal.mydomain.com:8080

[sni1]
; usługa podrzędna 1
sni = virtual:server1.mydomain.com
cert = server1.pem
connect = server1.internal.mydomain.com:8081

[sni2]
; usługa podrzędna 2
sni = virtual:server2.mydomain.com
cert = server2.pem
connect = server2.internal.mydomain.com:8082
verifyPeer = yes
CAfile = server2-allowed-clients.pem

Przykładowa konfiguracja umożliwiająca uwierzytelnienie z użyciem klucza prywatnego przechowywanego w Windows Certificate Store (tylko Windows):

engine = capi

[service]
engineId = capi
client = yes
accept = 127.0.0.1:8080
connect = example.com:8443

W przypadku użycia silnika CAPI, nie należy ustawiać opcji cert, gdyż klucz klienta zostanie automatycznie pobrany z Certificate Store na podstawie zaufanych certyfikatów CA przedstawionych przez serwer.

Przykładowa konfiguracja umożliwiająca użycie certyfikatu i klucza prywatnego z urządzenia obsługiwanego przez silnik pkcs11:

engine = pkcs11
engineCtrl = MODULE_PATH:opensc-pkcs11.so
engineCtrl = PIN:123456

[service]
engineId = pkcs11
client = yes
accept = 127.0.0.1:8080
connect = example.com:843
cert = pkcs11:token=MyToken;object=MyCert
key = pkcs11:token=MyToken;object=MyKey

Przykładowa konfiguracja umożliwiająca użycie certyfikatu i klucza prywatnego umieszczonego na tokenie SoftHSM:

engine = pkcs11
engineCtrl = MODULE_PATH:softhsm2.dll
engineCtrl = PIN:12345

[service]
engineId = pkcs11
client = yes
accept = 127.0.0.1:8080
connect = example.com:843
cert = pkcs11:token=MyToken;object=KeyCert

Przykładowa konfiguracja umożliwiająca użycie certyfikatu i klucza prywatnego z urządzenia obsługiwanego przez provider `pkcs11prov`:

Uwaga: wymaga OpenSSL 3.0 lub nowszego

setEnv = PKCS11_MODULE_PATH=opensc-pkcs11.dll
setEnv = PKCS11_PIN:123456
provider = pkcs11prov

[service]
client = yes
accept = 127.0.0.1:8080
connect = example.com:843
cert = pkcs11:token=MyToken;object=MyCert
key = pkcs11:token=MyToken;object=MyKey

Uwaga: wymaga OpenSSL 3.5 lub nowszego

provider = pkcs11prov
providerParameter = pkcs11prov:pkcs11_module=opensc-pkcs11.dll
providerParameter = pkcs11prov:pin=123456

[service]
client = yes
accept = 127.0.0.1:8080
connect = example.com:843
cert = pkcs11:token=MyToken;object=MyCert
key = pkcs11:token=MyToken;object=MyKey

W systemie Windows biblioteka PKCS#11 musi znajdować się w katalogu `ossl-modules`, lub należy podać jej pełną ścieżkę bezwzględną w `PKCS11_MODULE_PATH` lub parametrze `pkcs11_module`.

NOTKI

OGRANICZENIA

stunnel nie może być używany do szyfrowania protokołu FTP, ponieważ do przesyłania poszczególnych plików używa on dodatkowych połączeń otwieranych na portach o dynamicznie przydzielanych numerach. Istnieją jednak specjalne wersje klientów i serwerów FTP pozwalające na szyfrowanie przesyłanych danych przy pomocy protokołu TLS.

TRYB INETD (tylko Unix)

W większości zastosowań stunnel samodzielnie nasłuchuje na porcie podanym w pliku konfiguracyjnym i tworzy połączenie z innym portem podanym w opcji connect lub nowym programem podanym w opcji exec. Niektórzy wolą jednak wykorzystywać oddzielny program, który odbiera połączenia, po czym uruchamia program stunnel. Przykładami takich programów są inetd, xinetd i tcpserver.

Przykładowa linia pliku /etc/inetd.conf może wyglądać tak:

imaps stream tcp nowait root <bin-folder>/stunnel
    stunnel <config-folder>/imaps.conf

Ponieważ w takich przypadkach połączenie na zdefiniowanym porcie (tutaj imaps) nawiązuje osobny program (tutaj inetd), stunnel nie może używać opcji accept. W pliku konfiguracyjnym nie może być również zdefiniowana żadna usługa ([nazwa_usługi]), ponieważ konfiguracja taka pozwala na nawiązanie tylko jednego połączenia. Wszystkie OPCJE USŁUG powinny być umieszczone razem z opcjami globalnymi. Przykład takiej konfiguracji znajduje się w sekcji PRZYKŁADY.

CERTYFIKATY

Protokół TLS wymaga, aby każdy serwer przedstawiał się nawiązującemu połączenie klientowi prawidłowym certyfikatem X.509. Potwierdzenie tożsamości serwera polega na wykazaniu, że posiada on odpowiadający certyfikatowi klucz prywatny. Najprostszą metodą uzyskania certyfikatu jest wygenerowanie go przy pomocy wolnego pakietu OpenSSL. Więcej informacji na temat generowania certyfikatów można znaleźć na umieszczonych poniżej stronach.

Plik .pem powinien zawierać klucz prywatny oraz podpisany certyfikat (nie żądanie certyfikatu). Otrzymany plik powinien mieć następującą postać:

-----BEGIN RSA PRIVATE KEY-----
[zakodowany klucz]
-----END RSA PRIVATE KEY-----
-----BEGIN CERTIFICATE-----
[zakodowany certyfikat]
-----END CERTIFICATE-----

LOSOWOŚĆ

stunnel potrzebuje zainicjować PRNG (generator liczb pseudolosowych), gdyż protokół TLS wymaga do bezpieczeństwa kryptograficznego źródła dobrej losowości. Następujące źródła są kolejno odczytywane aż do uzyskania wystarczającej ilości entropii:

Warto zwrócić uwagę, że na maszynach z systemem Windows, na których konsoli nie pracuje użytkownik, zawartość ekranu nie jest wystarczająco zmienna, aby zainicjować PRNG. W takim przypadku do zainicjowania generatora należy użyć opcji RNDfile.

Plik RNDfile powinien zawierać dane losowe -- również w tym sensie, że powinny być one inne przy każdym uruchomieniu programu stunnel. O ile nie użyta została opcja RNDoverwrite jest to robione automatycznie. Do ręcznego uzyskania takiego pliku użyteczna może być komenda openssl rand dostarczana ze współczesnymi wersjami pakietu OpenSSL.

Jeszcze jedna istotna informacja -- jeżeli dostępne jest urządzenie /dev/urandom biblioteka OpenSSL ma zwyczaj zasilania nim PRNG w trakcie sprawdzania stanu generatora. W systemach z /dev/urandom urządzenie to będzie najprawdopodobniej użyte, pomimo że znajduje się na samym końcu powyższej listy. Jest to właściwość biblioteki OpenSSL, a nie programu stunnel.

PARAMETRY DH

Począwszy od wersji 4.40 stunnel zawiera w kodzie programu 2048-bitowe parametry DH. Od wersji 5.18 te początkowe wartości parametrów DH są wymieniane na automatycznie generowane parametry tymczasowe. Wygenerowanie parametrów DH może zająć nawet wiele minut.

Alternatywnie parametry DH można umieścić w pliku razem z certyfikatem, co wyłącza generowanie parametrów tymczasowych:

openssl dhparam 2048 >> stunnel.pem

PLIKI

BŁĘDY

Opcja execArgs oraz linia komend Win32 nie obsługuje cytowania.

ZOBACZ RÓWNIEŻ

AUTOR