STUNNEL(8) stunnel TLS Proxy STUNNEL(8) NAZWA stunnel - uniwersalny tunel protokolu TLS SKLADNIA o Unix: stunnel [PLIK] | -fd N | -help | -version | -sockets | -options o WIN32: stunnel [ [ -install | -uninstall | -start | -stop | -reload | -reopen | -exit ] [-quiet] [PLIK] ] | -help | -version | -sockets | -options OPIS Program stunnel zostal zaprojektowany do opakowywania w protokol TLS polaczen pomiedzy 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 serwerow nie posiadajacych funkcjonalnosci TLS poprzez bezpieczne kanaly TLS. stunnel pozwala dodac funkcjonalnosc TLS do powszechnie stosowanych demonow inetd, np. pop3 lub imap, do samodzielnych demonow, np. nntp, smtp lub http, a nawet tunelowac ppp poprzez gniazda sieciowe bez zmian w kodzie zrodlowym. OPCJE o PLIK uzyj podanego pliku konfiguracyjnego o -fd N (tylko Unix) wczytaj konfiguracje z podanego deskryptora pliku o -help drukuj liste wspieranych opcji o -version drukuj wersje programu i domyslne wartosci parametrow o -sockets drukuj domyslne opcje gniazd o -options drukuj wspierane opcje TLS o -install (tylko Windows NT lub nowszy) instaluj serwis NT o -uninstall (tylko Windows NT lub nowszy) odinstaluj serwis NT o -start (tylko Windows NT lub nowszy) uruchom serwis NT o -stop (tylko Windows NT lub nowszy) zatrzymaj serwis NT o -reload (tylko Windows NT lub nowszy) przeladuj plik konfiguracyjny uruchomionego serwisu NT o -reopen (tylko Windows NT lub nowszy) otworz ponownie log uruchomionego serwisu NT o -exit (tylko Win32) zatrzymaj uruchomiony program o -quiet (tylko Win32) nie wyswietlaj okienek z komunikatami PLIK KONFIGURACYJNY Linia w pliku konfiguracyjnym moze byc: o pusta (ignorowana) o komentarzem rozpoczynajacym sie znakiem `;' (ignorowana) o para `nazwa_opcji = wartosc_opcji' o tekstem `[nazwa_uslugi]' wskazujacym poczatek definicji uslugi Parametr adres moze byc: o numerem portu o oddzielona srednikiem para adresu (IPv4, IPv6, lub nazwa domenowa) i numeru portu o sciezka do gniazda Unix (tylko Unix) OPCJE GLOBALNE o chroot = KATALOG (tylko Unix) katalog roboczego korzenia systemu plikow Opcja okresla katalog, w ktorym uwieziony zostanie proces programu stunnel tuz po jego inicjalizacji, a przed rozpoczeciem odbierania polaczen. Sciezki podane w opcjach CApath, CRLpath, pid oraz exec musza byc umieszczone wewnatrz katalogu podanego w opcji chroot i okreslone wzgledem tego katalogu. Niektore funkcje systemu operacyjnego moga wymagac dodatkowych plikow umieszczonych w katalogu podanego w parametrze chroot: o opoznione rozwiniecie adresow DNS typowo wymaga /etc/nsswitch.conf i /etc/resolv.conf o lokalizacja strefy czasowej w logach wymaga pliku /etc/timezone o niektore inne pliki moga potrzebowac plikow urzadzen, np. /dev/zero lub /dev/null o compression = deflate | zlib | zstd | brotli wybor algorytmu kompresji przesylanych danych domyslnie: bez kompresji Kompresja danych jest dostepna wylacznie dla protokolu TLS 1.2 i starszych. Wymaga obnizenia securityLevel do 1 poczawszy od OpenSSL 1.1.0. Algorytmy zlib, zstd i brotli sa wylaczone w domyslnej konfiguracji OpenSSL. Algorytmy zstd i brotli zostaly dodane w OpenSSL 3.2. Kompresja danych stanowi ryzyko w aplikacjach, ktore umozliwiaja napastnikowi wstrzykniecie wybranego tekstu jawnego. Algorytm deflate jest standardowa metoda kompresji zgodnie z RFC 1951. Uwaga: Kompresja TLS moze umozliwiac ataki prowadzace do odzyskania tekstu jawnego, takie jak CRIME, gdy dane kontrolowane przez atakujacego sa kompresowane razem danymi chronionymi. o debug = [PODSYSTEM].POZIOM szczegolowosc logowania Poziom logowania mozna okreslic przy pomocy jednej z nazw lub liczb: emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6) lub debug (7). Zapisywane sa komunikaty o poziomie nizszym (numerycznie) lub rownym podanemu. Domyslnym poziomem jest notice (5). Jakkolwiek uzycie debug = debug lub debug = 7 zapewnia najbardziej szczegolowe logi, ich zawartosc jest uzyteczna jedynie dla programistow zajmujacych sie stunnelem. Uzyj tego poziomu logowania jedynie jesli jestes programistka/programista stunnela, albo przygotowujesz szczegolowe informacje celem przeslania do wsparcia technicznego. W przeciwnym wypadku proba analizy zawartosci logow bedzie jedynie zrodlem dodatkowego zamieszania. O ile nie wyspecyfikowano podsystemu uzyty bedzie domyslny: daemon. Podsystemy nie sa wspierane przez platforme Win32. Wielkosc liter jest ignorowana zarowno dla poziomu jak podsystemu. o EGD = SCIEZKA_DO_EGD (tylko Unix) sciezka do gniazda programu Entropy Gathering Daemon Opcja pozwala okreslic sciezke do gniazda programu Entropy Gathering Daemon uzywanego do zainicjalizowania generatora ciagow pseudolosowych biblioteki OpenSSL. o engine = auto | IDENTYFIKATOR_URZADZENIA wybor silnika kryptograficznego domyslnie: bez wykorzystania silnikow kryptograficznych Sekcja PRZYKLADY zawiera przykladowe konfiguracje wykorzystujace silniki kryptograficzne. o engineCtrl = KOMENDA[:PARAMETR] konfiguracja silnika kryptograficznego o engineDefault = LISTA_ZADAN lista zadan OpenSSL oddelegowanych do biezacego silnika Parametrem jest lista oddzielonych przecinkami zadan OpenSSL, ktore maja zostac oddelegowane do biezacego silnika kryptograficznego. W zaleznosci od konkretnego silnika dostepne moga byc nastepujace zadania: ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS, DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1. o fips = yes | no tryb FIPS 140-2 Opcja pozwala wylaczyc wejscie w tryb FIPS, jesli stunnel zostal skompilowany ze wsparciem dla FIPS 140-2. domyslnie: no (od wersji 5.00) o foreground = yes | quiet | no (tylko Unix) tryb pierwszoplanowy Uzycie tej opcji powoduje, ze stunnel nie przechodzi w tlo. Parametr yes powoduje dodatkowo, ze komunikaty diagnostyczne logowane sa na standardowy strumien bledow (stderr) oprocz wyjsc zdefiniowanych przy pomocy opcji syslog i output. o iconActive = PLIK_Z_IKONKA (tylko GUI) ikonka wyswietlana przy obecnosci aktywnych polaczen do uslugi W systemie Windows ikonka to plik .ico zawierajacy obrazek 16x16 pikseli. o iconError = PLIK_Z_IKONKA (tylko GUI) ikonka wyswietlana, jezeli nie zostal zaladowany poprawny plik konfiguracyjny W systemie Windows ikonka to plik .ico zawierajacy obrazek 16x16 pikseli. o iconIdle = PLIK_Z_IKONKA (tylko GUI) ikonka wyswietlana przy braku aktywnych polaczen do uslugi W systemie Windows ikonka to plik .ico zawierajacy obrazek 16x16 pikseli. o log = append | overwrite obsluga logow Ta opcja pozwala okreslic, czy nowe logi w pliku (okreslonym w opcji output) beda dodawane czy nadpisywane. domyslnie: append o output = PLIK plik, do ktorego dopisane zostana logi Uzycie tej opcji powoduje dopisanie logow do podanego pliku. Do kierowania komunikatow na standardowe wyjscie (na przyklad po to, zeby zalogowac je programem splogger z pakietu daemontools) mozna podac jako parametr urzadzenie /dev/stdout. o pid = PLIK (tylko Unix) polozenie pliku z numerem procesu Jezeli argument jest pusty, plik nie zostanie stworzony. Jezeli zdefiniowano katalog chroot, to sciezka do pid jest okreslona wzgledem tego katalogu. o provider = PROVIDER_ID Okresla identyfikator dostawcy (provider), ktory ma byc uzywany. PROVIDER_ID to unikalny identyfikator wskazujacy na konkretnego dostawce uslug kryptograficznych. Opcja ta wymaga biblioteki OpenSSL w wersji 3.0 lub nowszej. o providerParameter = PROVIDER_ID:PARAMETER=VALUE Ustawia okreslony parametr dla wskazanego dostawcy. PROVIDER_ID identyfikuje dostawce, PARAMETER to nazwa parametru, a VALUE to jego wartosc. Ta opcja pozwala na dostosowanie konfiguracji wybranego dostawcy uslug kryptograficznych. Opcja ta wymaga biblioteki OpenSSL w wersji 3.5 lub nowszej. o RNDbytes = LICZBA_BAJTOW liczba bajtow do zainicjowania generatora pseudolosowego o RNDfile = PLIK sciezka do pliku zawierajacego losowe dane Biblioteka OpenSSL uzyje danych z tego pliku do zainicjowania generatora pseudolosowego. o RNDoverwrite = yes | no nadpisz plik nowymi wartosciami pseudolosowymi domyslnie: yes (nadpisz) o service = SERWIS (tylko Unix) nazwa uslugi Podana nazwa uslugi bedzie uzywana jako nazwa uslugi dla inicjalizacji sysloga, oraz dla biblioteki TCP Wrapper w trybie inetd. Chociaz technicznie mozna uzyc tej opcji w trybie w sekcji uslug, to jest ona uzyteczna jedynie w opcjach globalnych. domyslnie: stunnel o setEnv = VAR_NAME=VALUE Zmienia lub dodaje zmienna srodowiskowa dla procesow potomnych. Jesli VAR_NAME juz istnieje, jej wartosc zostanie zaktualizowana; w przeciwnym razie zostanie utworzona nowa zmienna. Modyfikacja dotyczy tylko uruchamianych procesow potomnych i nie wplywa na biezace srodowisko. o syslog = yes | no (tylko Unix) wlacz logowanie poprzez mechanizm syslog domyslnie: yes (wlacz) o taskbar = yes | no (tylko WIN32) wlacz ikonke w prawym dolnym rogu ekranu domyslnie: yes (wlacz) OPCJE USLUG Kazda sekcja konfiguracji uslugi zaczyna sie jej nazwa ujeta w nawias kwadratowy. Nazwa uslugi uzywana jest do kontroli dostepu przez biblioteke libwrap (TCP wrappers) oraz pozwala rozroznic poszczegolne uslugi w logach. Jezeli stunnel ma zostac uzyty w trybie inetd, gdzie za odebranie polaczenia odpowiada osobny program (zwykle inetd, xinetd lub tcpserver), nalezy przeczytac sekcje TRYB INETD ponizej. o accept = [HOST:]PORT nasluchuje na polaczenia na podanym adresie i porcie Jezeli nie zostal podany adres, stunnel domyslnie nasluchuje na wszystkich adresach IPv4 lokalnych interfejsow. Aby nasluchiwac na wszystkich adresach IPv6 nalezy uzyc: accept = :::port o CAengine = IDENTYFIKATOR_CA_W_ENGINE laduje zaufane certyfikaty Centrum certyfikacji z silnika Opcja pozwala okreslic polozenie pliku zawierajacego certyfikaty uzywane przez opcje verifyChain lub verifyPeer. Opcja moze byc uzyta wielokrotnie w pojedynczej sekcji. Aktualnie wspierane silniki: pkcs11, cng. o CApath = KATALOG_CA laduje zaufane certyfikaty Centrum certyfikacji z katalogu Opcja okresla katalog, w ktorym stunnel bedzie szukal certyfikatow, jezeli uzyta zostala opcja verifyChain lub verifyPeer. Pliki z certyfikatami musza posiadac specjalne nazwy XXXXXXXX.0, gdzie XXXXXXXX jest skrotem kryptograficznym reprezentacji DER nazwy podmiotu certyfikatu. Ta opcja moze byc rowniez uzyta do dostarczenia certyfikatu root CA, ktory jest niezbedny do prawidlowej weryfikacji OCSP stapling w trybie serwera. Funkcja skrotu zostala zmieniona w OpenSSL 1.0.0. Nalezy wykonac c_rehash przy zmianie OpenSSL 0.x.x na 1.x.x. Jezeli zdefiniowano katalog chroot, to sciezka do CApath jest okreslona wzgledem tego katalogu. o CAfile = PLIK_CA laduje zaufane certyfikaty Centrum certyfikacji z pliku Opcja pozwala okreslic polozenie pliku zawierajacego certyfikaty uzywane przez opcje verifyChain lub verifyPeer. Ta opcja moze byc rowniez uzyta do dostarczenia certyfikatu root CA, ktory jest niezbedny do prawidlowej weryfikacji OCSP stapling w trybie serwera. o CAstore = URI_CA laduje zaufane certyfikaty Centrum certyfikacji z zasobu wskazanego przez URI Opcja umozliwia zaladowanie certyfikatow CA z zewnetrznego magazynu obslugiwanego przez mechanizm OSSL_STORE, takiego jak modul PKCS#11 (np. token sprzetowy), systemowy magazyn certyfikatow lub zasob sieciowy. Opcja moze byc stosowana niezaleznie od CAfile i CAdir, analogicznie sluzy do walidacji lancucha certyfikatow przy uzyciu opcji verifyChain lub verifyPeer, a takze do weryfikacji OCSP stapling po stronie serwera. Opcja ta wymaga biblioteki OpenSSL w wersji 3.0 lub nowszej. o cert = PLIK_CERT | URI plik z lancuchem certyfikatow Opcja okresla polozenie pliku zawierajacego certyfikaty uzywane przez program stunnel do uwierzytelnienia sie przed druga strona polaczenia. Plik powinien zawierac kompletny lancuch certyfikatow poczawszy od certyfikatu klienta/serwera, a skonczywszy na samopodpisanym certyfikacie glownego CA. Obslugiwane sa pliki w formacie PEM lub P12. Certyfikat jest konieczny, aby uzywac programu w trybie serwera. W trybie klienta certyfikat jest opcjonalny. Opcja cert moze byc podana wielokrotnie. Pierwszy napotkany certyfikat zostanie uzyty jako certyfikat serwera lub klienta, natomiast kolejne beda traktowane jako elementy posrednie lancucha. Ta funkcjonalnosc wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej. Jezeli uzywany jest silnik kryptograficzny lub provider, to opcja cert pozwala wybrac identyfikator (PKCS#11 URI) uzywanego certyfikatu. Uwaga: provider wymaga OpenSSL 3.0 lub nowszego o checkEmail = EMAIL adres email podmiotu przedstawionego certyfikatu Pojedyncza sekcja moze zawierac wiele wystapien opcji checkEmail. Certyfikaty sa akceptowane, jezeli sekcja nie weryfikuje podmiotu certyfikatu, albo adres email przedstawionego certyfikatu pasuje do jednego z adresow email okreslonych przy pomocy checkEmail. Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej. o checkHost = NAZWA_SERWERA nazwa serwera podmiotu przedstawionego certyfikatu Pojedyncza sekcja moze zawierac wiele wystapien opcji checkHost. Certyfikaty sa akceptowane, jezeli sekcja nie weryfikuje podmiotu certyfikatu, albo nazwa serwera przedstawionego certyfikatu pasuje do jednego nazw okreslonych przy pomocy checkHost. Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej. o checkIP = IP adres IP podmiotu przedstawionego certyfikatu Pojedyncza sekcja moze zawierac wiele wystapien opcji checkIP. Certyfikaty sa akceptowane, jezeli sekcja nie weryfikuje podmiotu certyfikatu, albo adres IP przedstawionego certyfikatu pasuje do jednego z adresow IP okreslonych przy pomocy checkIP. Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej. o ciphers = LISTA_SZYFROW lista dozwolonych szyfrow dla protokolow SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2 Ta opcja nie wplywa na liste parametrow kryptograficznych dla protokolu TLSv1.3 Parametrem tej opcji jest lista szyfrow, ktore beda uzyte przy otwieraniu nowych polaczen TLS, np.: DES-CBC3-SHA:IDEA-CBC-MD5 o ciphersuites = LISTA_PARAMETROW_KRYPTOGRAFICZNYCH lista dozwolonych parametrow kryptograficznych dla protokolu TLSv1.3 Parametrem tej opcji sa listy parametrow kryptograficznych w kolejnosci ich preferowania. Poczawszy od OpenSSL 3.0 opcja ciphersuites ignoruje nieznane szyfry. Opcja ciphersuites jest dostepna poczawszy od OpenSSL 1.1.1. domyslnie: TLS_CHACHA20_POLY1305_SHA256: TLS_AES_256_GCM_SHA384: TLS_AES_128_GCM_SHA256 o client = yes | no tryb kliencki (zdalna usluga uzywa TLS) domyslnie: no (tryb serwerowy) o config = KOMENDA[:PARAMETR] komenda konfiguracyjna OpenSSL Komenda konfiguracyjna OpenSSL zostaje wykonana z podanym parametrem. Pozwala to na wydawanie komend konfiguracyjnych OpenSSL z pliku konfiguracyjnego stunnela. Dostepne komendy opisane sa w podreczniku SSL_CONF_cmd(3ssl). Mozliwe jest wyspecyfikowanie wielu opcji OpenSSL przez wielokrotne uzycie komendy config. Zamiast wylaczac config = Curves:list_curves uzyj opcji curves w celu ustawienia krzywych eliptycznych. Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej. o connect = [HOST:]PORT polacz sie ze zdalnym serwerem na podany port Jezeli nie zostal podany adres, stunnel domyslnie laczy sie z lokalnym serwerem. Komenda moze byc uzyta wielokrotnie w pojedynczej sekcji celem zapewnienia wysokiej niezawodnosci lub rozlozenia ruchu pomiedzy wiele serwerow. o CRLpath = KATALOG_CRL katalog List Odwolanych Certyfikatow (CRL) Opcja okresla katalog, w ktorym stunnel bedzie szukal list CRL uzywanych przez opcje verifyChain i verifyPeer, a takze przez CRLcheckChain do sprawdzania pelnego lancucha certyfikatow. Pliki z listami CRL musza posiadac specjalne nazwy XXXXXXXX.r0, gdzie XXXXXXXX jest skrotem listy CRL. Funkcja skrotu zostala zmieniona OpenSSL 1.0.0. Nalezy wykonac c_rehash przy zmianie OpenSSL 0.x.x na 1.x.x. Jezeli zdefiniowano katalog chroot, to sciezka do CRLpath jest okreslona wzgledem tego katalogu. o CRLfile = PLIK_CRL plik List Odwolanych Certyfikatow (CRL) Opcja pozwala okreslic polozenie pliku zawierajacego listy CRL uzywane przez opcje verifyChain i verifyPeer, a takze przez CRLcheckChain do sprawdzania pelnego lancucha certyfikatow. o CRLcheckChain = yes | no sprawdzaj listy CRL dla pelnego lancucha certyfikatow drugiej strony polaczenia Opcja wymaga ustawienia verifyChain = yes oraz wskazania zrodla list CRL za pomoca CRLfile lub CRLpath. Domyslnie listy CRL sa sprawdzane tylko dla certyfikatu podmiotu koncowego (liscia) drugiej strony polaczenia. Ustawienie CRLcheckChain = yes dodatkowo wlacza sprawdzanie list CRL dla kazdego certyfikatu w zweryfikowanym lancuchu wystawcow. W trybie pelnego lancucha weryfikacja konczy sie niepowodzeniem, jezeli brakuje odpowiedniej listy CRL wystawcy albo lista ta stracila waznosc lub jest nieprawidlowa. Dla lancucha takiego jak Glowny CA -> Posredni CA -> Certyfikat koncowy lista CRL wystawiona przez posredni CA jest potrzebna do sprawdzenia certyfikatu koncowego, natomiast lista CRL wystawiona przez glowny CA jest potrzebna do sprawdzenia certyfikatu posredniego. domyslnie: no o curves = lista krzywe ECDH odddzielone `:' Uwaga: ta opcja wplywa tylko na gniazda w trybie serwera. Wersje OpenSSL starsze niz 1.1.1 pozwalaja na uzycie tylko jednej krzywej. Liste dostepnych krzywych mozna uzyskac poleceniem: openssl ecparam -list_curves domyslnie: X25519:P-256:X448:P-521:P-384 (poczawszy od OpenSSL 1.1.1) prime256v1 (OpenSSL starszy niz 1.1.1) o logId = TYP typ identyfikatora polaczenia klienta Identyfikator ten pozwala rozroznic wpisy w logu wygenerowane dla poszczegolnych polaczen. Aktualnie wspierane typy: o sequential Kolejny numer polaczenia jest unikalny jedynie w obrebie pojedynczej instancji programu stunnel, ale bardzo krotki. Jest on szczegolnie uzyteczny przy recznej analizie logow. o unique Ten rodzaj identyfikatora jest globalnie unikalny, ale znacznie dluzszy, niz kolejny numer polaczenia. Jest on szczegolnie uzyteczny przy zautomatyzowanej analizie logow. o thread Identyfikator watku systemu operacyjnego nie jest ani unikalny (nawet w obrebie pojedynczej instancji programu stunnel), ani krotki. Jest on szczegolnie uzyteczny przy diagnozowaniu problemow z oprogramowaniem lub konfiguracja. o process Identyfikator procesu (PID) moze byc uzyteczny w trybie inetd. domyslnie: sequential o debug = POZIOM szczegolowosc logowania Poziom logowania mozna okreslic przy pomocy jednej z nazw lub liczb: emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6) lub debug (7). Zapisywane sa komunikaty o poziomie nizszym (numerycznie) lub rownym podanemu. Do uzyskania najwyzszego poziomu szczegolowosci mozna uzyc opcji debug = debug lub debug = 7. Domyslnym poziomem jest notice (5). o delay = yes | no opoznij rozwiniecie adresu DNS podanego w opcji connect Opcja jest przydatna przy dynamicznym DNS, albo gdy usluga DNS nie jest dostepna przy starcie programu stunnel (klient VPN, polaczenie wdzwaniane). Opoznione rozwijanie adresu DNS jest wlaczane automatycznie, jezeli nie powiedzie sie rozwiniecie ktoregokolwiek z adresow connect dla danej uslugi. Opoznione rozwijanie adresu automatycznie aktywuje failover = prio. domyslnie: no o engineId = NUMER_URZADZENIA wybierz silnik kryptograficzny dla uslugi o engineNum = NUMER_URZADZENIA wybierz silnik kryptograficzny dla uslugi Urzadzenia sa numerowane od 1 w gore. o exec = SCIEZKA_DO_PROGRAMU wykonaj lokalny program przystosowany do pracy z superdemonem inetd Jezeli zdefiniowano katalog chroot, to sciezka do exec jest okreslona wzgledem tego katalogu. Na platformach Unix ustawiane sa nastepujace zmienne srodowiskowe: REMOTE_HOST, REMOTE_PORT, SSL_CLIENT_DN, SSL_CLIENT_I_DN. o execArgs = $0 $1 $2 ... argumenty do opcji exec wlacznie z nazwa programu ($0) Cytowanie nie jest wspierane w obecnej wersji programu. Argumenty sa rozdzielone dowolna liczba bialych znakow. o failover = rr | prio Strategia wybierania serwerow wyspecyfikowanych parametrami "connect". o rr round robin - sprawiedliwe rozlozenie obciazenia o prio priority - uzyj kolejnosci opcji w pliku konfiguracyjnym domyslnie: prio o ident = NAZWA_UZYTKOWNIKA weryfikuj nazwe zdalnego uzytkownika korzystajac z protokolu IDENT (RFC 1413) o include = KATALOG wczytaj fragmenty plikow konfiguracyjnych z podanego katalogu Pliki sa wczytywane w rosnacej kolejnosci alfabetycznej ich nazw. Rekomendowana konwencja nazewnictwa plikow dla opcji globalnych: 00-global.conf dla lokalnych opcji uslug: 01-service.conf 02-service.conf o key = PLIK_KLUCZA | URI klucz prywatny do certyfikatu podanego w opcji cert Klucz prywatny jest potrzebny do uwierzytelnienia wlasciciela certyfikatu. Poniewaz powinien on byc zachowany w tajemnicy, prawa do jego odczytu powinien miec wylacznie wlasciciel pliku. W systemie Unix mozna to osiagnac komenda: chmod 600 keyfile Jezeli uzywany jest silnik kryptograficzny lub provider, to opcja key pozwala wybrac identyfikator (PKCS#11 URI) uzywanego klucza prywatnego. Uwaga: provider wymaga OpenSSL 3.0 lub nowszego domyslnie: wartosc opcji cert o libwrap = yes | no wlacz lub wylacz korzystanie z /etc/hosts.allow i /etc/hosts.deny. domyslnie: no (od wersji 5.00) o local = HOST IP zrodla do nawiazywania zdalnych polaczen Domyslnie uzywane jest IP najbardziej zewnetrznego interfejsu w strone serwera, do ktorego nawiazywane jest polaczenie. o OCSP = URL responder OCSP do weryfikacji certyfikatu drugiej strony polaczenia o OCSPaia = yes | no weryfikuj certyfikaty przy uzyciu respondertow AIA Opcja OCSPaia pozwala na weryfikowanie certyfikatow przy pomocy listy URLi responderow OCSP przeslanych w rozszerzeniach AIA (Authority Information Access). o OCSPflag = FLAGA_OCSP flaga respondera OCSP Aktualnie wspierane flagi: NOCERTS, NOINTERN, NOSIGS, NOCHAIN, NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER, RESPID_KEY, NOTIME Aby wyspecyfikowac kilka flag nalezy uzyc OCSPflag wielokrotnie. o OCSPnonce = yes | no wysylaj i weryfikuj OCSP nonce Opcja OCSPnonce zabezpiecza protokol OCSP przed atakami powtorzeniowymi. Ze wzgledu na zlozonosc obliczeniowa rozszerzenie nonce jest zwykle wspierane jedynie przez wewnetrzne (np. korporacyjne), a nie przez publiczne respondery OCSP. o OCSPrequire = yes | no wymagaj rozstrzygajacej odpowiedzi respondera OCSP Wylaczenie tej opcji pozwala na zaakceptowanie polaczenia pomimo braku otrzymania rozstrzygajacej odpowiedzi OCSP ze staplingu i bezposredniego zadania wyslanego do respondera. domyslnie: yes o options = OPCJE_SSL opcje biblioteki OpenSSL Parametrem jest nazwa opcji zgodnie z opisem w SSL_CTX_set_options(3ssl), ale bez przedrostka SSL_OP_. stunnel -options wyswietla opcje dozwolone w aktualnej kombinacji programu stunnel i biblioteki OpenSSL. Aby wyspecyfikowac kilka opcji nalezy uzyc options wielokrotnie. Nazwa opcji moze byc poprzedzona myslnikiem ("-") celem wylaczenia opcji. Na przyklad, dla zachowania kompatybilnosci z bledami implementacji TLS w programie Eudora, mozna uzyc opcji: options = DONT_INSERT_EMPTY_FRAGMENTS domyslnie: options = NO_SSLv2 options = NO_SSLv3 Poczawszy od OpenSSL 1.1.0, zamiast wylaczac okreslone wersje protokolow TLS uzyj opcji sslVersionMax lub sslVersionMin. o protocol = PROTOKOL negocjuj TLS podanym protokolem aplikacyjnym Opcja ta wlacza wstepna negocjacje szyfrowania TLS dla wybranego protokolu aplikacyjnego. Opcji protocol nie nalezy uzywac z szyfrowaniem TLS na osobnym porcie. Aktualnie wspierane protokoly: o cifs Nieudokumentowane rozszerzenie protokolu CIFS wspierane przez serwer Samba. Wsparcie dla tego rozszerzenia zostalo zarzucone w wersji 3.0.0 serwera Samba. o capwin Wsparcie dla aplikacji o capwinctrl Wsparcie dla aplikacji Ten protokol jest wspierany wylacznie w trybie klienckim. o connect Negocjacja RFC 2817 - Upgrading to TLS Within HTTP/1.1, rozdzial 5.2 - Requesting a Tunnel with CONNECT Ten protokol jest wspierany wylacznie w trybie klienckim. o imap Negocjacja RFC 2595 - Using TLS with IMAP, POP3 and ACAP o ldap Negocjacja RFC 2830 - Lightweight Directory Access Protocol (v3): Extension for Transport Layer Security o nntp Negocjacja RFC 4642 - Using Transport Layer Security (TLS) with Network News Transfer Protocol (NNTP) Ten protokol jest wspierany wylacznie w trybie klienckim. o pgsql Negocjacja o pop3 Negocjacja RFC 2449 - POP3 Extension Mechanism o proxy Przekazywanie oryginalnego IP klienta przez protokol HAProxy PROXY w wersji 1 o smtp Negocjacja RFC 2487 - SMTP Service Extension for Secure SMTP over TLS o socks Wspierany jest protokol SOCKS w wersjach 4, 4a i 5. Protokol SOCKS enkapsulowany jest w protokole TLS, wiec adres serwera docelowego nie jest widoczny dla napastnika przechwytujacego ruch sieciowy. Nie jest wspierana komenda BIND protokolu SOCKS. Przeslana wartosc parametru USERID jest ignorowana. Sekcja PRZYKLADY zawiera przykladowe pliki konfiguracyjne VPNa zbudowanego w oparciu o szyfrowany protokol SOCKS. o protocolAuthentication = UWIERZYTELNIENIE rodzaj uwierzytelnienia do negocjacji protokolu Opcja ta jest wpierana wylacznie w klienckich protokolach `connect' i `smtp'. W protokole `connect' wspierane jest uwierzytelnienie `basic' oraz `ntlm'. Domyslnym rodzajem uwierzytelnienia protokolu `connect' jest `basic'. W protokole `smtp' wspierane jest uwierzytelnienie `plain' oraz `login'. Domyslnym rodzajem uwierzytelnienia protokolu `smtp' jest `plain'. o protocolDomain = DOMENA domena do negocjacji protokolu W obecnej wersji opcja ma zastosowanie wylacznie w protokole `connect'. o protocolHeader = NAGLOWEK naglowek do negocjacji protokolu W obecnej wersji opcja ma zastosowanie wylacznie w protokole `connect'. o protocolHost = ADRES adres hosta do negocjacji protokolu Dla protokolu `connect', protocolHost okresla docelowy serwer TLS, do ktorego polaczyc ma sie proxy. Adres serwera proxy, do ktorego laczy sie stunnel, musi byc okreslony przy pomocy opcji connect. Dla protokolu `smtp', protocolHost okresla wartosc HELO/EHLO wysylanego przy negocjacji klienta. o protocolPassword = HASLO haslo do negocjacji protokolu Opcja ta jest wspierana wylacznie w klienckich protokolach `connect' i `smtp'. o protocolUsername = UZYTKOWNIK nazwa uzytkownika do negocjacji protokolu Opcja ta jest wspierana wylacznie w klienckich protokolach `connect' i `smtp'. o PSKidentity = TOZSAMOSC tozsamosc klienta PSK PSKidentity moze zostac uzyte w sekcjach klienckich do wybrania tozsamosci uzytej do uwierzytelnienia PSK. Opcja jest ignorowana w sekcjach serwerowych. domyslnie: pierwsza tozsamosc zdefiniowana w pliku PSKsecrets o PSKsecrets = PLIK plik z tozsamosciami i kluczami PSK Kazda linia pliku jest w nastepujacym formacie: TOZSAMOSC:KLUCZ Szesnastkowe klucze sa automatycznie konwertowane do postaci binarnej. Klucz musi byc miec przynajmniej 16 bajtow, co w przypadku kluczy szesnastkowych przeklada sie na przynajmniej 32 znaki. Nalezy ograniczyc dostep do czytania lub pisania do tego pliku. o pty = yes | no (tylko Unix) alokuj pseudo-terminal dla programu uruchamianego w opcji `exec' o redirect = [HOST:]PORT przekieruj klienta, ktoremu nie udalo sie poprawnie uwierzytelnic przy pomocy certyfikatu Opcja dziala wylacznie w trybie serwera. Czesc negocjacji protokolow jest niekompatybilna z opcja redirect. o renegotiation = yes | no pozwalaj na renegocjacje TLS Zastosowania renegocjacji TLS zawieraja niektore scenariusze uwierzytelniania oraz renegocjacje kluczy dla dlugotrwalych polaczen. Z drugiej strony wlasnosc na moze ulatwic trywialny atak DoS poprzez wygenerowanie obciazenia procesora: Warto zauwazyc, ze zablokowanie renegocjacji TLS nie zabezpiecza w pelni przed opisanym problemem. domyslnie: yes (o ile wspierane przez OpenSSL) o reset = yes | no sygnalizuj wystapienie bledu przy pomocy flagi TCP RST Opcja nie jest wspierana na niektorych platformach. domyslnie: yes o retry = yes | no | OPOZNIENIE polacz ponownie sekcje connect+exec po rozlaczeniu Wartosc parametru OPOZNIENIE okresla liczbe milisekund oczekiwania przed wykonaniem ponownego polaczenia. "retry = yes" jest synonimem dla "retry = 1000". domyslnie: no o securityLevel = POZIOM ustaw poziom bezpieczenstwa Znaczenie kazdego poziomu opisano ponizej: o poziom 0 Wszystko jest dozwolone. o poziom 1 Poziom bezpieczenstwa zapewniajacy minimum 80 bitow bezpieczenstwa. Zadne parametry kryptograficzne oferujace poziom bezpieczenstwa ponizej 80 bitow nie moga zostac uzyte. W zwiazku z tym RSA, DSA oraz klucze DH krotsze niz 1024 bity, a takze klucze ECC krotsze niz 160 bitow i wszystkie eksportowe zestawy szyfrow sa niedozwolone. Uzycie SSLv2 jest zabronione. Wszelkie listy parametrow kryptograficznych uzywajace MD5 do MAC sa zabronione. Poczawszy od OpenSSL 3.0 wersje TLS starsze niz 1.2 sa wylaczone. o poziom 2 Poziom bezpieczenstwa zapewniajacy 112 bitow bezpieczenstwa. W zwiazku z tym RSA, DSA oraz klucze DH krotsze niz 2048 bitow, a takze klucze ECC krotsze niz 224 bity sa niedozwolone. Oprocz wylaczen z poziomu 1 zabronione jest takze korzystanie z zestawow szyfrow uzywajacych RC4. Kompresja jest wylaczona. Uzycie SSLv3 jest zabronione dla wersji OpenSSL starszych niz 3.0. o poziom 3 Poziom bezpieczenstwa zapewniajacy 128 bitow bezpieczenstwa. W zwiazku z tym RSA, DSA oraz klucze DH krotsze niz 3072 bity, a takze klucze ECC krotsze niz 256 bitow sa niedozwolone. Oprocz wylaczen z poziomu 2 zabronione jest takze korzystanie z zestawow szyfrow nie zapewniajacych utajniania z wyprzedzeniem (forward secrecy). Bilety sesji sa wylaczone. Wersje TLS starsze niz 1.1 sa zabronione dla wersji OpenSSL starszych niz 3.0. o poziom 4 Poziom bezpieczenstwa zapewniajacy 192 bity bezpieczenstwa. W zwiazku z tym RSA, DSA oraz klucze DH krotsze niz 7680 bitow, a takze klucze ECC krotsze niz 384 bity sa niedozwolone. Listy parametrow kryptograficznych uzywajacych SHA1 do MAC sa zabronione. Wersje TLS starsze niz 1.2 sa zabronione dla wersji OpenSSL starszych niz 3.0. o poziom 5 Poziom bezpieczenstwa zapewniajacy 256 bitow bezpieczenstwa. W zwiazku z tym RSA, DSA oraz klucze DH krotsze niz 15360 bitow, a takze klucze ECC krotsze niz 512 bitow sa niedozwolone. o domyslnie: 2 Opcja securityLevel jest dostepna poczawszy od OpenSSL 1.1.0. o requireCert = yes | no wymagaj certyfikatu klienta dla verifyChain lub verifyPeer Przy opcji requireCert ustawionej na no, stunnel akceptuje polaczenia klientow, ktore nie wyslaly certyfikatu. Zarowno verifyChain = yes jak i verifyPeer = yes automatycznie ustawiaja requireCert na yes. domyslnie: no o setgid = IDENTYFIKATOR_GRUPY (tylko Unix) identyfikator grupy Unix Jako opcja globalna: grupa, z ktorej prawami pracowal bedzie stunnel. Jako opcja uslugi: grupa gniazda Unix utworzonego przy pomocy opcji "accept". o setuid = IDENTYFIKATOR_UZYTKOWNIKA (tylko Unix) identyfikator uzytkownika Unix Jako opcja globalna: uzytkownik, z ktorego prawami pracowal bedzie stunnel. Jako opcja uslugi: wlasciciel gniazda Unix utworzonego przy pomocy opcji "accept". o sessionCacheSize = LICZBA_POZYCJI_CACHE rozmiar pamieci podrecznej sesji TLS Parametr okresla maksymalna liczbe pozycji wewnetrznej pamieci podrecznej sesji. Wartosc 0 oznacza brak ograniczenia rozmiaru. Nie jest to zalecane dla systemow produkcyjnych z uwagi na ryzyko ataku DoS przez wyczerpanie pamieci RAM. o sessionCacheTimeout = LICZBA_SEKUND przeterminowanie pamieci podrecznej sesji TLS Parametr okresla czas w sekundach, po ktorym sesja TLS zostanie usunieta z pamieci podrecznej. o sessionResume = yes | no zezwalaj lub nie zezwalaj na wznawianie sesji domyslnie: yes o sessiond = HOST:PORT adres sessiond - serwera cache sesji TLS o sni = NAZWA_USLUGI:WZORZEC_NAZWY_SERWERA (tryb serwera) Uzyj uslugi jako podrzednej (virtualnego serwera) dla rozszerzenia TLS Server Name Indication (RFC 3546). NAZWA_USLUGI wskazuje usluge nadrzedna, ktora odbiera polaczenia od klientow przy pomocy opcji accept. WZORZEC_NAZWY_SERWERA wskazuje nazwe serwera wirtualnego. Wzorzec moze zaczynac sie znakiem `*', np. '*.example.com". Z pojedyncza usluga nadrzedna powiazane jest zwykle wiele uslug podrzednych. Opcja sni moze byc rowniez uzyta wielokrotnie w ramach jednej uslugi podrzednej. Zarowno usluga nadrzedna jak i podrzedna nie moze byc skonfigurowana w trybie klienckim. Opcja connect uslugi podrzednej jest ignorowana w polaczeniu z opcja protocol, gdyz polaczenie do zdalnego serwera jest w tym wypadku nawiazywane przed negocjacja TLS. Uwierzytelnienie przy pomocy biblioteki libwrap jest realizowane dwukrotnie: najpierw dla uslugi nadrzednej po odebraniu polaczenia TCP, a nastepnie dla uslugi podrzednej podczas negocjacji TLS. Opcja sni jest dostepna poczawszy od OpenSSL 1.0.0. o sni = NAZWA_SERWERA (tryb klienta) Uzyj parametru jako wartosci rozszerzenia TLS Server Name Indication (RFC 3546). Pusta wartosc parametru NAZWA_SERWERA wylacza wysylanie rozszerzenia SNI. Opcja sni jest dostepna poczawszy od OpenSSL 1.0.0. o socket = a|l|r:OPCJA=WARTOSC[:WARTOSC] ustaw opcje na akceptujacym/lokalnym/zdalnym gniezdzie Dla opcji linger wartosci maja postac l_onof:l_linger. Dla opcji time wartosci maja postac tv_sec:tv_usec. Przyklady: socket = l:SO_LINGER=1:60 ustaw jednominutowe przeterminowanie przy zamykaniu lokalnego gniazda socket = r:SO_OOBINLINE=yes umiesc dane pozapasmowe (out-of-band) bezposrednio w strumieniu danych wejsciowych dla zdalnych gniazd socket = a:SO_REUSEADDR=no zablokuj ponowne uzywanie portu (domyslnie wlaczone) socket = a:SO_BINDTODEVICE=lo przyjmuj polaczenia wylacznie na interfejsie zwrotnym (ang. loopback) o sslVersion = WERSJA_SSL wersja protokolu TLS Wspierane wersje: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 Dostepnosc konkretnych protokolow zalezy od uzytej wersji OpenSSL. Starsze wersje OpenSSL nie wspieraja TLSv1.1, TLSv1.2, TLSv1.3. Nowsze wersje OpenSSL nie wspieraja SSLv2. Przestarzale protokoly SSLv2 i SSLv3 sa domyslnie wylaczone. Poczawszy od OpenSSL 1.1.0, ustawienie sslVersion = WERSJA_SSL jest rownowazne opcjom sslVersionMax = WERSJA_SSL sslVersionMin = WERSJA_SSL o sslVersionMax = WERSJA_SSL maksymalna wspierana wersja protokolu TLS Wspierane wersje: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 all wlacza wszystkie wersje protokolow az do maksymalnej wersji wspieranej przez biblioteke uzytej wersji OpenSSL. Dostepnosc konkretnych protokolow zalezy od uzytej wersji OpenSSL. Opcja sslVersionMax jest dostepna poczawszy od OpenSSL 1.1.0. domyslnie: all o sslVersionMin = WERSJA_SSL minimalna wspierana wersja protokolu TLS Wspierane wersje: all, SSLv3, TLSv1, TLSv1.1, TLSv1.2, TLSv1.3 all wlacza wszystkie wersje protokolow az do minimalnej wersji wspieranej przez biblioteke uzytej wersji OpenSSL. Dostepnosc konkretnych protokolow zalezy od uzytej wersji OpenSSL. Opcja sslVersionMin jest dostepna poczawszy od OpenSSL 1.1.0. domyslnie: TLSv1 o stack = LICZBA_BAJTOW (z wyjatkiem modelu FORK) rozmiar stosu procesora tworzonych watkow Zbyt duzy stos zwieksza zuzycie pamieci wirtualnej. Zbyt maly stos moze powodowac problemy ze stabilnoscia aplikacji. domyslnie: 65536 bytes (wystarczajacy dla testowanych platform) o ticketKeySecret = SECRET szesnastkowy klucz symetryczny uzywany przez serwer do zapewnienia poufnosci biletow sesji Bilety sesji zdefiniowane w RFC 5077 zapewniaja ulepszona mozliwosc wznawiania sesji, w ktorej implementacja serwera nie jest wymagana do utrzymania stanu sesji. Laczne uzycie opcji ticketKeySecret i ticketMacSecret umozliwia wznawianie sesji na klastrze serwerow lub wznowienie sesji po restarcie serwera. Klucz musi miec rozmiar 16 lub 32 bajtow, co przeklada sie na dokladnie 32 lub 64 cyfry szesnastkowe. Poszczegolne bajty moga byc opcjonalnie oddzielone dwukropkami. Opcja dziala wylacznie w trybie serwera. Opcja ticketKeySecret jest dostepna poczawszy od OpenSSL 1.0.0. Wylaczenie opcji NO_TICKET jest wymagane dla obslugi biletow sesji w OpenSSL-u starszym niz 1.1.1, ale opcja ta jest niekompatybilna z opcja redirect. o ticketMacSecret = SECRET szesnastkowy klucz symetryczny uzywany przez serwer zapewnienia integralnosci biletow sesji Klucz musi miec rozmiar 16 lub 32 bajtow, co przeklada sie na dokladnie 32 lub 64 cyfry szesnastkowe. Poszczegolne bajty moga byc opcjonalnie oddzielone dwukropkami. Opcja dziala wylacznie w trybie serwera. Opcja ticketMacSecret jest dostepna poczawszy od OpenSSL 1.0.0. o TIMEOUTbusy = LICZBA_SEKUND czas oczekiwania na spodziewane dane o TIMEOUTclose = LICZBA_SEKUND czas oczekiwania na close_notify (ustaw na 0, jezeli klientem jest MSIE) o TIMEOUTconnect = LICZBA_SEKUND czas oczekiwania na nawiazanie polaczenia o TIMEOUTidle = LICZBA_SEKUND maksymalny czas utrzymywania bezczynnego polaczenia o TIMEOUTocsp = LICZBA_SEKUND czas oczekiwania na nawiazanie polaczenia z serwerem OCSP o transport = tcp | udp wybor protokolu transportowego Wspierane wartosci: o tcp Standardowy TLS po TCP (domyslnie). o udp DTLS po UDP. Kazdy datagram otwiera nowe polaczenie logiczne w ramach uslugi. Serwer uzywa oddzielnego polaczonego gniazda dla kazdego klienta, a ciasteczka DTLS chronia przed atakami DDoS typu refleksyjnego. domyslnie: tcp o transparent = none | source | destination | both (tylko Unix) tryb przezroczystego proxy na wspieranych platformach Wspierane wartosci: o none Zablokuj wsparcie dla przezroczystego proxy. Jest to wartosc domyslna. o source Przepisz adres, aby nawiazywane polaczenie wydawalo sie pochodzic bezposrednio od klienta, a nie od programu stunnel. Opcja jest aktualnie obslugiwana w: o Trybie zdalnym (opcja connect) w systemie Linux >=2.6.28 Konfiguracja wymaga nastepujacych ustawien iptables oraz routingu (na przyklad w pliku /etc/rc.local lub analogicznym): iptables -t mangle -N DIVERT iptables -t mangle -A PREROUTING -p tcp -m socket -j DIVERT iptables -t mangle -A DIVERT -j MARK --set-mark 1 iptables -t mangle -A DIVERT -j ACCEPT ip rule add fwmark 1 lookup 100 ip route add local 0.0.0.0/0 dev lo table 100 echo 0 >/proc/sys/net/ipv4/conf/lo/rp_filter Konfiguracja ta wymaga, aby stunnel byl wykonywany jako root i bez opcji setuid. o Trybie zdalnym (opcja connect) w systemie Linux 2.2.x Konfiguracja ta wymaga skompilowania jadra z opcja transparent proxy. Docelowa usluga musi byc umieszczona na osobnej maszynie, do ktorej routing kierowany jest poprzez serwer stunnela. Dodatkowo stunnel powinien byc wykonywany jako root i bez opcji setuid. o Trybie zdalnym (opcja connect) w systemie FreeBSD >=8.0 Konfiguracja ta wymaga skonfigurowania firewalla i routingu. stunnel musi byc wykonywany jako root i bez opcji setuid. o Trybie lokalnym (opcja exec) Konfiguracja ta jest realizowana przy pomocy biblioteki libstunnel.so. Do zaladowania biblioteki wykorzystywana jest zmienna srodowiskowa _RLD_LIST na platformie Tru64 lub LD_PRELOAD na innych platformach. o destination Oryginalny adres docelowy jest uzywany zamiast opcji connect. Przykladowa konfiguracja przezroczystego adresu docelowego: [transparent] client = yes accept = transparent = destination Konfiguracja wymaga ustawien iptables, na przyklad w pliku /etc/rc.local lub analogicznym. W przypadku docelowej uslugi umieszczonej na tej samej maszynie: /sbin/iptables -t nat -I OUTPUT -p tcp --dport \ -m ! --uid-owner \ -j DNAT --to-destination : W przypadku docelowej uslugi umieszczonej na zdalnej maszynie: /sbin/iptables -I INPUT -i eth0 -p tcp --dport -j ACCEPT /sbin/iptables -t nat -I PREROUTING -p tcp --dport \ -i eth0 -j DNAT --to-destination : Przezroczysty adres docelowy jest aktualnie wspierany wylacznie w systemie Linux. o both Uzyj przezroczystego proxy zarowno dla adresu zrodlowego jak i docelowego. Dla zapewnienia kompatybilnosci z wczesniejszymi wersjami wspierane sa dwie dodatkowe opcje: o yes Opcja zostala przemianowana na source. o no Opcja zostala przemianowana na none. o verify = POZIOM weryfikuj certyfikat drugiej strony polaczenia Opcja ta jest przestarzala i nalezy ja zastapic przez opcje verifyChain i verifyPeer. o poziom 0 zarzadaj certyfikatu i zignoruj go o poziom 1 weryfikuj, jezeli zostal przedstawiony o poziom 2 weryfikuj z zainstalowanym certyfikatem Centrum Certyfikacji o poziom 3 weryfikuj z lokalnie zainstalowanym certyfikatem drugiej strony o poziom 4 weryfikuj z certyfikatem drugiej strony ignorujac lancuch CA o domyslnie nie weryfikuj o verifyChain = yes | no weryfikuj lancuch certyfikatow drugiej strony Do weryfikacji certyfikatu serwera kluczowe jest, aby wymagac rowniez konkretnego certyfikatu przy pomocy checkHost lub checkIP. Samopodpisany certyfikat glownego CA nalezy umiescic albo w pliku podanym w opcji CAfile, albo w katalogu podanym w opcji CApath. domyslnie: no o verifyPeer = yes | no weryfikuj certyfikat drugiej strony Certyfikat drugiej strony nalezy umiescic albo w pliku podanym w opcji CAfile, albo w katalogu podanym w opcji CApath. domyslnie: no ZWRACANA WARTOSC stunnel zwraca zero w przypadku sukcesu, lub wartosc niezerowa w przypadku bledu. SIGNALY Nastepujace sygnaly moga byc uzyte do sterowania programem w systemie Unix: o SIGHUP Zaladuj ponownie plik konfiguracyjny. Niektore globalne opcje nie beda przeladowane: o chroot o foreground o pid o setgid o setuid Jezeli wykorzystywana jest opcja `setuid' stunnel nie bedzie mogl zaladowac ponownie konfiguracji wykorzystujacej uprzywilejowane (<1024) porty. Jezeli wykorzystywana jest opcja `chroot' stunnel bedzie szukal wszystkich potrzebnych plikow (lacznie z plikiem konfiguracyjnym, certyfikatami, logiem i plikiem pid) wewnatrz katalogu wskazanego przez `chroot'. o SIGUSR1 Zamknij i otworz ponownie log. Funkcja ta moze zostac uzyta w skrypcie rotujacym log programu stunnel. o SIGUSR2 Zapisz w logu liste aktywnych polaczen. o SIGTERM, SIGQUIT, SIGINT Zakoncz dzialanie programu. Skutek wyslania innych sygnalow jest niezdefiniowany. PRZYKLADY Szyfrowanie polaczen do lokalnego serwera imapd mozna uzyc: [imapd] accept = 993 exec = /usr/sbin/imapd execArgs = imapd albo w trybie zdalnym: [imapd] accept = 993 connect = 143 Aby umozliwic lokalnemu klientowi poczty elektronicznej korzystanie z serwera imapd przez TLS nalezy skonfigurowac pobieranie poczty z adresu localhost i portu 119, oraz uzyc nastepujacej konfiguracji: [imap] client = yes accept = 143 connect = serwer:993 W polaczeniu z programem pppd stunnel pozwala zestawic prosty VPN. Po stronie serwera nasluchujacego na porcie 2020 jego konfiguracja moze wygladac nastepujaco: [vpn] accept = 2020 exec = /usr/sbin/pppd execArgs = pppd local pty = yes Ponizszy plik konfiguracyjny moze byc wykorzystany do uruchomienia programu stunnel w trybie inetd. Warto zauwazyc, ze w pliku konfiguracyjnym nie ma sekcji [nazwa_uslugi]. exec = /usr/sbin/imapd execArgs = imapd Aby skonfigurowac VPN mozna uzyc nastepujacej konfiguracji klienta: [socks_client] client = yes accept = 127.0.0.1:1080 connect = vpn_server:9080 verifyPeer = yes CAfile = stunnel.pem Odpowiadajaca jej konfiguracja serwera vpn_server: [socks_server] protocol = socks accept = 9080 cert = stunnel.pem key = stunnel.key Do przetestowania konfiguracji mozna wydac na maszynie klienckiej komende: curl --socks4a localhost http://www.example.com/ Przykladowa konfiguracja serwera SNI: [virtual] ; usluga nadrzedna accept = 443 cert = default.pem connect = default.internal.mydomain.com:8080 [sni1] ; usluga podrzedna 1 sni = virtual:server1.mydomain.com cert = server1.pem connect = server1.internal.mydomain.com:8081 [sni2] ; usluga podrzedna 2 sni = virtual:server2.mydomain.com cert = server2.pem connect = server2.internal.mydomain.com:8082 verifyPeer = yes CAfile = server2-allowed-clients.pem Przykladowa konfiguracja umozliwiajaca uwierzytelnienie z uzyciem 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 uzycia silnika CAPI, nie nalezy ustawiac opcji cert, gdyz klucz klienta zostanie automatycznie pobrany z Certificate Store na podstawie zaufanych certyfikatow CA przedstawionych przez serwer. Przykladowa konfiguracja umozliwiajaca uzycie certyfikatu i klucza prywatnego z urzadzenia obslugiwanego 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 Przykladowa konfiguracja umozliwiajaca uzycie 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 Przykladowa konfiguracja umozliwiajaca uzycie certyfikatu i klucza prywatnego z urzadzenia obslugiwanego 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 znajdowac sie w katalogu `ossl-modules`, lub nalezy podac jej pelna sciezke bezwzgledna w `PKCS11_MODULE_PATH` lub parametrze `pkcs11_module`. NOTKI OGRANICZENIA stunnel nie moze byc uzywany do szyfrowania protokolu FTP, poniewaz do przesylania poszczegolnych plikow uzywa on dodatkowych polaczen otwieranych na portach o dynamicznie przydzielanych numerach. Istnieja jednak specjalne wersje klientow i serwerow FTP pozwalajace na szyfrowanie przesylanych danych przy pomocy protokolu TLS. TRYB INETD (tylko Unix) W wiekszosci zastosowan stunnel samodzielnie nasluchuje na porcie podanym w pliku konfiguracyjnym i tworzy polaczenie z innym portem podanym w opcji connect lub nowym programem podanym w opcji exec. Niektorzy wola jednak wykorzystywac oddzielny program, ktory odbiera polaczenia, po czym uruchamia program stunnel. Przykladami takich programow sa inetd, xinetd i tcpserver. Przykladowa linia pliku /etc/inetd.conf moze wygladac tak: imaps stream tcp nowait root @bindir@/stunnel stunnel @sysconfdir@/stunnel/imaps.conf Poniewaz w takich przypadkach polaczenie na zdefiniowanym porcie (tutaj imaps) nawiazuje osobny program (tutaj inetd), stunnel nie moze uzywac opcji accept. W pliku konfiguracyjnym nie moze byc rowniez zdefiniowana zadna usluga ([nazwa_uslugi]), poniewaz konfiguracja taka pozwala na nawiazanie tylko jednego polaczenia. Wszystkie OPCJE USLUG powinny byc umieszczone razem z opcjami globalnymi. Przyklad takiej konfiguracji znajduje sie w sekcji PRZYKLADY. CERTYFIKATY Protokol TLS wymaga, aby kazdy serwer przedstawial sie nawiazujacemu polaczenie klientowi prawidlowym certyfikatem X.509. Potwierdzenie tozsamosci serwera polega na wykazaniu, ze posiada on odpowiadajacy certyfikatowi klucz prywatny. Najprostsza metoda uzyskania certyfikatu jest wygenerowanie go przy pomocy wolnego pakietu OpenSSL. Wiecej informacji na temat generowania certyfikatow mozna znalezc na umieszczonych ponizej stronach. Plik .pem powinien zawierac klucz prywatny oraz podpisany certyfikat (nie zadanie certyfikatu). Otrzymany plik powinien miec nastepujaca postac: -----BEGIN RSA PRIVATE KEY----- [zakodowany klucz] -----END RSA PRIVATE KEY----- -----BEGIN CERTIFICATE----- [zakodowany certyfikat] -----END CERTIFICATE----- LOSOWOSC stunnel potrzebuje zainicjowac PRNG (generator liczb pseudolosowych), gdyz protokol TLS wymaga do bezpieczenstwa kryptograficznego zrodla dobrej losowosci. Nastepujace zrodla sa kolejno odczytywane az do uzyskania wystarczajacej ilosci entropii: o Zawartosc pliku podanego w opcji RNDfile. o Zawartosc pliku o nazwie okreslonej przez zmienna srodowiskowa RANDFILE, o ile jest ona ustawiona. o Plik .rnd umieszczony w katalogu domowym uzytkownika, jezeli zmienna RANDFILE nie jest ustawiona. o Plik podany w opcji `--with-random' w czasie konfiguracji programu. o Zawartosc ekranu w systemie Windows. o Gniazdo egd, jezeli uzyta zostala opcja EGD. o Gniazdo egd podane w opcji `--with-egd-socket' w czasie konfiguracji programu. o Urzadzenie /dev/urandom. Warto zwrocic uwage, ze na maszynach z systemem Windows, na ktorych konsoli nie pracuje uzytkownik, zawartosc ekranu nie jest wystarczajaco zmienna, aby zainicjowac PRNG. W takim przypadku do zainicjowania generatora nalezy uzyc opcji RNDfile. Plik RNDfile powinien zawierac dane losowe -- rowniez w tym sensie, ze powinny byc one inne przy kazdym uruchomieniu programu stunnel. O ile nie uzyta zostala opcja RNDoverwrite jest to robione automatycznie. Do recznego uzyskania takiego pliku uzyteczna moze byc komenda openssl rand dostarczana ze wspolczesnymi wersjami pakietu OpenSSL. Jeszcze jedna istotna informacja -- jezeli dostepne jest urzadzenie /dev/urandom biblioteka OpenSSL ma zwyczaj zasilania nim PRNG w trakcie sprawdzania stanu generatora. W systemach z /dev/urandom urzadzenie to bedzie najprawdopodobniej uzyte, pomimo ze znajduje sie na samym koncu powyzszej listy. Jest to wlasciwosc biblioteki OpenSSL, a nie programu stunnel. PARAMETRY DH Poczawszy od wersji 4.40 stunnel zawiera w kodzie programu 2048-bitowe parametry DH. Od wersji 5.18 te poczatkowe wartosci parametrow DH sa wymieniane na automatycznie generowane parametry tymczasowe. Wygenerowanie parametrow DH moze zajac nawet wiele minut. Alternatywnie parametry DH mozna umiescic w pliku razem z certyfikatem, co wylacza generowanie parametrow tymczasowych: openssl dhparam 2048 >> stunnel.pem PLIKI o @sysconfdir@/stunnel/stunnel.conf plik konfiguracyjny programu BLEDY Opcja execArgs oraz linia komend Win32 nie obsluguje cytowania. ZOBACZ ROWNIEZ o aplikacja stunnel o biblioteka OpenSSL AUTOR o Michal Trojnara stunnel 5.80 2026.07.31 STUNNEL(8)