stunnel4/doc/stunnel.pl.pod

1158 lines
30 KiB
Plaintext
Raw Normal View History

2017-03-28 09:58:13 +02:00
=head1 NAZWA
=encoding utf8
stunnel - uniwersalny tunel protokołu SSL
=head1 SKŁADNIA
=over 4
=item B<Unix:>
B<stunnel> [<S<plik>>] | S<-fd n> | S<-help> | S<-version> | S<-sockets>
=item B<WIN32:>
B<stunnel> [ [S<-install> | S<-uninstall> | S<-start> | S<-stop> ] | S<-exit>]
[S<-quiet>] [<S<plik>>] ] | S<-help> | S<-version> | S<-sockets>
=back
=head1 OPIS
Program B<stunnel> został zaprojektowany do opakowywania w protokół I<SSL>
połączeń pomiędzy zdalnymi klientami a lokalnymi lub zdalnymi serwerami.
Przez serwer lokalny rozumiana jest aplikacja przeznaczona do uruchamiania
przy pomocy I<inetd>.
Stunnel pozwala na proste zestawienie komunikacji serwerów nie posiadających
funkcjonalności I<SSL> poprzez bezpieczne kanały I<SSL>.
B<stunnel> pozwala dodać funkcjonalność I<SSL> do powszechnie stosowanych
demonów I<inetd>, np. I<pop3> lub I<imap>, do samodzielnych demonów,
np. I<nntp>, I<smtp> lub I<http>, a nawet tunelować ppp poprzez gniazda sieciowe
bez zmian w kodzie źródłowym.
=head1 OPCJE
=over 4
=item <B<plik>>
użyj podanego pliku konfiguracyjnego
=item B<-fd n> (tylko Unix)
wczytaj konfigurację z podanego deskryptora pliku
=item B<-help>
drukuj listę wspieranych opcji
=item B<-version>
drukuj wersję programu i domyślne wartości parametrów
=item B<-sockets>
drukuj domyślne opcje gniazd
=item B<-install> (tylko NT/2000/XP)
instaluj serwis NT
=item B<-uninstall> (tylko NT/2000/XP)
odinstaluj serwis NT
=item B<-start> (tylko NT/2000/XP)
uruchom serwis NT
=item B<-stop> (tylko NT/2000/XP)
zatrzymaj serwis NT
=item B<-exit> (tylko Win32)
zatrzymaj uruchomiony program
=item B<-quiet> (tylko NT/2000/XP)
nie wyświetlaj okienka informującego o pomyślnym zainstalowaniu lub
odinstalowaniu
=back
=head1 PLIK KONFIGURACYJNY
Linia w pliku konfiguracyjnym może być:
=over 4
2017-03-28 10:18:03 +02:00
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
pusta (ignorowana)
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
komentarzem rozpoczynającym się znakiem ';' (ignorowana)
=item *
parą 'nazwa_opcji = wartość_opcji'
=item *
tekstem '[nazwa_usługi]' wskazującym początek definicji usługi
2017-03-28 09:58:13 +02:00
=back
Parametr adres może być:
=over 4
2017-03-28 10:18:03 +02:00
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
numerem portu
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item *
oddzieloną średnikiem parą adresu (IPv4, IPv6, lub nazwą domenową) i numeru portu
=item *
ścieżką do gniazda Unix (tylko Unix)
2017-03-28 09:58:13 +02:00
=back
=head2 OPCJE GLOBALNE
=over 4
=item B<chroot> = katalog (tylko Unix)
katalog roboczego korzenia systemu plików
Opcja określa katalog, w którym uwięziony zostanie proces programu
B<stunnel> tuż po jego inicjalizacji, a przed rozpoczęciem odbierania
połączeń. Ścieżki podane w opcjach I<CApath>, I<CRLpath>, I<pid>
oraz I<exec> muszą być umieszczone wewnątrz katalogu podanego w opcji
I<chroot> i określone względem tego katalogu.
2017-03-28 10:18:03 +02:00
Niektóre funkcje systemu operacyjnego mogą wymagać dodatkowych plików umieszczonych w katalogu podanego w parametrze chroot:
=over 4
=item *
opóźnione rozwinięcie adresów DNS typowo wymaga /etc/nsswitch.conf i /etc/resolv.conf
=item *
lokalizacja strefy czasowej w logach wymaga pliku /etc/timezone
=item *
niektóre inne pliki mogą potrzebować plików urządzeń, np. /dev/zero lub /dev/null
=back
2017-03-28 09:58:13 +02:00
=item B<compression> = deflate | zlib | rle
wybór algorytmu kompresji przesyłanych danych
domyślnie: bez kompresji
Algorytm deflate jest standardową metodą kompresji zgodnie z RFC 1951.
2017-03-28 10:18:03 +02:00
Kompresja zlib zaimplementowana w B<OpenSSL 0.9.8> i nowszych nie jest
kompatybilna implementacją B<OpenSSL 0.9.7>.
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
Kompresja rle nie jest zaimplementowana w aktualnych wersjach B<OpenSSL>.
2017-03-28 09:58:13 +02:00
=item B<debug> = poziom[.podsystem]
szczegółowość logowania
Poziom logowania można określić 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 są komunikaty o poziomie niższym (numerycznie) lub równym podanemu.
Do uzyskania najwyższego poziomu szczegółowości można użyć opcji
I<debug = debug> lub I<debug = 7>. Domyślnym poziomem jest notice (5).
O ile nie wyspecyfikowano podsystemu użyty będzie domyślny: daemon.
Podsystemy nie są wspierane przez platformę Win32.
Wielkość liter jest ignorowana zarówno dla poziomu jak podsystemu.
=item B<EGD> = ścieżka_do_EGD (tylko Unix)
ścieżka do gniazda programu Entropy Gathering Daemon
Opcja pozwala określić ścieżkę do gniazda programu Entropy Gathering Daemon
używanego do zainicjalizowania generatora ciągów pseudolosowych biblioteki
2017-03-28 10:18:03 +02:00
B<OpenSSL>. Opcja jest dostępna z biblioteką B<OpenSSL 0.9.5a> lub nowszą.
2017-03-28 09:58:13 +02:00
=item B<engine> = auto | <identyfikator urządzenia>
wybór sprzętowego urządzenia kryptograficznego
domyślnie: bez wykorzystania urządzeń kryptograficznych
Przykładowa konfiguracja umożliwiająca odczytanie klucza prywatnego z
urządzenia zgodnego z OpenSC:
engine=dynamic
engineCtrl=SO_PATH:/usr/lib/opensc/engine_pkcs11.so
engineCtrl=ID:pkcs11
engineCtrl=LIST_ADD:1
engineCtrl=LOAD
engineCtrl=MODULE_PATH:/usr/lib/pkcs11/opensc-pkcs11.so
engineCtrl=INIT
[service]
engineNum=1
key=id_45
=item B<engineCtrl> = <command>[:<parameter>]
konfiguracja urządzenia kryptograficznego
Specjalne komendy "LOAD" i "INIT" pozwalają na załadowanie i inicjalizację
modułu kryptograficznego urządzenia.
=item B<fips> = yes | no
Włącz lub wyłącz tryb FIPS 140-2.
2017-03-28 10:18:03 +02:00
Opcja pozwala wyłączyć wejście w tryb FIPS, jeśli B<stunnel> został
skompilowany ze wsparciem dla FIPS 140-2.
2017-03-28 09:58:13 +02:00
domyślnie: yes (pracuj w trybie FIPS 140-2)
=item B<foreground> = yes | no (tylko Unix)
tryb pierwszoplanowy
2017-03-28 10:18:03 +02:00
Użycie tej opcji powoduje, że B<stunnel> nie przechodzi w tło logując
2017-03-28 09:58:13 +02:00
swoje komunikaty na konsolę zamiast przez I<syslog> (o ile nie użyto
opcji I<output>).
=item B<output> = plik
plik, do którego dopisane zostaną logi
Użycie tej opcji powoduje dopisanie logów do podanego pliku.
Do kierowaniakomunikatów na standardowe wyjście (na przykład po to, żeby
zalogować je programem splogger z pakietu daemontools) można podać jako
parametr urządzenie /dev/stdout.
=item B<pid> = plik (tylko Unix)
położenie pliku z numerem procesu
Jeżeli argument jest pusty plik nie zostanie stworzony.
Jeżeli zdefiniowano katalog I<chroot>, to ścieżka do I<pid> jest określona
względem tego katalogu.
=item B<RNDbytes> = liczba_bajtów
liczba bajtów do zainicjowania generatora pseudolosowego
2017-03-28 10:18:03 +02:00
W wersjach biblioteki B<OpenSSL> starszych niż B<0.9.5a> opcja ta określa
2017-03-28 09:58:13 +02:00
również liczbę bajtów wystarczających do zainicjowania PRNG.
Nowsze wersje biblioteki mają wbudowaną funkcję określającą, czy
dostarczona ilość losowości jest wystarczająca do zainicjowania generatora.
=item B<RNDfile> = plik
ścieżka do pliku zawierającego losowe dane
2017-03-28 10:18:03 +02:00
Biblioteka B<OpenSSL> użyje danych z tego pliku do zainicjowania
2017-03-28 09:58:13 +02:00
generatora pseudolosowego.
=item B<RNDoverwrite> = yes | no
nadpisz plik nowymi wartościami pseudolosowymi
domyślnie: yes (nadpisz)
=item B<service> = nazwa_serwisu (tylko Unix)
użyj parametru jako nazwy serwisu dla biblioteki TCP Wrapper w trybie I<inetd>
domyślnie: stunnel
=item B<setgid> = identyfikator_grupy (tylko Unix)
2017-03-28 10:18:03 +02:00
grupa z której prawami pracował będzie B<stunnel>
2017-03-28 09:58:13 +02:00
=item B<setuid> = identyfikator_użytkownika (tylko Unix)
2017-03-28 10:18:03 +02:00
użytkownik, z którego prawami pracował będzie B<stunnel>
2017-03-28 09:58:13 +02:00
=item B<socket> = a|l|r:option=value[:value]
ustaw opcję na akceptującym/lokalnym/zdalnym gnieździe
Dla opcji linger wartości mają postać l_onof:l_linger.
Dla opcji time wartości mają postać tv_sec:tv_usec.
Przykłady:
socket = l:SO_LINGER=1:60
ustaw jednominutowe przeterminowanie
przy zamykaniu lokalnego gniazda
socket = r:SO_OOBINLINE=yes
umieść dane pozapasmowe (out-of-band)
bezpośrednio w strumieniu danych
wejściowych dla zdalnych gniazd
socket = a:SO_REUSEADDR=no
zablokuj ponowne używanie portu
(domyślnie włączone)
socket = a:SO_BINDTODEVICE=lo
przyjmuj połączenia wyłącznie na
interfejsie zwrotnym (ang. loopback)
=item B<syslog> = yes | no (tylko Unix)
włącz logowanie poprzez mechanizm syslog
domyślnie: yes (włącz)
=item B<taskbar> = yes | no (tylko WIN32)
włącz ikonkę w prawym dolnym rogu ekranu
domyślnie: yes (włącz)
=back
=head2 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 B<stunnel> ma zostać użyty w trybie I<inetd>, gdzie za odebranie
połączenia odpowiada osobny program (zwykle I<inetd>, I<xinetd>
lub I<tcpserver>), należy przeczytać sekcję I<TRYB INETD> poniżej.
=over 4
=item B<accept> = [adres:]port
nasłuchuje na połączenia na podanym adresie i porcie
2017-03-28 10:18:03 +02:00
Jeżeli nie został podany adres, B<stunnel> domyślnie nasłuchuje
2017-03-28 09:58:13 +02:00
na wszystkich adresach IPv4 lokalnych interfejsów.
Aby nasłuchiwać na wszystkich adresach IPv6 należy użyć:
accept = :::port
=item B<CApath> = katalog_CA
katalog Centrum Certyfikacji
Opcja określa katalog, w którym B<stunnel> będzie szukał certyfikatów,
jeżeli użyta została opcja I<verify>. Pliki z certyfikatami muszą
posiadać specjalne nazwy XXXXXXXX.0, gdzie XXXXXXXX jest skrótem
kryptograficznym reprezentacji DER nazwy podmiotu certyfikatu.
2017-03-28 10:18:03 +02:00
Funkcja skrótu została zmieniona w B<OpenSSL 1.0.0>.
Należy wykonać c_rehash przy zmianie B<OpenSSL 0.x.x> na B<1.x.x>.
2017-03-28 09:58:13 +02:00
Jeżeli zdefiniowano katalog I<chroot>, to ścieżka do I<CApath> jest określona
względem tego katalogu.
=item B<CAfile> = plik_CA
plik Centrum Certyfikacji
Opcja pozwala określić położenie pliku zawierającego certyfikaty używane
przez opcję I<verify>.
=item B<cert> = plik_pem
plik z łańcuchem certyfikatów
Opcja określa położenie pliku zawierającego certyfikaty używane przez
program B<stunnel> do uwierzytelnienia się przed drugą stroną połączenia.
Certyfikat jest konieczny, aby używać programu w trybie serwera.
W trybie klienta certyfikat jest opcjonalny.
=item B<ciphers> = lista_szyfrów
lista dozwolonych szyfrów SSL
Parametrem tej opcji jest lista szyfrów, które będą użyte przy
otwieraniu nowych połączeń SSL, np.: DES-CBC3-SHA:IDEA-CBC-MD5
=item B<client> = yes | no
tryb kliencki (zdalna usługa używa SSL)
domyślnie: no (tryb serwerowy)
=item B<connect> = [adres:]port
połącz się ze zdalnym serwerem na podany port
2017-03-28 10:18:03 +02:00
Jeżeli nie został podany adres, B<stunnel> domyślnie łączy się
2017-03-28 09:58:13 +02:00
z lokalnym serwerem.
Komenda może byc użyta wielokrotnie w pojedynczej sekcji
celem zapewnienia wysokiej niezawodności lub rozłożenia
ruchu pomiędzy wiele serwerów.
=item B<CRLpath> = katalog_CRL
katalog List Odwołanych Certyfikatów (CRL)
Opcja określa katalog, w którym B<stunnel> będzie szukał list CRL,
jeżeli użyta została opcja I<verify>. Pliki z listami CRL muszą
posiadać specjalne nazwy XXXXXXXX.r0, gdzie XXXXXXXX jest skrótem
listy CRL.
2017-03-28 10:18:03 +02:00
Funkcja skrótu została zmieniona B<OpenSSL 1.0.0>.
Należy wykonać c_rehash przy zmianie B<OpenSSL 0.x.x> na B<1.x.x>.
2017-03-28 09:58:13 +02:00
Jeżeli zdefiniowano katalog I<chroot>, to ścieżka do I<CRLpath> jest określona
względem tego katalogu.
=item B<CRLfile> = plik_CRL
plik List Odwołanych Certyfikatów (CRL)
Opcja pozwala określić położenie pliku zawierającego listy CRL używane
przez opcję I<verify>.
=item B<curve> = nid
krzywa dla ECDH
Listę dostępnych krzywych można uzyskać poleceniem:
openssl ecparam -list_curves
domyślnie: prime256v1
=item B<delay> = yes | no
opóźnij rozwinięcie adresu DNS podanego w opcji I<connect>
Opcja jest przydatna przy dynamicznym DNS, albo gdy usługa DNS nie jest
2017-03-28 10:18:03 +02:00
dostępna przy starcie programu B<stunnel> (klient VPN, połączenie wdzwaniane).
2017-03-28 09:58:13 +02:00
=item B<engineNum> = <numer urządzenia>
wybierz urządzenie do odczyta klucza prywatnego
Urządzenia są numerowane od 1 w górę.
=item B<exec> = ścieżka_do_programu
wykonaj lokalny program przystosowany do pracy z superdemonem inetd
Jeżeli zdefiniowano katalog I<chroot>, to ścieżka do I<exec> jest określona
względem tego katalogu.
=item B<execargs> = $0 $1 $2 ...
argumenty do opcji I<exec> włącznie z nazwą programu ($0)
Cytowanie nie jest wspierane w obecnej wersji programu.
Argumenty są rozdzielone dowolną liczbą białych znaków.
=item B<failover> = rr | prio
Strategia wybierania serwerów wyspecyfikowanych parametrami "connect".
rr (round robin) - sprawiedliwe rozłożenie obciążenia
prio (priority) - użyj kolejności opcji w pliku konfiguracyjnym
domyślnie: rr
=item B<ident> = nazwa_użytkownika
weryfikuj nazwę zdalnego użytkownika korzystając z protokołu IDENT (RFC 1413)
=item B<key> = plik_klucza
klucz prywatny do certyfikatu podanego w opcji I<cert>
Klucz prywatny jest potrzebny do uwierzytelnienia właściciela certyfikatu.
Ponieważ powinien on być zachowany w tajemnicy, prawa do jego odczytu
powinien mieć wyłącznie właściciel pliku. W systemie Unix można to osiągnąć
komendą:
chmod 600 keyfile
domyślnie: wartość opcji I<cert>
=item B<libwrap> = yes | no
włącz lub wyłącz korzystanie z /etc/hosts.allow i /etc/hosts.deny.
domyślnie: yes
=item B<local> = serwer
IP źródła do nawiązywania zdalnych połączeń
Domyślnie używane jest IP najbardziej zewnętrznego interfejsu w stronę
serwera, do którego nawiązywane jest połączenie.
2017-03-28 10:18:03 +02:00
=item B<sni> = nazwa_usługi:wzorzec_nazwy_serwera (tryb serwera)
2017-03-28 09:58:13 +02:00
Użyj usługi jako podrzędnej (virtualnego serwera) dla rozszerzenia TLS Server
Name Indication (RFC 3546).
I<nazwa_usługi> wskazuje usługę nadrzędną, która odbiera połączenia od klientów
2017-03-28 10:18:03 +02:00
przy pomocy opcji I<accept>. I<wzorzec_nazwy_serwera> wskazuje nazwę serwera
wirtualnego. Wzorzec może zaczynać się znakiem '*', np. '*.example.com".
Z pojedyńczą usługą nadrzędną powiązane jest zwykle wiele usług podrzędnych.
Opcja I<sni> może być rownież użyta wielokrotnie w ramach jednej usługi
podrzędnej.
2017-03-28 09:58:13 +02:00
Zarówno usługa nadrzędna jak i podrzędna nie może być skonfigurowana w trybie
2017-03-28 10:18:03 +02:00
klienckim.
Opcja I<connect> usługi podrzędnej jest ignorowana w połączeniu z opcją
I<protocol>, gdyż połączenie do zdalnego serwera jest w tym wypadku nawiązywane
przed negocjacją TLS.
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
Uwierzytelnienie przy pomocy biblioteki libwrap jest realizowane dwukrotnie:
najpierw dla usługi nadrzędnej po odebraniu połączenia TCP, a następnie dla
usługi podrzędnej podczas negocjacji TLS.
Opcja I<sni> jest dostępna począwszy od B<OpenSSL 1.0.0>.
2017-03-28 09:58:13 +02:00
=item B<sni> = nazwa_serwera (tryb klienta)
Użyj parametru jako wartości rozszerzenia TLS Server Name Indication
(RFC 3546).
2017-03-28 10:18:03 +02:00
Opcja I<sni> jest dostępna począwszy od B<OpenSSL 1.0.0>.
2017-03-28 09:58:13 +02:00
=item B<OCSP> = URL
serwer OCSP do weryfikacji certyfikatów
=item B<OCSPflag> = flaga
flaga serwera OCSP
aktualnie wspierane flagi: NOCERTS, NOINTERN NOSIGS, NOCHAIN, NOVERIFY,
NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER, RESPID_KEY, NOTIME
Aby wyspecyfikować kilka flag należy użyć I<OCSPflag> wielokrotnie.
=item B<options> = opcje_SSL
2017-03-28 10:18:03 +02:00
opcje biblioteki B<OpenSSL>
2017-03-28 09:58:13 +02:00
Parametrem jest nazwa opcji zgodnie z opisem w I<SSL_CTX_set_options(3ssl)>,
ale bez przedrostka I<SSL_OP_>.
Aby wyspecyfikować kilka opcji należy użyć I<options> wielokrotnie.
Na przykład dla zachowania kompatybilności z błędami implementacji SSL
w programie Eudora można użyć opcji:
options = DONT_INSERT_EMPTY_FRAGMENTS
=item B<protocol> = protokół
2017-03-28 10:18:03 +02:00
negocjuj SSL podanym protokołem aplikacyjnym
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
Opcja ta włącza wstępną negocjację szyfrowania SSL dla wybranego protokołu
aplikacyjnego.
2017-03-28 09:58:13 +02:00
Opcji I<protocol> nie należy używać z szyfrowaniem SSL na osobnym porcie.
Aktualnie wspierane protokoły:
=over 4
=item I<cifs>
Unieudokumentowane rozszerzenie protokołu CIFS wspierane przez serwer Samba.
Wsparcie dla tego rozrzeczenia zostało zarzucone w wersji 3.0.0 serwera Samba.
=item I<connect>
Negocjacja RFC 2817 - I<Upgrading to TLS Within HTTP/1.1>, rozdział 5.2 - I<Requesting a Tunnel with CONNECT>
Ten protokół jest wspierany wyłącznie w trybie klienckim.
=item I<imap>
Negocjacja RFC 2595 - I<Using TLS with IMAP, POP3 and ACAP>
=item I<nntp>
Negocjacja RFC 4642 - I<Using Transport Layer Security (TLS) with Network News Transfer Protocol (NNTP)>
Ten protokół jest wspierany wyłącznie w trybie klienckim.
=item I<pgsql>
Negocjacja http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982
=item I<pop3>
Negocjacja RFC 2449 - I<POP3 Extension Mechanism>
=item I<proxy>
Przekazywanie adresu IP haproxy http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt
=item I<smtp>
Negocjacja RFC 2487 - I<SMTP Service Extension for Secure SMTP over TLS>
=back
=item B<protocolAuthentication> = uwierzytelnienie
rodzaj uwierzytelnienia do negocjacji protokołu
aktualnie wspierane: basic, NTLM
Obecnie typ uwierzytelnienia ma zastosowanie wyłącznie w protokole 'connect'.
domyślnie: basic
=item B<protocolHost> = adres:port
adres docelowy do negocjacji protokołu
2017-03-28 10:18:03 +02:00
I<protocolHost> określa docelowy serwer SSL, do którego połączyć ma się proxy.
Nie jest to adres serwera proxy, do którego połączenie zestawia B<stunnel>.
Adres serwera proxy powinien być określony przy pomocy opcji 'connect'.
W obecnej wersji adres docelowy protokołu ma zastosowanie wyłącznie w protokole
'connect'.
2017-03-28 09:58:13 +02:00
=item B<protocolPassword> = hasło
hasło do negocjacji protokołu
=item B<protocolUsername> = użytkownik
nazwa użytkownika do negocjacji protokołu
=item B<pty> = yes | no (tylko Unix)
alokuj pseudoterminal dla programu uruchamianego w opcji 'exec'
2017-03-28 10:18:03 +02:00
=item B<renegotiation> = yes | no
pozwalaj na renegocjację SSL
Wśród zastosowań renegocjacji SSL są niektóre scenariusze uwierzytelnienia,
oraz renegocjacja kluczy dla długotrwałych połączeń.
Z drugiej strony własność na może ułatwić trywialny atak DoS poprzez
wygenerowanie obciążenia procesora:
http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html
Warto zauważyć, że zablokowanie renegocjacji SSL nie zebezpiecza w pełni
przed opisanym problemem.
domyślnie: yes (o ile wspierane przez B<OpenSSL>)
=item B<reset> = yes | no
sygnalizuj wystąpienie błędu przy pomocy flagi TCP RST
Ta opcja nie jest wspierana na niektórych platformach.
domyślnie: yes
=item B<retry> = yes | no
2017-03-28 09:58:13 +02:00
połącz ponownie sekcję connect+exec po rozłączeniu
domyślnie: no
2017-03-28 10:18:03 +02:00
=item B<sessionCacheSize> = rozmiar
rozmiar pamięci podręcznej sesji SSL
Parametr określa maksymalną liczbę pozycji wewnętrznej pamięci podręcznej
sesji.
Wartość 0 oznacza brak ograniczenia rozmiaru. Nie jest to zalecane dla
systemów produkcyjnych z uwagi na ryzyko ataku DoS przez wyczerpanie pamięci
RAM.
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item B<sessionCacheTimeout> = czas
przeterminowanie pamięci podręcznej sesji SSL
Parametr określa czas w sekundach, po którym sesja SSL zostanie usunięta z
pamięci podręcznej.
2017-03-28 09:58:13 +02:00
=item B<sessiond> = adres:port
adres sessiond - servera cache sesji SSL
=item B<sslVersion> = wersja
wersja protokołu SSL
2017-03-28 10:18:03 +02:00
Dozwolone opcje: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2
2017-03-28 09:58:13 +02:00
=item B<stack> = liczba_bajtów (z wyjątkiem modelu FORK)
rozmiar stosu procesora wątku
=item B<TIMEOUTbusy> = liczba_sekund
czas oczekiwania na spodziewane dane
=item B<TIMEOUTclose> = liczba_sekund
czas oczekiwania na close_notify (ustaw na 0, jeżeli klientem jest MSIE)
=item B<TIMEOUTconnect> = liczba_sekund
czas oczekiwania na nawiązanie połączenia
=item B<TIMEOUTidle> = liczba_sekund
maksymalny czas utrzymywania bezczynnego połączenia
=item B<transparent> = none | source | destination | both (tylko Unix)
tryb przezroczystego proxy na wspieranych platformach
Wspierane opcje:
=over 4
=item B<none>
Zablokuj wsparcie dla przezroczystago proxy. Jest to wartość domyślna.
=item B<source>
Przepisz adres, aby nawiązywane połączenie wydawało się pochodzić
2017-03-28 10:18:03 +02:00
bezpośrednio od klienta, a nie od programu B<stunnel>.
2017-03-28 09:58:13 +02:00
Opcja jest aktualnie obsługiwana w:
=over 4
=item Trybie zdalnym (opcja I<connect>) w systemie I<Linux E<gt>=2.6.28>
Konfiguracja wymaga następujących ustawień iptables oraz routingu
(na przykład 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 B<stunnel> był wykonywany jako root i bez opcji I<setuid>.
=item Trybie zdalnym (opcja I<connect>) w systemie I<Linux 2.2.x>
Konfiguracja ta wymaga skompilowania jądra z opcją I<transparent proxy>.
Docelowa usługa musi być umieszczona na osobnej maszynie, do której routing
2017-03-28 10:18:03 +02:00
kierowany jest poprzez serwer B<stunnela>.
2017-03-28 09:58:13 +02:00
Dodatkowo B<stunnel> powinien być wykonywany jako root i bez opcji I<setuid>.
=item Trybie zdalnym (opcja I<connect>) w systemie I<FreeBSD E<gt>=8.0>
Konfiguracja ta wymaga skonfigurowania firewalla i routingu.
B<stunnel> musi być wykonywany jako root i bez opcji I<setuid>.
=item Trybie lokalnym (opcja I<exec>)
Konfiguracja ta jest realizowana przy pomocy biblioteki I<libstunnel.so>.
Do załadowania biblioteki wykorzystywana jest zmienna środowiskowa _RLD_LIST na
platformie Tru64 lub LD_PRELOAD na innych platformach.
=back
=item I<destination>
Oryginalny adres docelowy jest używany zamiast opcji I<connect>.
Przykładowana konfiguracja przezroczystego adresu docelowego:
[transparent]
client=yes
accept=<port_stunnela>
transparent=destination
Konfiguracja wymaga następujących ustawień iptables
(na przykład w pliku /etc/rc.local lub analogicznym):
/sbin/iptables -I INPUT -i eth0 -p tcp --dport <port_stunnela> -j ACCEPT
/sbin/iptables -t nat -I PREROUTING -i eth0 -p tcp --dport <port_przekierowany> -j DNAT --to-destination <lokalne_ip>:<port_stunnela>
Przezroczysty adres docelowy jest aktualnie wspierany wyłącznie w systemie Linux.
=item I<both>
Użyj przezroczystego proxy zarówno dla adresu źródłowego jak i docelowego.
=back
Dla zapewnienia kompatybilności z wcześniejszymim wersjami wspierane są dwie
dodatkowe opcje:
=over 4
=item I<yes>
Opcja została przemianowana na I<source>.
=item I<no>
Opcja została przemianowana na I<none>.
=back
=item B<verify> = poziom
weryfikuj certyfikat drugiej strony połączenia
=over 4
2017-03-28 10:18:03 +02:00
=item I<poziom 0>
zarządaj certyfikatu i zignoruj go
=item I<poziom 1>
weryfikuj, jeżeli został przedstawiony
=item I<poziom 2>
weryfikuj z zainstalowanym certyfikatem Centrum Certyfikacji
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item I<poziom 3>
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
weryfikuj z lokalnie zainstalowanym certyfikatem drugiej strony
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item I<poziom 4>
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
weryfikuj z certyfikatem drugiej strony ignorując łańcuch CA
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item I<domyślnie>
nie weryfikuj
2017-03-28 09:58:13 +02:00
=back
=back
=head1 ZWRACANA WARTOŚĆ
B<stunnel> zwraca zero w przypadku sukcesu, lub wartość niezerową
w przypadku błędu.
=head1 SIGNAŁY
Następujące sygnały mogą być użyte do sterowania programem w systemie Unix:
=over 4
=item SIGHUP
Załaduj ponownie plik konfiguracyjny.
Niektóre globalne opcje nie będą przeładowane:
=over 4
2017-03-28 10:18:03 +02:00
=item *
chroot
=item *
foreground
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
pid
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
setgid
=item *
setuid
2017-03-28 09:58:13 +02:00
=back
2017-03-28 10:18:03 +02:00
Jeżeli wykorzystywana jest opcja 'setuid' B<stunnel> nie będzie mógł załadować
2017-03-28 09:58:13 +02:00
ponownie konfiguracji wykorzystującej uprzywilejowane (<1024) porty.
2017-03-28 10:18:03 +02:00
Jeżeli wykorzystywana jest opcja 'chroot' B<stunnel> będzie szukał wszystkich
2017-03-28 09:58:13 +02:00
potrzebnych plików (łącznie z plikiem konfiguracyjnym, certyfikatami, logiem i
plikiem pid) wewnątrz katalogu wskazanego przez 'chroot'.
=item SIGUSR1
Zamknij i otwórz ponownie log.
2017-03-28 10:18:03 +02:00
Funkcja ta może zostać użyta w skrypcie rotującym log programu B<stunnel>.
2017-03-28 09:58:13 +02:00
=item SIGTERM, SIGQUIT, SIGINT
Zakończ działanie programu.
=back
Skutek wysłania innych sygnałów jest niezdefiniowany.
=head1 PRZYKŁADY
Szyfrowanie połączeń do lokalnego serwera I<imapd> można użyć:
[imapd]
accept = 993
exec = /usr/sbin/imapd
execargs = imapd
albo w trybie zdalnym:
[imapd]
accept = 993
connect = 143
W połączeniu z programem I<pppd> B<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 B<stunnel> w trybie I<inetd>. Warto zauważyć, że w pliku
konfiguracyjnym nie ma sekcji I<[nazwa_usługi]>.
exec = /usr/sbin/imapd
execargs = imapd
=head1 NOTKI
=head2 OGRANICZENIA
2017-03-28 10:18:03 +02:00
B<stunnel> nie może być używany do szyfrowania protokołu I<FTP>,
2017-03-28 09:58:13 +02:00
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 I<SSL>.
=head2 TRYB INETD (tylko Unix)
W większości zastosowań B<stunnel> samodzielnie nasłuchuje na porcie
podanym w pliku konfiguracyjnym i tworzy połączenie z innym portem
podanym w opcji I<connect> lub nowym programem podanym w opcji I<exec>.
Niektórzy wolą jednak wykorzystywać oddzielny program, który odbiera
połączenia, po czym uruchamia program B<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 /usr/bin/stunnel
stunnel /etc/stunnel/imaps.conf
Ponieważ w takich przypadkach połączenie na zdefiniowanym porcie
(tutaj I<imaps>) nawiązuje osobny program (tutaj I<inetd>), B<stunnel>
nie może używać opcji I<accept>. W pliku konfiguracyjnym nie może
być również zdefiniowana żadna usługa (I<[nazwa_usługi]>), ponieważ
konfiguracja taka pozwala na nawiązanie tylko jednego połączenia.
Wszystkie I<OPCJE USŁUG> powinny być umieszczone razem z opcjami
globalnymi. Przykład takiej konfiguracji znajduje się w sekcji
I<PRZYKŁADY>.
=head2 CERTYFIKATY
Protokół SSL 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.
2017-03-28 10:18:03 +02:00
Najprostszą metodą uzyskania certyfikatu jest wygenerowanie go przy pomocy
wolnego pakietu B<OpenSSL>. Więcej informacji na temat generowania
certyfikatów można znaleźć na umieszczonych poniżej stronach.
2017-03-28 09:58:13 +02:00
Istotną kwestią jest kolejność zawartości pliku I<.pem>.
W pierwszej kolejności powinien on zawierać klucz prywatny,
a dopiero za nim podpisany certyfikat (nie żądanie certyfikatu).
Po certyfikacie i kluczu prywatnym powinny znajdować się puste linie.
Jeżeli przed certyfikatem znajdują się dodatkowe informacje tekstowe,
to powinny one zostać usunięte. Otrzymany plik powinien mieć
następującą postać:
-----BEGIN RSA PRIVATE KEY-----
[zakodowany klucz]
-----END RSA PRIVATE KEY-----
[pusta linia]
-----BEGIN CERTIFICATE-----
[zakodowany certyfikat]
-----END CERTIFICATE-----
[pusta linia]
=head2 LOSOWOŚĆ
B<stunnel> potrzebuje zainicjować PRNG (generator liczb pseudolosowych),
gdyż protokół SSL 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:
=over 4
2017-03-28 10:18:03 +02:00
=item *
Zawartość pliku podanego w opcji I<RNDfile>.
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item *
Zawartość pliku o nazwie określonej przez zmienną środowiskową
2017-03-28 09:58:13 +02:00
RANDFILE, o ile jest ona ustawiona.
2017-03-28 10:18:03 +02:00
=item *
Plik .rnd umieszczony w katalogu domowym użytkownika,
2017-03-28 09:58:13 +02:00
jeżeli zmienna RANDFILE nie jest ustawiona.
2017-03-28 10:18:03 +02:00
=item *
Plik podany w opcji '--with-random' w czasie konfiguracji programu.
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
Zawartość ekranu w systemie Windows.
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
=item *
2017-03-28 09:58:13 +02:00
2017-03-28 10:18:03 +02:00
Gniazdo egd, jeżeli użyta została opcja I<EGD>.
=item *
Gniazdo egd podane w opcji '--with-egd-socket' w czasie konfiguracji
2017-03-28 09:58:13 +02:00
programu.
2017-03-28 10:18:03 +02:00
=item *
Urządzenie /dev/urandom.
2017-03-28 09:58:13 +02:00
=back
2017-03-28 10:18:03 +02:00
Współczesne (B<0.9.5a> lub nowsze) wersje biblioteki B<OpenSSL> automatycznie
2017-03-28 09:58:13 +02:00
zaprzestają ładowania kolejnych danych w momencie uzyskania wystarczającej
ilości entropii. Wcześniejsze wersje biblioteki wykorzystają wszystkie
2017-03-28 10:18:03 +02:00
powyższe źródła, gdyż nie istnieje tam funkcja pozwalająca określić, czy
uzyskano już wystarczająco dużo danych.
2017-03-28 09:58:13 +02:00
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 I<RNDfile>.
Plik I<RNDfile> powinien zawierać dane losowe -- również w tym sensie,
że powinny być one inne przy każdym uruchomieniu programu B<stunnel>.
O ile nie użyta została opcja I<RNDoverwrite> jest to robione
automatycznie. Do ręcznego uzyskania takiego pliku użyteczna
może być komenda I<openssl rand> dostarczana ze współczesnymi
2017-03-28 10:18:03 +02:00
wersjami pakietu B<OpenSSL>.
2017-03-28 09:58:13 +02:00
Jeszcze jedna istotna informacja -- jeżeli dostępne jest urządzenie
2017-03-28 10:18:03 +02:00
I</dev/urandom> biblioteka B<OpenSSL> ma zwyczaj zasilania nim PRNG w trakcie
2017-03-28 09:58:13 +02:00
sprawdzania stanu generatora. W systemach z I</dev/urandom> urządzenie
to będzie najprawdopodobniej użyte, pomimo że znajduje się na samym końcu
2017-03-28 10:18:03 +02:00
powyższej listy. Jest to właściwość biblioteki B<OpenSSL>, a nie programu
B<stunnel>.
2017-03-28 09:58:13 +02:00
=head2 PARAMETRY DH
2017-03-28 10:18:03 +02:00
Począwszy od wersji 4.40 B<stunnel> zawiera w kodzie programu 2048-bitowe
2017-03-28 09:58:13 +02:00
parametry DH.
Alternatywnie parametry DH można umieścić w pliku razem z certyfikatem:
openssl dhparam 2048 >> stunnel.pem
Wygenerowanie parametrów DH może zająć nawet wiele minut.
=head1 PLIKI
=over 4
=item F<stunnel.conf>
plik konfiguracyjny programu
=back
=head1 BŁĘDY
2017-03-28 10:18:03 +02:00
Opcja I<execargs> oraz linia komend Win32 nie obsługuje cytowania.
2017-03-28 09:58:13 +02:00
=head1 ZOBACZ RÓWNIEŻ
=over 4
=item L<tcpd(8)>
biblioteka kontroli dostępu do usług internetowych
=item L<inetd(8)>
'super-serwer' internetowy
=item F<http://www.stunnel.org/>
2017-03-28 10:18:03 +02:00
strona domowa programu B<stunnel>
2017-03-28 09:58:13 +02:00
=item F<http://www.openssl.org/>
2017-03-28 10:18:03 +02:00
strona projektu B<OpenSSL>
2017-03-28 09:58:13 +02:00
=back
=head1 AUTOR
=over 4
=item Michał Trojnara
<F<Michal.Trojnara@mirt.net>>
=back