DragonFly On-Line Manual Pages

stunnel(8) stunnel TLS Proxy stunnel(8)

NAZWA
stunnel - uniwersalny tunel protokolu SSL

OPIS
Program stunnel zostal zaprojektowany do opakowywania w protokol SSL
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 SSL
poprzez bezpieczne kanaly SSL.

stunnel pozwala dodac funkcjonalnosc SSL 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
PLIK
uzyj podanego pliku konfiguracyjnego

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

-help
drukuj liste wspieranych opcji

-version
drukuj wersje programu i domyslne wartosci parametrow

-sockets
drukuj domyslne opcje gniazd

-options
drukuj wspierane opcje SSL

-install (tylko Windows NT lub nowszy)
instaluj serwis NT

-uninstall (tylko Windows NT lub nowszy)
odinstaluj serwis NT

-start (tylko Windows NT lub nowszy)
uruchom serwis NT

-stop (tylko Windows NT lub nowszy)
zatrzymaj serwis NT

-reload (tylko Windows NT lub nowszy)
przeladuj plik konfiguracyjny uruchomionego serwisu NT

-reopen (tylko Windows NT lub nowszy)
otworz ponownie log uruchomionego serwisu NT

-exit (tylko Win32)
zatrzymaj uruchomiony program

-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
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

compression = deflate | zlib
wybor algorytmu kompresji przesylanych danych

domyslnie: bez kompresji

Algorytm deflate jest standardowa metoda kompresji zgodnie z RFC
1951.

Kompresja zlib zaimplementowana w OpenSSL 0.9.8 i nowszych nie jest
kompatybilna implementacja OpenSSL 0.9.7.

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. Do uzyskania
najwyzszego poziomu szczegolowosci mozna uzyc opcji debug = debug
lub debug = 7. Domyslnym poziomem jest notice (5).

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.

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. Opcja jest dostepna z
biblioteka OpenSSL 0.9.5a lub nowsza.

engine = auto | IDENTYFIKATOR_URZADZENIA
wybor sprzetowego urzadzenia kryptograficznego

domyslnie: bez wykorzystania urzadzen kryptograficznych

Przykladowa konfiguracja umozliwiajaca uzycie certyfikatu i klucza
prywatnego z urzadzenia zgodnego z OpenSC:

engine = dynamic
engineCtrl = SO_PATH:/usr/local/lib/engines/libpkcs11.so
engineCtrl = LOAD
engineCtrl = MODULE_PATH:opensc-pkcs11.so
engineCtrl = PIN:123456

[service]
engineId = pkcs11
cert = id_45

engineCtrl = KOMENDA[:PARAMETR]
konfiguracja urzadzenia kryptograficznego

Specjalna komenda "LOAD" pozwala na zaladowanie modulu urzadzenia
kryptograficznego.

engineDefault = LISTA_ZADAN
lista zadan OpenSSL oddelegowanych do biezacego urzadzenia

Parametrem jest lista oddzielonych przecinkami zadan OpenSSL, ktore
maja zostac oddelegowane do biezacego urzadzenia kryptograficznego.

W zaleznosci od konkretnego urzadzenia dostepne moga byc
nastepujace zadania: ALL, RSA, DSA, ECDH, ECDSA, DH, RAND, CIPHERS,
DIGESTS, PKEY, PKEY_CRYPTO, PKEY_ASN1.

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)

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.

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.

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.

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.

log = append | overwrite
log file handling

This option allows to choose whether the log file (specified with
the output option) is appended or overwritten when opened or re-
opened.

domyslnie: append

output = PLIK
plik, do ktorego dopisane zostana logi

Uzycie tej opcji powoduje dopisanie logow do podanego pliku.

Do kierowaniakomunikatow na standardowe wyjscie (na przyklad po to,
zeby zalogowac je programem splogger z pakietu daemontools) mozna
podac jako parametr urzadzenie /dev/stdout.

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.

RNDbytes = LICZBA_BAJTOW
liczba bajtow do zainicjowania generatora pseudolosowego

W wersjach biblioteki OpenSSL starszych niz 0.9.5a opcja ta okresla
rowniez liczbe bajtow wystarczajacych do zainicjowania PRNG. Nowsze
wersje biblioteki maja wbudowana funkcje okreslajaca, czy
dostarczona ilosc losowosci jest wystarczajaca do zainicjowania
generatora.

RNDfile = PLIK
sciezka do pliku zawierajacego losowe dane

Biblioteka OpenSSL uzyje danych z tego pliku do zainicjowania
generatora pseudolosowego.

RNDoverwrite = yes | no
nadpisz plik nowymi wartosciami pseudolosowymi

domyslnie: yes (nadpisz)

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

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)

syslog = yes | no (tylko Unix)
wlacz logowanie poprzez mechanizm syslog

domyslnie: yes (wlacz)

taskbar = yes | no (tylko WIN32)
wlacz ikonke w prawym dolnym rogu ekranu

domyslnie: yes (wlacz)

OPCJE US/UG
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.

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

CApath = KATALOG_CA
katalog Centrum Certyfikacji

Opcja okresla katalog, w ktorym stunnel bedzie szukal certyfikatow,
jezeli uzyta zostala opcja verify. Pliki z certyfikatami musza
posiadac specjalne nazwy XXXXXXXX.0, gdzie XXXXXXXX jest skrotem
kryptograficznym reprezentacji DER nazwy podmiotu certyfikatu.

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.

CAfile = PLIK_CA
plik Centrum Certyfikacji

Opcja pozwala okreslic polozenie pliku zawierajacego certyfikaty
uzywane przez opcje verify.

cert = PLIK_PEM
plik z lancuchem certyfikatow

Opcja okresla polozenie pliku zawierajacego certyfikaty uzywane
przez program stunnel do uwierzytelnienia sie przed druga strona
polaczenia. Certyfikat jest konieczny, aby uzywac programu w
trybie serwera. W trybie klienta certyfikat jest opcjonalny.

Jezeli uzywane jest sprzetowe urzadzenie kryptograficzne, to opcja
cert pozwala wybrac identyfikator uzywanego certyfikatu.

checkEmail = EMAIL
adres email przedstawionego certyfikatu

Pojedyncza sekcja moze zawierac wiele wystapien opcji checkEmail.
Certyfikaty sa akceptowane, jezeli sekcja nie zawiera opcji
checkEmail, 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.

checkHost = NAZWA_SERWERA
nazwa serwera przedstawionego certyfikatu

Pojedyncza sekcja moze zawierac wiele wystapien opcji checkHost.
Certyfikaty sa akceptowane, jezeli sekcja nie zawiera opcji
checkHost, 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.

checkIP = IP
adres IP przedstawionego certyfikatu

Pojedyncza sekcja moze zawierac wiele wystapien opcji checkIP.
Certyfikaty sa akceptowane, jezeli sekcja nie zawiera opcji
checkIP, 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.

ciphers = LISTA_SZYFROW
lista dozwolonych szyfrow SSL

Parametrem tej opcji jest lista szyfrow, ktore beda uzyte przy
otwieraniu nowych polaczen SSL, np.: DES-CBC3-SHA:IDEA-CBC-MD5

client = yes | no
tryb kliencki (zdalna usluga uzywa SSL)

domyslnie: no (tryb serwerowy)

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 manualu SSL_CONF_cmd(3ssl).

Mozliwe jest wyspecyfikowanie wielu opcji OpenSSL przez wielokrotne
uzycie komendy config.

Opcja ta wymaga biblioteki OpenSSL w wersji 1.0.2 lub nowszej.

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.

CRLpath = KATALOG_CRL
katalog List Odwolanych Certyfikatow (CRL)

Opcja okresla katalog, w ktorym stunnel bedzie szukal list CRL,
jezeli uzyta zostala opcja verify. 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.

CRLfile = PLIK_CRL
plik List Odwolanych Certyfikatow (CRL)

Opcja pozwala okreslic polozenie pliku zawierajacego listy CRL
uzywane przez opcje verify.

curve = NID
krzywa dla ECDH

Liste dostepnych krzywych mozna uzyskac poleceniem:

openssl ecparam -list_curves

domyslnie: prime256v1

logId = TYP
typ identyfikatora polaczenia klienta

Identyfikator ten pozwala rozroznic wpisy w logu wygenerowane dla
poszczegolnych polaczen.

Aktualnie wspierane typy:

sequential
Kolejny numer polaczenia jest unikalny jedynie w obrebie
pojedynczej instancji programu stunnel, ale bardzo krotki.
Jest on szczegolnie uzytczny przy recznej analizie logow.

unique
Ten rodzaj identyfikatora jest globalnie unikalny, ale znacznie
dluzszy, niz kolejny numer polaczenia. Jest on szczegolnie
uzyteczny przy zautomatyzowanej analizie logow.

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.

domyslnie: sequential

debug = POZIOM
szczegolowosc logowania

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.

default: no

engineId = NUMER_URZADZENIA
wybierz urzadzenie dla uslugi

engineNum = NUMER_URZADZENIA
wybierz urzadzenie dla uslugi

Urzadzenia sa numerowane od 1 w gore.

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.

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.

failover = rr | prio
Strategia wybierania serwerow wyspecyfikowanych parametrami
"connect".

rr (round robin) - sprawiedliwe rozlozenie obciazenia
prio (priority) - uzyj kolejnosci opcji w pliku konfiguracyjnym

domyslnie: rr

ident = NAZWA_UZYTKOWNIKA
weryfikuj nazwe zdalnego uzytkownika korzystajac z protokolu IDENT
(RFC 1413)

include = KATALOG
wczytaj fragmenty plikow konfiguracyjnych z podanego katalogu

Pliki sa wczytywane w rosnacej kolejnosci alfabetycznej ich nazw.

key = PLIK_KLUCZA
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 uzywane jest sprzetowe urzadzenie kryptograficzne, to opcja
key pozwala wybrac identyfikator uzywanego klucza prywatnego.

domyslnie: wartosc opcji cert

libwrap = yes | no
wlacz lub wylacz korzystanie z /etc/hosts.allow i /etc/hosts.deny.

domyslnie: no (od wersji 5.00)

local = HOST
IP zrodla do nawiazywania zdalnych polaczen

Domyslnie uzywane jest IP najbardziej zewnetrznego interfejsu w
strone serwera, do ktorego nawiazywane jest polaczenie.

sni = USLUGA:WZORZEC_NAZWY_SERWERA (tryb serwera)
Uzyj uslugi jako podrzednej (virtualnego serwera) dla rozszerzenia
TLS Server Name Indication (RFC 3546).

nazwa_us/lugi 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.

sni = HOST (tryb klienta)
Uzyj parametru jako wartosci rozszerzenia TLS Server Name
Indication (RFC 3546).

Opcja sni jest dostepna poczawszy od OpenSSL 1.0.0.

OCSP = URL
responder OCSP do weryfikacji certyfikatow

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).

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.

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.

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
SSL w programie Eudora, mozna uzyc opcji:

options = DONT_INSERT_EMPTY_FRAGMENTS

domyslnie:

options = NO_SSLv2
options = NO_SSLv3

protocol = PROTOKOL
negocjuj SSL podanym protokolem aplikacyjnym

Opcja ta wlacza wstepna negocjacje szyfrowania SSL dla wybranego
protokolu aplikacyjnego. Opcji protocol nie nalezy uzywac z
szyfrowaniem SSL na osobnym porcie.

Aktualnie wspierane protokoly:

cifs
Unieudokumentowane rozszerzenie protokolu CIFS wspierane przez
serwer Samba. Wsparcie dla tego rozrzeczenia zostalo zarzucone
w wersji 3.0.0 serwera Samba.

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.

imap
Negocjacja RFC 2595 - Using TLS with IMAP, POP3 and ACAP

nntp
Negocjacja RFC 4642 - Using Transport Layer Security (TLS) with
Network News Transfer Protocol (NNTP)

Ten protokol jest wspierany wylacznie w trybie klienckim.

pgsql
Negocjacja
http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982

pop3
Negocjacja RFC 2449 - POP3 Extension Mechanism

proxy
Przekazywanie adresu IP haproxy
http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt

smtp
Negocjacja RFC 2487 - SMTP Service Extension for Secure SMTP
over TLS

socks
Wspierany jest protokol SOCKS w wersjach 4, 4a i 5. Protokol
SOCKS enkapsulowany jest w protokole SSL/TLS, wiec adres
serwera docelowego nie jest widoczny dla napastnika
przechwytujacego ruch sieciowy.

http://www.openssh.com/txt/socks4.protocol

http://www.openssh.com/txt/socks4a.protocol

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.

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'.

protocolDomain = DOMENA
domena do negocjacji protokolu

W obecnej wersji wybrana domena ma zastosowanie wylacznie w
protokole 'connect'.

protocolHost = HOST:PORT
adres docelowy do negocjacji protokolu

protocolHost okresla docelowy serwer SSL, do ktorego polaczyc ma
sie proxy. Nie jest to adres serwera proxy, do ktorego polaczenie
zestawia stunnel. Adres serwera proxy powinien byc okreslony przy
pomocy opcji 'connect'.

W obecnej wersji adres docelowy protokolu ma zastosowanie wylacznie
w protokole 'connect'.

protocolPassword = HASLO
haslo do negocjacji protokolu

Opcja ta jest wspierana wylacznie w klienckich protokolach
'connect' i 'smtp'.

protocolUsername = UZYTKOWNIK
nazwa uzytkownika do negocjacji protokolu

Opcja ta jest wspierana wylacznie w klienckich protokolach
'connect' i 'smtp'.

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

PSKsecrets = PLIK
plik z tozsamosciami i kluczami PSK

Kazda linia pliku jest w nastepujacym formacie:

TOZSAMOSC:KLUCZ

Klucz musi byc miec przynajmniej 20 znakow. Nalezy ograniczyc
dostep do czytania lub pisania do tego pliku.

pty = yes | no (tylko Unix)
alokuj pseudoterminal dla programu uruchamianego w opcji 'exec'

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.

renegotiation = yes | no
pozwalaj na renegocjacje SSL

Wsrod zastosowan renegocjacji SSL sa niektore scenariusze
uwierzytelnienia, oraz renegocjacja kluczy dla dlugotrwalych
polaczen.

Z drugiej strony wlasnosc na moze ulatwic trywialny atak DoS
poprzez wygenerowanie obciazenia procesora:

http://vincent.bernat.im/en/blog/2011-ssl-dos-mitigation.html

Warto zauwazyc, ze zablokowanie renegocjacji SSL nie zebezpiecza w
pelni przed opisanym problemem.

domyslnie: yes (o ile wspierane przez OpenSSL)

reset = yes | no
sygnalizuj wystapienie bledu przy pomocy flagi TCP RST

Opcja nie jest wspierana na niektorych platformach.

domyslnie: yes

retry = yes | no
polacz ponownie sekcje connect+exec po rozlaczeniu

domyslnie: no

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".

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".

sessionCacheSize = LICZBA_POZYCJI_CACHE
rozmiar pamieci podrecznej sesji SSL

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.

sessionCacheTimeout = LICZBA_SEKUND
przeterminowanie pamieci podrecznej sesji SSL

Parametr okresla czas w sekundach, po ktorym sesja SSL zostanie
usunieta z pamieci podrecznej.

sessiond = HOST:PORT
adres sessiond - servera cache sesji SSL

sslVersion = WERSJA_SSL
wersja protokolu SSL

Wspierane opcje: all, SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2

Dostepnosc konkretnych protokolow zalezy od uzytej wersji OpenSSL.
Starsze wersje OpenSSL nie wspieraja TLSv1.1 i TLSv1.2. Nowsze
wersje OpenSSL nie wspieraja SSLv2.

Przestarzale protokoly SSLv2 i SSLv3 sa domyslnie wylaczone.
Szczegolowe informacje dostepne sa w opisie opcji options.

stack = LICZBA_BAJTOW (z wyjatkiem modelu FORK)
rozmiar stosu procesora watku

TIMEOUTbusy = LICZBA_SEKUND
czas oczekiwania na spodziewane dane

TIMEOUTclose = LICZBA_SEKUND
czas oczekiwania na close_notify (ustaw na 0, jezeli klientem jest
MSIE)

TIMEOUTconnect = LICZBA_SEKUND
czas oczekiwania na nawiazanie polaczenia

TIMEOUTidle = LICZBA_SEKUND
maksymalny czas utrzymywania bezczynnego polaczenia

transparent = none | source | destination | both (tylko Unix)
tryb przezroczystego proxy na wspieranych platformach

Wspierane opcje:

none
Zablokuj wsparcie dla przezroczystago proxy. Jest to wartosc
domyslna.

source
Przepisz adres, aby nawiazywane polaczenie wydawalo sie
pochodzic bezposrednio od klienta, a nie od programu stunnel.

Opcja jest aktualnie obslugiwana w:

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.

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.

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.

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.

destination
Oryginalny adres docelowy jest uzywany zamiast opcji connect.

Przykladowana konfiguracja przezroczystego adresu docelowego:

[transparent]
client = yes
accept = <port_stunnela>
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 <port_przekierowany> \
-m ! --uid-owner <identyfikator_uzytkownika_stunnela> \
-j DNAT --to-destination <lokalne_ip>:<lokalny_port>

W przypadku docelowej uslugi umieszczonej na zdalnej maszynie:

/sbin/iptables -I INPUT -i eth0 -p tcp --dport <port_stunnela> -j ACCEPT
/sbin/iptables -t nat -I PREROUTING -p tcp --dport <port_przekierowany> \
-i eth0 -j DNAT --to-destination <lokalne_ip>:<port_stunnela>

Przezroczysty adres docelowy jest aktualnie wspierany wylacznie
w systemie Linux.

both
Uzyj przezroczystego proxy zarowno dla adresu zrodlowego jak i
docelowego.

Dla zapewnienia kompatybilnosci z wczesniejszymim wersjami
wspierane sa dwie dodatkowe opcje:

yes Opcja zostala przemianowana na source.

no Opcja zostala przemianowana na none.

verify = POZIOM
weryfikuj certyfikat drugiej strony polaczenia

poziom 0
zarzadaj certyfikatu i zignoruj go

poziom 1
weryfikuj, jezeli zostal przedstawiony

poziom 2
weryfikuj z zainstalowanym certyfikatem Centrum Certyfikacji

poziom 3
weryfikuj z lokalnie zainstalowanym certyfikatem drugiej strony

poziom 4
weryfikuj z certyfikatem drugiej strony ignorujac lancuch CA

domy'slnie
nie weryfikuj

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:

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'.

SIGUSR1
Zamknij i otworz ponownie log. Funkcja ta moze zostac uzyta w
skrypcie rotujacym log programu stunnel.

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 SSL 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_us/lugi].

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
verify = 4
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/

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 SSL.

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 /usr/local/bin/stunnel
stunnel /usr/local/etc/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_us/lugi]), poniewaz konfiguracja taka
pozwala na nawiazanie tylko jednego polaczenia. Wszystkie OPCJE US/LUG
powinny byc umieszczone razem z opcjami globalnymi. Przyklad takiej
konfiguracji znajduje sie w sekcji PRZYK/LADY.

CERTYFIKATY
Protokol SSL 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.

Istotna kwestia jest kolejnosc zawartosci pliku .pem. W pierwszej
kolejnosci powinien on zawierac klucz prywatny, a dopiero za nim
podpisany certyfikat (nie zadanie certyfikatu). Po certyfikacie i
kluczu prywatnym powinny znajdowac sie puste linie. Jezeli przed
certyfikatem znajduja sie dodatkowe informacje tekstowe, to powinny one
zostac usuniete. Otrzymany plik powinien miec nastepujaca postac:

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

LOSOWO''
stunnel potrzebuje zainicjowac PRNG (generator liczb pseudolosowych),
gdyz protokol SSL 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.

Wspolczesne (0.9.5a lub nowsze) wersje biblioteki OpenSSL automatycznie
zaprzestaja ladowania kolejnych danych w momencie uzyskania
wystarczajacej ilosci entropii. Wczesniejsze wersje biblioteki
wykorzystaja wszystkie powyzsze zrodla, gdyz nie istnieje tam funkcja
pozwalajaca okreslic, czy uzyskano juz wystarczajaco duzo danych.

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 autogenerowane 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
@sysconfdir@/stunnel/stunnel.conf
plik konfiguracyjny programu

BLEDY
Opcja execArgs oraz linia komend Win32 nie obsluguje cytowania.

ZOBACZ ROWNIEZ
tcpd(8)
biblioteka kontroli dostepu do uslug internetowych

inetd(8)
'super-serwer' internetowy

http://www.stunnel.org/
strona domowa programu stunnel

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

AUTOR
Michal Trojnara
<Michal.Trojnara@mirt.net>

5.28 2015.12.05 stunnel(8)

DragonFly On-Line Manual Pages

NAZWA

SKLADNIA

OPIS

OPCJE

PLIK KONFIGURACYJNY

ZWRACANA WARTOSC

SIGNALY

PRZYKLADY

NOTKI

PLIKI

BLEDY

ZOBACZ ROWNIEZ

AUTOR