SKLADNIA

       Unix:
           stunnel [<plik>] | -fd n | -help | -version | -sockets

       WIN32:
           stunnel [ [-install | -uninstall | -start | -stop ]
               [-quiet] [<plik>] ] | -help | -version | -sockets

OPIS

       Program stunnel zosta3 zaprojektowany do opakowywania w protoko3 SSL
       po3+-czen pomiedzy zdalnymi klientami a lokalnymi lub zdalnymi serw-
       erami.  Przez serwer lokalny rozumiana jest aplikacja przeznaczona do
       uruchamiania przy pomocy inetd.  Stunnel pozwala na proste zestawienie
       komunikacji serwerow nie posiadaj+-cych funkcjonalno9|ci SSL poprzez
       bezpieczne kana3y SSL.

       stunnel pozwala dodaae funkcjonalno9|ae SSL do powszechnie stosowanych
       demonow inetd, np. pop3 lub imap, do samodzielnych demonow, np. nntp,
       smtp lub http, a nawet tunelowaae ppp poprzez gniazda sieciowe bez
       zmian w kodzie 1/4rod3owym.

OPCJE

       <plik>
           ucyj podanego pliku konfiguracyjnego

       -fd n (tylko Unix)
           wczytaj konfiguracje z podanego deskryptora pliku

       -help
           drukuj liste wspieranych opcji

       -version
           drukuj wersje programu i domy9|lne warto9|ci parametrow

       -sockets
           drukuj domy9|lne opcje gniazd

       -install (tylko NT/2000/XP)
           instaluj serwis NT

       -uninstall (tylko NT/2000/XP)
           odinstaluj serwis NT

       -start (tylko NT/2000/XP)
           uruchom serwis NT

       -stop (tylko NT/2000/XP)
           zatrzymaj serwis NT

       -quiet (tylko NT/2000/XP)
           nie wy9|wietlaj okienka informuj+-cego o pomy9|lnym zainstalowaniu
           lub odinstalowaniu

       chroot = katalog (tylko Unix)
           katalog roboczego korzenia systemu plikow

           Opcja okre9|la katalog, w ktorym uwieziony zostanie proces programu
           stunnel tuc po jego inicjalizacji, a przed rozpoczeciem odbierania
           po3+-czen.  |ciecki podane w opcjach CApath, CRLpath, pid oraz exec
           musz+- byae umieszczone wewn+-trz katalogu podanego w opcji chroot
           i okre9|lone wzgledem tego katalogu.

           W przypadku wykorzystania kontroli dostepu przy pomocy biblioteki
           libwrap (TCP wrappers) jej pliki konfiguracyjne (/etc/hosts.allow i
           /etc/hosts.deny) musz+- zostaae skopiowane do podkatalogu etc/
           umieszczonego wewn+-trz katalogu podanego w opcji chroot.

       compression = zlib | rle
           wybor algorytmu kompresji przesy3anych danych

           domy9|lnie: bez kompresji

       debug = poziom[.podsystem]
           szczego3owo9|ae logowania

           Poziom logowania mocna okre9|liae 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
           nicszym (numerycznie) lub rownym podanemu.  Do uzyskania
           najwycszego poziomu szczego3owo9|ci mocna ucyae opcji debug = debug
           lub debug = 7.  Domy9|lnym poziomem jest notice (5).

           O ile nie wyspecyfikowano podsystemu ucyty bedzie domy9|lny: dae-
           mon.  Podsystemy nie s+- wspierane przez platforme Win32.

           Wielko9|ae liter jest ignorowana zarowno dla poziomu jak podsys-
           temu.

       EGD = 9|ciecka_do_EGD (tylko Unix)
           9|ciecka do gniazda programu Entropy Gathering Daemon

           Opcja pozwala okre9|liae 9|ciecke do gniazda programu Entropy Gath-
           ering Daemon ucywanego do zainicjalizowania generatora ci+-gow
           pseudolosowych biblioteki OpenSSL.  Opcja jest dostepna z bib-
           liotek+- OpenSSL 0.9.5a lub nowsz+-.

       engine = auto | <identyfikator urz+-dzenia>
           wybor sprzetowego urz+-dzenia kryptograficznego

           domy9|lnie: bez wykorzystania urz+-dzen kryptograficznych

           Przyk3ad wykorzystania w sekcji 'PRZYKLADY'.

       engineCtrl = <command>[:<parameter>]

           Ucycie tej opcji zmienia domy9|lne zachowanie programu polegaj+-ce
           na logowaniu swoich komunikatow poprzez syslog.

           Do przekierowania komunikatow na standardowe wyj9|cie (na przyk3ad
           po to, ceby zalogowaae je programem splogger z pakietu daemontools)
           mocna podaae jako parametr urz+-dzenie /dev/stdout.

       pid = plik (tylko Unix)
           po3ocenie pliku z numerem procesu

           Jeceli argument jest pusty plik nie zostanie stworzony.

           Jeceli zdefiniowano katalog chroot, to 9|ciecka do pid jest
           okre9|lona wzgledem tego katalogu.

       RNDbytes = liczba_bajtow
           liczba bajtow do zainicjowania generatora pseudolosowego

           W wersjach biblioteki OpenSSL starszych nic 0.9.5a opcja ta
           okre9|la rowniec liczbe bajtow wystarczaj+-cych do zainicjowania
           PRNG.  Nowsze wersje biblioteki maj+- wbudowan+- funkcje
           okre9|laj+-c+-, czy dostarczona ilo9|ae losowo9|ci jest wystar-
           czaj+-ca do zainicjowania generatora.

       RNDfile = plik
           9|ciecka do pliku zawieraj+-cego losowe dane

           Biblioteka OpenSSL ucyje danych z tego pliku do zainicjowania gen-
           eratora pseudolosowego.

       RNDoverwrite = yes | no
           nadpisz plik nowymi warto9|ciami pseudolosowymi

           domy9|lnie: yes (nadpisz)

       service = nazwa_serwisu
           ucyj parametru jako nazwy serwisu

           Unix: nazwa serwisu dla biblioteki TCP Wrapper w trybie inetd.

           NT/2000/XP: nazwa serwisu NT w Panelu Sterowania.

           domy9|lnie: stunnel

       setgid = identyfikator_grupy (tylko Unix)
           grupa z ktorej prawami pracowa3 bedzie stunnel

       setuid = identyfikator_ucytkownika (tylko Unix)
           ucytkownik, z ktorego prawami pracowa3 bedzie stunnel

       socket = a|l|r:option=value[:value]
                   umie9|ae dane pozapasmowe (out-of-band)
                   bezpo9|rednio w strumieniu danych
                   wej9|ciowych dla zdalnych gniazd
               socket = a:SO_REUSEADDR=0
                   zablokuj ponowne ucywanie portu
                   (domy9|lnie w3+-czone)
               socket = a:SO_BINDTODEVICE=lo
                   przyjmuj po3+-czenia wy3+-cznie na
                   interfejsie zwrotnym (ang. loopback)

       taskbar = yes | no (tylko WIN32)
           w3+-cz ikonke w prawym dolnym rogu ekranu

           domy9|lnie: yes (w3+-cz)

       OPCJE USLUG

       Kacda sekcja konfiguracji us3ugi zaczyna sie jej nazw+- ujet+- w nawias
       kwadratowy.  Nazwa us3ugi ucywana jest do kontroli dostepu przez bib-
       lioteke libwrap (TCP wrappers) oraz pozwala rozrocniae poszczegolne
       us3ugi w logach.

       Jeceli stunnel ma zostaae ucyty w trybie inetd, gdzie za odebranie
       po3+-czenia odpowiada osobny program (zwykle inetd, xinetd lub
       tcpserver), nalecy przeczytaae sekcje TRYB INETD ponicej.

       accept = [adres:]port
           nas3uchuje na po3+-czenia na podanym adresie i porcie

           Jeceli nie zosta3 podany adres, stunnel domy9|lnie nas3uchuje na
           wszystkich adresach IP lokalnych interfejsow.

       CApath = katalog_CA
           katalog Centrum Certyfikacji

           Opcja okre9|la katalog, w ktorym stunnel bedzie szuka3 certy-
           fikatow, jeceli ucyta zosta3a opcja verify.  Pliki z certyfikatami
           musz+- posiadaae specjalne nazwy XXXXXXXX.0, gdzie XXXXXXXX jest
           skrotem kryptograficznym reprezentacji DER nazwy podmiotu certy-
           fikatu (4 pierwsze bajty skrotu MD5 pocz+-wszy od najmniej znacza-
           cego).

           Jeceli zdefiniowano katalog chroot, to 9|ciecka do CApath jest
           okre9|lona wzgledem tego katalogu.

       CAfile = plik_CA
           plik Centrum Certyfikacji

           Opcja pozwala okre9|liae po3ocenie pliku zawieraj+-cego certyfikaty
           ucywane przez opcje verify.

       cert = plik_pem
           tryb kliencki (zdalna us3uga ucywa SSL)

           domy9|lnie: no (tryb serwerowy)

       connect = [adres:]port
           po3+-cz sie ze zdalnym serwerem na podany port

           Jeceli nie zosta3 podany adres, stunnel domy9|lnie 3+-czy sie z
           lokalnym serwerem.

       CRLpath = katalog_CRL
           katalog List Odwo3anych Certyfikatow (CRL)

           Opcja okre9|la katalog, w ktorym stunnel bedzie szuka3 list CRL,
           jeceli ucyta zosta3a opcja verify.  Pliki z listami CRL musz+-
           posiadaae specjalne nazwy XXXXXXXX.0, gdzie XXXXXXXX jest skrotem
           listy CRL.

           Jeceli zdefiniowano katalog chroot, to 9|ciecka do CRLpath jest
           okre9|lona wzgledem tego katalogu.

       CRLfile = plik_CRL
           plik List Odwo3anych Certyfikatow (CRL)

           Opcja pozwala okre9|liae po3ocenie pliku zawieraj+-cego listy CRL
           ucywane przez opcje verify.

       delay = yes | no
           opo1/4nij rozwiniecie adresu DNS podanego w opcji connect

       engineNum = <numer urz+-dzenia>
           wybierz urz+-dzenie do odczyta klucza prywatnego

           Urz+-dzenia s+- numerowane od 1 w gore.

       exec = 9|ciecka_do_programu (tylko Unix)
           wykonaj lokalny program przystosowany do pracy z superdemonem inetd

           Jeceli zdefiniowano katalog chroot, to 9|ciecka do exec jest
           okre9|lona wzgledem tego katalogu.

       execargs = $0 $1 $2 ... (tylko Unix)
           argumenty do opcji exec w3+-cznie z nazw+- programu ($0)

           Cytowanie nie jest wspierane w obecnej wersji programu.  Argumenty
           s+- rozdzielone dowoln+- liczb+- bia3ych znakow.

       ident = nazwa_ucytkownika
           weryfikuj nazwe zdalnego ucytkownika korzystaj+-c z protoko3u IDENT
           (RFC 1413)

       key = plik_klucza
           Domy9|lnie ucywane jest IP najbardziej zewnetrznego interfejsu w
           strone serwera, do ktorego nawi+-zywane jest po3+-czenie.

       OCSP = URL
           serwer OCSP do weryfikacji certyfikatow

       OCSPflag = flaga
           flaga serwera OCSP

           aktualnie wspierane flagi: NOCERTS, NOINTERN NOSIGS, NOCHAIN,
           NOVERIFY, NOEXPLICIT, NOCASIGN, NODELEGATED, NOCHECKS, TRUSTOTHER,
           RESPID_KEY, NOTIME

           Aby wyspecyfikowaae kilka flag nalecy ucyae OCSPflag wielokrotnie.

       options = opcje_SSL
           opcje biblioteki OpenSSL

           Parametrem jest nazwa opcji zgodnie z opisem w
           SSL_CTX_set_options(3ssl), ale bez przedrostka SSL_OP_.  Aby
           wyspecyfikowaae kilka opcji nalecy ucyae options wielokrotnie.

           Na przyk3ad dla zachowania kompatybilno9|ci z b3edami implementacji
           SSL w programie Eudora mocna ucyae opcji:

               options = DONT_INSERT_EMPTY_FRAGMENTS

       protocol = protoko3
           negocjuj SSL podanym protoko3em aplikacyjnym

           aktualnie wspierane protoko3y: cifs, connect, imap, nntp, pop3,
           smtp

       protocolAuthentication = uwierzytelnienie
           rodzaj uwierzytelnienia do negocjacji protoko3u

           aktualnie wspierane: basic, NTLM

           Obecnie typ uwierzytelnienia ma zastosowanie wy3+-cznie w protokole
           'connect'.

           domy9|lnie: basic

       protocolHost = adres:port
           adres docelowy do negocjacji protoko3u

       protocolPassword = has3o
           has3o do negocjacji protoko3u

       protocolUsername = ucytkownik
           nazwa ucytkownika do negocjacji protoko3u


           Dozwolone opcje: all, SSLv2, SSLv3, TLSv1

       TIMEOUTbusy = liczba_sekund
           czas oczekiwania na spodziewane dane

       TIMEOUTclose = liczba_sekund
           czas oczekiwania na close_notify (ustaw na 0, jeceli klientem jest
           MSIE)

       TIMEOUTconnect = liczba_sekund
           czas oczekiwania na nawi+-zanie po3+-czenia

       TIMEOUTidle = liczba_sekund
           maksymalny czas utrzymywania bezczynnego po3+-czenia

       transparent = yes | no (tylko Unix)
           tryb przezroczystego proxy

           Przepisz adres, aby nawi+-zywane po3+-czenie wydawa3o sie
           pochodziae bezpo9|rednio od klienta, a nie od programu stunnel.
           Opcja dzia3a tylko w trybie lokalnym (opcja exec) przez za3adowanie
           przy pomocy LD_PRELOAD biblioteki env.so, albo w trybie zdalnym
           (opcja connect) na systemie Linux 2.2 z w3+-czon+- opcj+- transpar-
           ent proxy.

       verify = poziom
           weryfikuj certyfikat drugiej strony po3+-czenia

               poziom 1 - weryfikuj, jeceli zosta3
                   przedstawiony
               poziom 2 - weryfikuj z zainstalowanym
                   certyfikatem Centrum Certyfikacji
               poziom 3 - weryfikuj z lokalnie
                   zainstalowanym certyfikatem drugiej strony
               domy9|lnie - nie weryfikuj

ZWRACANA WARTO|AE

       stunnel zwraca zero w przypadku sukcesu, lub warto9|ae niezerow+- w
       przypadku b3edu.

PRZYKLADY

       Szyfrowanie po3+-czen do lokalnego serwera imapd mocna ucyae:

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

       albo w trybie zdalnym:

           [imapd]

       programu stunnel w trybie inetd.  Warto zauwacyae, ce w pliku konfigu-
       racyjnym nie ma sekcji [nazwa_us3ugi].

           exec = /usr/sbin/imapd
           execargs = imapd

       Przyk3adowa konfiguracja umocliwiaj+-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

PLIKI

       stunnel.conf
           plik konfiguracyjny programu

       stunnel.pem
           certyfikat i klucz prywatny

BLEDY

       Opcja execargs nie obs3uguje cytowania.

OGRANICZENIA

       stunnel nie moce byae ucywany do szyfrowania protoko3u FTP, poniewac do
       przesy3ania poszczegolnych plikow ucywa on dodatkowych po3+-czen
       otwieranych na portach o dynamicznie przydzielanych numerach.  Ist-
       niej+- jednak specjalne wersje klientow i serwerow FTP pozwalaj+-ce na
       szyfrowanie przesy3anych danych przy pomocy protoko3u SSL.

NOTKI

       TRYB INETD (tylko Unix)

       W wiekszo9|ci zastosowan stunnel samodzielnie nas3uchuje na porcie
       podanym w pliku konfiguracyjnym i tworzy po3+-czenie z innym portem
       podanym w opcji connect lub nowym programem podanym w opcji exec.
       Niektorzy wol+- jednak wykorzystywaae oddzielny program, ktory odbiera
       po3+-czenia, po czym uruchamia program stunnel.  Przyk3adami takich
       programow s+- inetd, xinetd i tcpserver.

       Przyk3adowa linia pliku /etc/inetd.conf moce wygl+-daae tak:

           imaps stream tcp nowait root /usr/sbin/stunnel
               stunnel /etc/stunnel/imaps.conf

       certyfikatowi klucz prywatny.  Najprostsz+- metod+- uzyskania certy-
       fikatu jest wygenerowanie go przy pomocy wolnego pakietu OpenSSL.
       Wiecej informacji na temat generowania certyfikatow mocna znale1/4ae na
       umieszczonych ponicej stronach.

       Przy generowaniu par certyfikat-klucz dla programu stunnel istotne s+-
       dwie kwestie.  Po pierwsze klucz prywatny nie moce byae zaszyfrowany,
       poniewac startuj+-cy serwer nie ma w ogolnym przypadku mocliwo9|ci
       uzyskania has3a od ucytkownika.  Do wytworzenia niezaszyfrowanego
       klucza nalecy przy uruchamianiu komendy openssl req podaae jej parametr
       -nodes.

       Drug+- istotn+- kwesti+- jest kolejno9|ae zawarto9|ci pliku .pem.  W
       pierwszej kolejno9|ci powinien on zawieraae klucz prywatny, a dopiero
       za nim podpisany certyfikat (nie c+-danie certyfikatu).  Po certyfika-
       cie i kluczu prywatnym powinny znajdowaae sie puste linie.  Jeceli
       przed certyfikatem znajduj+- sie dodatkowe informacje tekstowe, to
       powinny one zostaae usuniete.  Otrzymany plik powinien mieae
       nastepuj+-c+- postaae:

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

       LOSOWO|AE

       stunnel potrzebuje zainicjowaae PRNG (generator liczb pseudolosowych),
       gdyc protoko3 SSL wymaga do bezpieczenstwa kryptograficznego 1/4rod3a
       dobrej losowo9|ci.  Nastepuj+-ce 1/4rod3a s+- kolejno odczytywane ac do
       uzyskania  wystarczaj+-cej ilo9|ci entropii:

       o   Zawarto9|ae pliku podanego w opcji RNDfile.

       o   Zawarto9|ae pliku o nazwie okre9|lonej przez zmienn+-
           9|rodowiskow+- RANDFILE, o ile jest ona ustawiona.

       o   Plik .rnd umieszczony w katalogu domowym ucytkownika, jeceli zmi-
           enna RANDFILE nie jest ustawiona.

       o   Plik podany w opcji '--with-random' w czasie konfiguracji programu.

       o   Zawarto9|ae ekranu w systemie Windows.

       o   Gniazdo egd, jeceli ucyta zosta3a opcja EGD.

       o   Gniazdo egd podane w opcji '--with-egd-socket' w czasie konfigu-
           racji programu.

       Plik RNDfile powinien zawieraae dane losowe -- rowniec w tym sensie, ce
       powinny byae one inne przy kacdym uruchomieniu programu stunnel.  O ile
       nie ucyta zosta3a opcja RNDoverwrite jest to robione automatycznie.  Do
       recznego uzyskania takiego pliku ucyteczna moce byae komenda openssl
       rand dostarczana ze wspo3czesnymi wersjami pakietu OpenSSL.

       Jeszcze jedna istotna informacja -- jeceli dostepne 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 bedzie najprawdopodobniej ucyte, pomimo ce znajduje sie na samym
       koncu powycszej listy.  Jest to w3a9|ciwo9|ae biblioteki OpenSSL, a nie
       programu stunnel.
             _

ZOBACZ ROWNIE

       tcpd(8)
           biblioteka kontroli dostepu do us3ug internetowych

       inetd(8)
           'super-serwer' internetowy

       http://stunnel.mirt.net/
           strona domowa programu stunnel

       http://www.stunnel.org/
           najcze9|ciej zadawane pytania na temat programu stunnel

       http://www.openssl.org/
           strona projektu OpenSSL

AUTOR

       Micha3 Trojnara
           <Michal.Trojnara@mirt.net>



4.08                              2006.11.11                     STUNNEL.PL(8)