%
% stunnel.tex
% Last Update: $Id$
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%% Kapitel Stunnel %%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Achtung: Dateien muessen mit latin1-Encoding gespeichert werden!
% Attention: Files must be saved using latin1 encoding!
%

\chapter{Das Stunnel-Paket}

\section{Die Einleitung}

    Dieses Paket dient dazu SSL verschl"usselte Tunnel zwischen entfernten
    Clients und lokalen und/oder entfernten Servern zur Verf"ugung zu
    stellen. Nicht SSL-f"ahige Programme k"onnen somit mit SSL-Verschl"usselung
    und Authentifizierung versehen werden.


\section{Die Funktionen}

    Das Stunnel-Paket besteht aus folgenden Komponenten:

    \begin{itemize}
        \item Stunnel - Stellt das Programm zum Verschl"usseln von
            TCP-Verbindungen zur Verf"ugung.\\
            (\url{http://www.stunnel.org/})
    \end{itemize}


\section{Die Voraussetzungen}

    Dieses Paket ben"otigt zur korrekten Funktion ein installiertes Libssl-Paket.


\section{Die Installation}

    Das Stunnel-Paket wird "uber das Setup-Men"u installiert. Wird eine
    "altere Paketversion vorgefunden, so wird diese deinstalliert bevor
    die neuen Programmdateien installiert werden. Nach dem Installieren
    der Programmdateien wird direkt der Konfigurations-Editor gestartet
    um die Konfiguration anzupassen. Nach Beendigung dieses Schrittes
    werden die Konfigurationsdateien generiert und alle ben"otigten
    Programme gestartet.


\section{Das Men"u im Setup-Programm}

    Das Men"u im Setup-Programm ist wie folgt aufgebaut:

    \begin{itemize}
        \item Stunnel administration
        \begin{itemize}
            \item View documentation: Anzeigen der Dokumentation
            \item Edit configuration: Bearbeiten der Konfiguration
            \item Advanced configuration file handling: Konfigurationen verwalten
            \item View configuration log file: Konfigurationsmeldungen anzeigen
            \item Show Status: Status des Stunnel-Service anzeigen
            \item Stop Stunnel service: Stunnel-Service beenden
            \item Start Stunnel service: Stunnel-Service starten
            \item View log file: Logmeldungen anzeigen
        \end{itemize}
        \item Return: Untermen"u verlassen
    \end{itemize}

    Die Men"upunkte d"urften selbsterkl"arend sein, da sie keinerlei weitere
    Eingaben erwarten. Aus diesem Grund wird auf deren Funktion nicht weiter
    eingegangen.


\section{Die "Anderung der Konfiguration}

    Die Konfiguration kann "uber den Men"upunkt `Edit configuration'
    ge"andert werden. Standardm"a"sig wird der Editor aufgerufen, der in der
    Environment-Konfiguration "uber die Variable `EDITOR' festgelegt wurde.
    Nachdem der Editor beendet wurde wird abgefragt, ob die Konfiguration
    aktiviert werden soll. Wird dies best"atigt, werden "uber ein Skript die
    Anpassungen umgehend wirksam gemacht.


\section{Die Konfigurationsdatei}

   In der Konfigurationsdatei, die "uber das Men"u zug"anglich ist, sind
   folgende Parameter vorhanden; wer sie von Hand editieren will findet
   sie unter \texttt{/etc/config.d/stunnel}.


\section{Die Parameter}

\begin{description}
%% JED - show this description only in the help file
 %  \config{STUNNEL\_DO\_DEBUG (Optionaler Parameter)}{STUNNEL\_DO\_DEBUG}{STUNNELDODEBUG}
 %      Um den Debug-Modus zu aktivieren muss diese Parameter
 %      lediglich auf den Wert `yes' gestellt werden, die Einstellung
 %      `no' deaktiviert den Debug-Modus.
 %
 %      G"ultige Werte: yes, no
 %
 %      Standardeinstellung: \texttt{STUNNEL\_DO\_DEBUG='no'}

    \config{START\_STUNNEL}{START\_STUNNEL}{STARTSTUNNEL}
        F"ur die Aktivierung des stunnel-Paketes muss diese Variable
        lediglich auf den Wert `yes' gestellt werden. Die Einstellung
        `no' deaktiviert das Stunnel-Paket.

        G"ultige Werte: yes, no

        Standardeinstellung: \texttt{START\_STUNNEL='no'}

    \config{STUNNEL\_DEFAULT\_CERT\_FILE}{STUNNEL\_DEFAULT\_CERT\_FILE}{STUNNELDEFAULTCERTFILE}
        "Uber diesen Parameter kann eine Zertifikatsdatei im PEM-Format
        angegeben werden, welche standardm"a"sig das f"ur einen Verbindungsaufbau
        ben"otigte Zertifikat enth"alt. Im Servermodus ist die Angabe
        einer Zertifikatsdatei zwingend erforderlich.
        Die Datei muss sich im Verzeichnis \texttt{/usr/local/ssl/certs}
        befinden.

        G"ultige Werte: leer oder Name einer Zertifikatsdatei

        Standardeinstellung: \texttt{STUNNEL\_DEFAULT\_CERT\_FILE=''}

    \config{STUNNEL\_DEFAULT\_CERT\_KEY}{STUNNEL\_DEFAULT\_CERT\_KEY}{STUNNELDEFAULTCERTKEY}
        "Uber diesen Parameter kann eine private Schl"usseldatei im
        PEM-Format angegeben werden welche standardm"a"sig zur
        Authentifizierung eines Zertifikatsbesitzers verwendet
        werden soll. Die Datei muss sich im Verzeichnis \texttt{/usr/local/ssl/private}
        befinden.

        G"ultige Werte: leer oder Name einer Schl"usseldatei

        Standardeinstellung: \texttt{STUNNEL\_DEFAULT\_CERT\_KEY=$''$}

    \config{STUNNEL\_DEFAULT\_PROTOCOL}{STUNNEL\_DEFAULT\_PROTOCOL}{STUNNELDEFAULTPROTOCOL}
        "Uber diesen Parameter wird das Protokoll eingestellt,
        welches zum Verbindungsaufbau verwendet werden soll.

        G"ultige Werte: all (leer), ssl2, ssl3 oder tls1

        Standardeinstellung: \texttt{STUNNEL\_DEFAULT\_PROTOCOL='ssl3'}

     \config{STUNNEL\_FIPS\_ENABLED}{STUNNEL\_FIPS\_ENABLED}{STUNNELFIPSENABLED}
        "Uber diesen Parameter kann eingestellt werden, ob Stunnel von der
        FIPS (Federal Information Processing Standard) Zertifizierung 140-2
        von OpenSSL profitieren soll. Falls ja, muss als Transportprotokoll
        `TLSv1' verwendet werden.

        G"ultige Werte: yes oder no

        Standardeinstellung: \texttt{STUNNEL\_FIPS\_ENABLED='no'}

    Mittels der folgenden Parameter werden die individuellen
    Einstellungen einer Tunnelkonfiguration festgelegt.

    \config{STUNNEL\_N}{STUNNEL\_N}{STUNNELN}
        "Uber diesen Parameter wird die Anzahl der zu konfigurierenden
        Verbindungen festgelegt.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{STUNNEL\_N='1'}

    \config{STUNNEL\_x\_ACTIVE}{STUNNEL\_x\_ACTIVE}{STUNNELxACTIVE}
        Wird dieser Parameter auf den Wert `yes' gesetzt, so wird die
        zugeh"orige Tunnelkonfiguration aktiviert, `no' deaktiviert sie.

        G"ultige Werte: yes oder no

        Beispiel: \texttt{STUNNEL\_1\_ACTIVE='no'}

    \config{STUNNEL\_x\_NAME}{STUNNEL\_x\_NAME}{STUNNELxNAME}
        "Uber diesen Parameter kann man einen Namen f"ur eine
        Tunnelkonfiguration festlegen.

        G"ultige Werte: Name

        Beispiel: \texttt{STUNNEL\_1\_NAME='vpn-1'}

    \config{STUNNEL\_x\_CLIENT\_MODE}{STUNNEL\_x\_CLIENT\_MODE}{STUNNELxCLIENTMODE}
        "Uber diesen Parameter aktiviert man den Klientenmodus der
        Tunnelkonfiguration, der Parameter \jump{STUNNELxSERVERMODE}{STUNNEL\_x\_SERVER\_MODE}
        muss in diesem Fall auf den Wert `no' gesetzt werden.

        G"ultige Werte: yes oder no

        Standardeinstellung: \texttt{STUNNEL\_1\_CLIENT\_MODE='yes'}

    \config{STUNNEL\_x\_CLIENT\_DELAYED\_DNS}{STUNNEL\_x\_CLIENT\_DELAYED\_DNS}{STUNNELxCLIENTDELAYEDDNS}
        "Uber diesen Parameter legt man fest, ob DNS-Anfragen bei
        Verbindungsanfragen verz"ogert ausgef"uhrt werden sollen.
        Dies kann sinnvoll sein, wenn dynamisches DNS verwendet
        wird oder DNS, z.B. bei einer Einwahlverbindung, noch nicht
        zur Verf"ugung steht wenn der Tunnel gestartet wird.

        G"ultige Werte: yes oder no

        Standardeinstellung: \texttt{STUNNEL\_1\_CLIENT\_DELAYED\_DNS='no'}

    \config{STUNNEL\_x\_CLIENT\_LISTEN\_HOST}{STUNNEL\_x\_CLIENT\_LISTEN\_HOST}{STUNNELxCLIENTLISTENHOST}
        "Uber diesen Parameter legt man fest auf welcher IP-Adresse
        und welchem TCP-Port Verbindungsanfragen akzeptiert werden
        sollen. Wird nur ein Port aber kein Hostname angegeben, so
        werden Verbindungen "uber alle IP-Adressen des lokalen
        Rechners angenommen.

        G"ultige Werte: [Hostname:] und TCP-Port

        Standardeinstellung: \texttt{STUNNEL\_1\_CLIENT\_LISTEN\_HOST=$''$}

    \config{STUNNEL\_x\_CLIENT\_REMOTE\_HOST}{STUNNEL\_x\_CLIENT\_REMOTE\_HOST}{STUNNELxCLIENTREMOTEHOST}
        "Uber diesen Parameter legt man fest zu welchem Host bzw.
        welcher IP-Adresse und welchem TCP-Port eine Verbindung
        aufgebaut werden soll. Wird nur ein Port aber kein Hostname
        angegeben, so wird standardm"a"sig `localhost' angenommen.

        G"ultige Werte: [Hostname:] und TCP-Port

        Standardeinstellung: \texttt{STUNNEL\_1\_CLIENT\_REMOTE\_HOST=$''$}

    \config{STUNNEL\_x\_CLIENT\_OUTGOING\_IPADDR}{STUNNEL\_x\_CLIENT\_OUTGOING\_IPADDR}{STUNNELxCLIENTOUTGOINGIPADDR}
        "Uber diesen Parameter legt man fest welche
        Netzwerkschnittstelle f"ur ausgehende Verbindungen verwendet
        werden soll.

        G"ultige Werte: leer oder IP-Adresse

        Standardeinstellung: \texttt{STUNNEL\_1\_CLIENT\_OUTGOING\_IPADDR=$''$}

    \config{STUNNEL\_x\_CLIENT\_APP\_PROTOCOL}{STUNNEL\_x\_CLIENT\_APP\_PROTOCOL}{STUNNELxCLIENTAPPPROTOCOL}
        "Uber diesen Parameter kann festgelegt werden welches
        Applikationsprotokoll zur Aushandlung einer SSL/TLS-gesicherten
        Verbindung genutzt werden soll. Diese Option sollte nicht
        verwendet werden, wenn eine verschl"usselte Verbindung "uber
        einen separaten Port aufgebaut werden soll.

        Die unterst"utzten Protokolle sind:

        \begin{itemize}
            \item cifs:    Dies ist eine propriet"are, undokumentierte,
                           Erweiterung des CIFS-Protokolls in Samba.
            \item connect: Basierend auf RFC 2817 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte Verbindung,
                           aufbauend auf eine HTTP/1.1-Verbindung, zu
                           etablieren. Dieses Protokoll wird nur im
                           Klientenmodus unterst"utzt.
            \item imap:    Basierend auf RFC 2595 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte IMAP-Verbindung
                           aufzubauen.
            \item nntp:    Basierend auf RFC 4642 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte NNTP-Verbindung
                           aufzubauen. Dieses Protokoll wird nur im
                           Klientenmodus unterst"utzt.
            \item pgsql:   Siehe:\\
                           \url{http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982}
            \item pop3:    Basierend auf RFC 2449 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte POP3-Verbindung
                           aufzubauen.
            \item proxy:   Haproxy IP-Adresse des Klienten. Siehe:\\
                           \url{http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt}
            \item smtp:    Basierend auf RFC 2487 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte SMTP-Verbindung
                           aufzubauen.
            \item socks:   Es werden die SOCKS-Versionen 4, 4a und 5
                           unterst"utzt. Das SOCKS-Protokoll selbst wird
                           in einem SSL/TLS-Layer gekapselt, um die finale
                           Zieladresse zu verschleiern. Siehe:\\
                           \url{http://www.openssh.com/txt/socks4.protocol}\\
                           Es gilt zu beachten, dass der BIND-Befehl nicht
                           unterst"utzt und der USERID-Parameter ignoriert
                           wird.
        \end{itemize}

        Standardeinstellung: \texttt{STUNNEL\_1\_CLIENT\_APP\_PROTOCOL=$''$}

    \config{STUNNEL\_x\_SERVER\_MODE}{STUNNEL\_x\_SERVER\_MODE}{STUNNELxSERVERMODE}
        "Uber diesen Parameter aktiviert man den Server-Modus der
        Tunnelkonfiguration, der Parameter \jump{STUNNELxCLIENTMODE}{STUNNEL\_x\_CLIENT\_MODE}
        muss in diesem Fall auf den Wert `no' gesetzt werden.

        G"ultige Werte: yes oder no

        Standardeinstellung: \texttt{STUNNEL\_1\_SERVER\_MODE='no'}

    \config{STUNNEL\_x\_SERVER\_LISTEN\_HOST}{STUNNEL\_x\_SERVER\_LISTEN\_HOST}{STUNNELxSERVERLISTENHOST}
        "Uber diesen Parameter legt man fest auf welcher IP-Adresse
        und welchem TCP-Port Verbindungsanfragen akzeptiert werden
        sollen. Wird kein Hostname angegeben, so werden Verbindungen
        "uber alle IP-Adressen des lokalen Rechners angenommen.

        G"ultige Werte: leer oder [Hostname:] und TCP-Port

        Standardeinstellung: \texttt{STUNNEL\_1\_SERVER\_LISTEN\_HOST=$''$}

    \config{STUNNEL\_x\_SERVER\_COMMAND}{STUNNEL\_x\_SERVER\_COMMAND}{STUNNELxSERVERCOMMAND}
        "Uber diesen Parameter kann ein lokales Programm angegeben werden
        welches nach einem Verbindungsaufbau ausgef"uhrt werden soll.

        G"ultige Werte: Programm inkl. Pfad

        Beispiel: \texttt{STUNNEL\_1\_SERVER\_COMMAND='/usr/sbin/pppd'}

    \config{STUNNEL\_x\_SERVER\_COMMAND\_OPTION}{STUNNEL\_x\_SERVER\_COMMAND\_OPTION}{STUNNELxSERVERCOMMANDOPTION}
        "Uber diesen Parameter k"onnen optionale Programmparameter f"ur das "uber\\
        \jump{STUNNELxSERVERCOMMAND}{STUNNEL\_x\_SERVER\_COMMAND} konfigurierte
        Programm angegeben werden.

        G"ultige Werte: Optionale Parameter

        Beispiel: \texttt{STUNNEL\_1\_SERVER\_COMMAND\_OPTION='pppd local'}

    \config{STUNNEL\_x\_SERVER\_APP\_PROTOCOL}{STUNNEL\_x\_SERVER\_APP\_PROTOCOL}{STUNNELxSERVERAPPPROTOCOL}
        "Uber diesen Parameter kann festgelegt werden welches
        Applikationsprotokoll zur Aushandlung einer SSL/TLS-gesicherten
        Verbindung genutzt werden soll. Diese Option sollte nicht
        verwendet werden, wenn eine verschl"usselte Verbindung "uber
        einen separaten Port aufgebaut werden soll.

        Die unterst"utzten Protokolle sind:

        \begin{itemize}
            \item cifs:    Dies ist eine propriet"are, undokumentierte,
                           Erweiterung des CIFS-Protokolls in Samba.
            \item imap:    Basierend auf RFC 2595 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte IMAP-Verbindung
                           aufzubauen.
            \item pgsql:   Siehe:\\
                           \url{http://www.postgresql.org/docs/8.3/static/protocol-flow.html#AEN73982}
            \item pop3:    Basierend auf RFC 2449 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte POP3-Verbindung
                           aufzubauen.
            \item proxy:   Haproxy IP-Adresse des Klienten. Siehe:\\
                           \url{http://haproxy.1wt.eu/download/1.5/doc/proxy-protocol.txt}
            \item smtp:    Basierend auf RFC 2487 wird dieses Protokoll
                           verwendet um eine TLS-gesicherte SMTP-Verbindung
                           aufzubauen.
            \item socks:   Es werden die SOCKS-Versionen 4, 4a und 5
                           unterst"utzt. Das SOCKS-Protokoll selbst wird
                           in einem SSL/TLS-Layer gekapselt, um die finale
                           Zieladresse zu verschleiern. Siehe:\\
                           \url{http://www.openssh.com/txt/socks4.protocol}\\
                           Es gilt zu beachten, dass der BIND-Befehl nicht
                           unterst"utzt und der USERID-Parameter ignoriert
                           wird.
        \end{itemize}

        Standardeinstellung: \texttt{STUNNEL\_1\_SERVER\_APP\_PROTOCOL=$''$}

    \config{STUNNEL\_x\_CERT\_CHECK}{STUNNEL\_x\_CERT\_CHECK}{STUNNELxCERTCHECK}
        "Uber diesen Parameter legt man fest, ob und wie das Zertifikat
        der Gegenstelle "uberpr"uft werden soll.

        \begin{itemize}
            \item 0 - Zertifikat nicht pr"ufen.
            \item 1 - Zertifikat der Gegenstelle pr"ufen, wenn es existiert.
            \item 2 - Zertifikat der Gegenstelle pr"ufen.
            \item 3 - Zertifikat der Gegenstelle pr"ufen und mit den lokal
                      installierten Zertifikaten vergleichen.
            \item 4 - Zertifikat der Gegenstelle pr"ufen und dabei die CA-Zertifikatskette
                      ignorieren.
        \end{itemize}

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{STUNNEL\_1\_CERT\_CHECK='0'}

    \config{STUNNEL\_x\_CERT\_FILE}{STUNNEL\_x\_CERT\_FILE}{STUNNELxCERTFILE}
        "Uber diesen Parameter kann eine Zertifikatsdatei im PEM-Format
        angegeben werden, welche das f"ur einen Verbindungsaufbau ben"otigte
        Zertifikat enth"alt. Im Servermodus ist die Angabe einer Zertifikatsdatei
        zwingend erforderlich.
        Die Datei muss sich im Verzeichnis \texttt{/usr/local/ssl/certs}
        befinden.

        G"ultige Werte: leer oder Zertifikatsdatei

        Standardeinstellung: \texttt{STUNNEL\_1\_CERT\_FILE=$''$}

    \config{STUNNEL\_x\_CERT\_KEY}{STUNNEL\_x\_CERT\_KEY}{STUNNELxCERTKEY}
        "Uber diesen Parameter kann eine private Schl"usseldatei im
        PEM-Format angegeben werden welche standardm"a"sig zur Authentifizierung
        eines Zertifikatsbesitzers verwendet werden soll.
        Die Datei muss sich im Verzeichnis \texttt{/usr/local/ssl/private}
        befinden.

        G"ultige Werte: leer oder Schl"usseldatei

        Standardeinstellung: \texttt{STUNNEL\_1\_CERT\_KEY=$''$}

    \config{STUNNEL\_x\_PROTOCOL}{STUNNEL\_x\_PROTOCOL}{STUNNELxPROTOCOL}
        "Uber diesen Parameter wird das Sicherheitsprotokoll eingestellt,
        welches zum Verbindungsaufbau verwendet werden soll.

        G"ultige Werte: all (leer), ssl2, ssl3 oder tls1

        Standardeinstellung: \texttt{STUNNEL\_1\_PROTOCOL='ssl3'}

    \config{STUNNEL\_LOG\_COUNT}{STUNNEL\_LOG\_COUNT}{STUNNELLOGCOUNT}
        "Uber diesen Parameter wird eingestellt, wie viele Logdateien
        vorgehalten werden sollen. Wird dieser Wert "uberschritten, so
        wird immer die "alteste Logdatei gel"oscht.

        G"ultige Werte: Zahl

        Standardeinstellung: \texttt{STUNNEL\_LOG\_COUNT='6'}

    \config{STUNNEL\_LOG\_INTERVAL}{STUNNEL\_LOG\_INTERVAL}{STUNNELLOGINTERVAL}
        Dieser Parameter bestimmt in welchen Intervallen die Logdateien
        archiviert werden sollen. Zur Auswahl stehen die Schl"usselw"orter
        `daily' - t"aglich, `weekly' - w"ochentlich und `monthly - monatlich.

        G"ultige Werte: daily, weekly, monthly

        Standardeinstellung: \texttt{STUNNEL\_LOG\_INTERVAL='weekly'}
\end{description}

