STUNNEL.FR(8)

NOM
stunnel - tunnel SSL universel

SYNOPSIS

Unix:
    stunnel [fichier] | -fdÂ [n] | -help | -version | -sockets

WIN32:
    stunnel [fichier] | -install | -uninstall | -help | -version | -sockets

DESCRIPTION
Le programme stunnel est conÃ§u pour fonctionner comme une couche de chiffrement SSL entre des clients distants et des serveurs locaux (inetd-dÃ©marrables) ou distants. Le concept est qu'Ã  partir de daemons non-SSL prÃ©sents sur le systÃ¨me, on peut facilement les configurer pour communiquer avec des clients sur des liens sÃ©curisÃ©s SSL.

stunnel peut Ãªtre utilisÃ© pour ajouter des fonctionnalitÃ©s SSL Ã  des daemons classiques Inetd tels que les serveurs POP-2, POP-3 et IMAP, Ã  d'autres autonomes tels que NNTP, SMTP et HTTP, ainsi que pour tunneliser PPP sur des sockets rÃ©seau sans modification du code source.

Ce produit inclut du code de chiffrement Ã©crit par Eric Young (eay@cryptsoft.com)

OPTIONS

[fichier]
    Utilisation du fichier de configuration spÃ©cifiÃ©.

-fd [n] (Unix seulement)
    Lecture du fichier de configuration depuis le descripteur de fichier indiquÃ©.

-help
    Affiche le menu d'aide de stunnel.

-version
    Affiche la version de stunnel et les options de compilation.

-sockets
    Affiche les options socket par dÃ©faut.

-install (NT/2000/XP seulement)
    Installe un service NT.

-uninstall (NT/2000/XP only)
    DÃ©sinstalle un service NT.

FICHIER DE CONFIGURATION
Chaque ligne du fichier de configuration peut Ãªtre soitÂ :

•   une ligne vide (ignorÃ©e)Â ;

•   un commentaire commenÃ§ant par Â«Â #Â Â» (ignorÃ©)Â ;

•   une paire Â«Â option = valeurÂ Â»Â ;

•   Â«Â [service_name]Â Â» indiquant le dÃ©but de la dÃ©finition d'un serviceÂ ;

  OPTIONS GLOBALES

CApath = rÃ©pertoire
    RÃ©pertoire des autoritÃ©s de certification (CA)

    C'est le rÃ©pertoire dans lequel stunnel cherche les certificats si l'on utilise verify. Les certificats doivent Ãªtre dÃ©nommÃ©s selon la forme XXXXXXXX.0, oÃ¹ XXXXXXXX est la valeur de hachage du certificat.

    Le cas Ã©chÃ©ant, le rÃ©pertoire CApath est relatif au rÃ©pertoire chroot.

CAfile = fichier
    Fichier d'autoritÃ©s de certification

    Ce fichier, utilisÃ© avec verify, contient plusieurs certificats de CA.

cert = fichier
    Fichier de chaÃ®ne de certificats PEM

    Une PEM est toujours nÃ©cessaire en mode serveur. En mode client, cette option utilise cette PEM comme une chaÃ®ne cÃ´tÃ© client. L'utilisation de certificats cÃ´tÃ© client est optionnelle. Les certificats doivent Ãªtre au format PEM et triÃ©s par ordre de niveau dÃ©croissant (CA racine en premier).

chroot = rÃ©pertoire (Unix seulement)
    RÃ©pertoire de chroot du processus stunnel

    chroot enferme stunnel dans une cellule chroot. CApath, CRLpath, pid et exec sont situÃ©s Ã  l'intÃ©rieur de la cellule et les rÃ©pertoires doivent Ãªtre relatifs au rÃ©pertoire correspondant.

    Pour que le contrÃ´le de libwrap (wrappeur TCP) soit effectif dans un environnement chroot, il faut aussi y recopier leurs fichiers de configuration (/etc/hosts.allow et /etc/hosts.deny).

ciphers = listes de chiffre
    SÃ©lection des chiffres SSL autorisÃ©s

    Liste dÃ©limitÃ©e par deux-points (Â«Â :Â Â») des chiffres autorisÃ©s pour la connexion SSL. ExempleÂ : DES-CBC3-SHA:IDEA-CBC-MD5

client = yes | no
    Mode client (Le service distant utilise SSL)

    Par dÃ©fautÂ : no (mode server)

CRLpath = rÃ©pertoire
    RÃ©pertoire des listes de rÃ©vocation de certificats (CRL)

    C'est le rÃ©pertoire dans lequel stunnel recherche les CRL avec l'option verify. Les CRL doivent Ãªtre dÃ©nommÃ©s selon la forme XXXXXXXX.0 oÃ¹ XXXXXXXX est la valeur de hachage de la CRL.

    Le cas Ã©chÃ©ant, le rÃ©pertoire CRLpath est relatif au rÃ©pertoire chroot.

CRLfile = fichier
    Fichier de listes de rÃ©vocation de certificats (CRL)

    Ce fichier, utilisÃ© avec verify, contient plusieurs CRL.

debug = [facilitÃ©.]niveau
    niveau de dÃ©verminage

    Le niveau est un nom ou un numÃ©ro conforme Ã  ceux de syslogÂ : emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6) ou debug (7). Toutes les traces du niveau indiquÃ© et des niveaux numÃ©riquement infÃ©rieurs seront affichÃ©es. debug = debug ou debug = 7 donneront le maximum d'informations. La valeur par dÃ©faut est notice (5).

    La facilitÃ© syslog Â«Â daemonÂ Â» est utilisÃ©e, sauf si un autre nom est spÃ©cifiÃ© (Win32 ne permet pas l'usage des facilitÃ©s.)

    La casse est ignorÃ©e, aussi bien pour la facilitÃ© que pour le niveau.

EGD = chemin (Unix seulement)
    Emplacement du socket du daemon de recueil d'entropie (EGD - Entropy Gathering Daemon)

    Socket EGD Ã  utiliser pour alimenter le gÃ©nÃ©rateur d'alÃ©atoires de OpenSSL (disponible seulement si la compilation a Ã©tÃ© effectuÃ©e avec OpenSSL 0.9.5a ou supÃ©rieur).

foreground = yes | no (Unix seulement)
    Mode avant-plan

    Reste en avant-plan (sans fork) et dirige la trace sur stderr au lieu de syslog (sauf si output est spÃ©cifiÃ©).

    Par dÃ©faultÂ : arriÃ¨re-plan en mode daemon.

key = fichier
    Fichier de clef privÃ©e pour le certificat spÃ©cifiÃ© par cert

    La clef privÃ©e est nÃ©cessaire pour authentifier le titulaire du certificat. Puisque ce fichier doit rester secret, il ne doit Ãªtre lisible que par son propriÃ©taire. Sur les systÃ¨mes Unix, on peut utiliser la commande suivanteÂ :

        chmod 600 fichier

    Par dÃ©faultÂ : Valeur de cert

options = Options_SSL
    Options de la bibliothÃ¨que OpenSSL

    Le paramÃ¨tre est l'option OpenSSL dÃ©crite dans la page de man SSL_CTX_set_options(3ssl), dÃ©barassÃ©e du prÃ©fixe SSL_OP_. Plusieurs options peuvent Ãªtre spÃ©cifiÃ©es.

    Par exemple, pour la compatibilitÃ© avec l'implantation SSL dÃ©faillante d'Eudora, on peut utiliserÂ :

        options = DONT_INSERT_EMPTY_FRAGMENTS

output = fichier
    Ajoute la trace Ã  la fin d'un fichier au lieu d'utiliser syslog.

    /dev/stdout peut Ãªtre utilisÃ© pour afficher les traces sur la sortie standard (par exemple pour les traiter avec les outils splogger).

pid = fichier (Unix seulement)
    Emplacement du fichier pid

    Si l'argument est vide, aucun fichier ne sera crÃ©Ã©.

    Le cas Ã©chÃ©ant, le chemin pid est relatif au rÃ©pertoire chroot.

RNDbytes = nombre
    Nombre d'octets Ã  lire depuis les fichiers de Â«Â selÂ Â» alÃ©atoire

    Avec les SSL de version infÃ©rieure Ã  0.9.5a, dÃ©termine aussi le nombre d'octets considÃ©rÃ©s comme suffisants pour Â«Â salerÂ Â» le PRNG. Les versions plus rÃ©centes d'OpenSSL ont une fonction intÃ©grÃ©e qui dÃ©termine lorsque l'alÃ©atoire est suffisant.

RNDfile = fichier
    chemin du fichier de donnÃ©es de Â«Â selÂ Â» alÃ©atoire

    La bibliothÃ¨que SSL utilise prioritairement les donnÃ©es de ce fichier pour Â«Â salerÂ Â» le gÃ©nÃ©rateur d'alÃ©atoire.

RNDoverwrite = yes | no
    Recouvre les fichiers de Â«Â selÂ Â» avec de nouvelles donnÃ©es alÃ©atoires.

    Par dÃ©fautÂ : yes

service = nom
    DÃ©finit le nom de service Ã  utiliser

    Sous UnixÂ : nom de service du mode inetd pour la bibliothÃ¨que TCP Wrapper.

    Par dÃ©fautÂ : stunnel

session = timeout
    Timeout du cache de session

setgid = nom (Unix seulement)
    Nom de groupe utilisÃ© en mode daemon (les Ã©ventuels autres noms de groupe attribuÃ©s sont supprimÃ©s)

setuid = nom (Unix seulement)
    Nom d'utilisateur utilisÃ© en mode daemon

socket = a|l|r:option=valeur[:valeur]
    Configure une option de socket accept (a), locale (l) ou distante (r)

    Les valeurs de l'option linger sontÂ : l_onof:l_linger. Les valeurs de l'option time sontÂ : tv_sec:tv_usec.

    ExemplesÂ :

        socket = l:SO_LINGER=1:60
            dÃ©finit un dÃ©lai d'une minute pour la clÃ´ture des sockets locaux
        socket = r:SO_OOBINLINE=yes
            Place directement les donnÃ©es hors-bande dans le flux de rÃ©ception
            des sockets distants
        socket = a:SO_REUSEADDR=no
            dÃ©sactive la rÃ©utilisation d'adresses (activÃ©e par dÃ©faut)
        socket = a:SO_BINDTODEVICE=lo
            limite l'acceptation des connexions sur la seule interface de bouclage

taskbar = yes | no (WIN32 seulement)
    active l'icÃ´ne de la barre de tÃ¢ches

    Par dÃ©fautÂ : yes

verify = niveau
    VÃ©rifie le certificat du correspondant

        niveau 1 - vÃ©rifie le certificat s'il est prÃ©sent
        niveau 2 - vÃ©rifie le certificat
        niveau 3 - contrÃ´le le correspondant avec le certificat local

    Par dÃ©faut - pas de vÃ©rification

  OPTIONS DE SERVICE
Chaque section de configuration commence par le nom du service entre crochets. Celui-ci est utilisÃ© par le contrÃ´le d'accÃ¨s de libwrap (TCP Wrappers) et sert Ã  distinguer les services stunnel dans les fichiers de traces.

Si l'on souhaite utiliser stunnel en mode inetd (lorsqu'un socket lui est fourni par un serveur comme inetd, xinetd ou tcpserver), il faut se reporter Ã  la section MODE INETD plus bas.

accept = [hÃ´te:]port
    Accepte des connexions sur le port spÃ©cifiÃ©

    Si l'hÃ´te n'est pas indiquÃ©, le port est ouvert pour toutes les adresses IP de la machine locale.

connect = [hÃ´te:]port
    Se connecte au port distant indiquÃ©

    Par dÃ©faut, l'hÃ´te est localhost.

delay = yes | no
    Retarde la recherche DNS pour l'option Â«Â connectÂ Â»

exec = chemin_exÃ©cutable (Unix seulement)
    ExÃ©cute un programme local de type inetd

    Le cas Ã©chÃ©ant, le chemin exec est relatif au rÃ©pertoire chroot.

execargs = $0 $1 $2 ... (Unix seulement)
    Arguments pour exec, y compris le nom du programme ($0)

    Les quotes ne peuvent actuellement pas Ãªtre utilisÃ©es. Les arguments sont sÃ©parÃ©s par un nombre quelconque d'espaces.

ident = nom
    Applique le contrÃ´le d'identitÃ© d'utilisateur IDENT (RFC 1413)

local = hÃ´te
    Adresse IP de l'interface de sortie utilisÃ©e pour les connexions distantes. Cette option permet de relier une adresse statique locale.

protocol = protocole
    NÃ©gocie avec SSL selon le protocole indiquÃ©

    Actuellement gÃ©rÃ©sÂ : cifs, nntp, pop3, smtp

pty = yes | no (Unix seulement)
    Alloue un pseudo-terminal pour l'option Â«Â execÂ Â»

TIMEOUTbusy = secondes
    DurÃ©e d'attente de donnÃ©es

TIMEOUTclose = secondes
    DurÃ©e d'attente du close_notify (mis Ã  0 pour MSIE qui est boguÃ©)

TIMEOUTidle = secondes
    DurÃ©e d'attente sur une connexion inactive

transparent = yes | no (Unix seulement)
    Mode mandataire transparent

    RÃ©-Ã©crit les adresses pour qu'elles apparaissent provenir de la machine client SSL plutÃ´t que de celle qui exÃ©cute stunnel. Cette option n'est disponible en mode local (option exec) qu'avec la bibliothÃ¨que partagÃ©e LD_PRELOADing env.so shared library et en mode distant (option connect) sur les noyaux Linux 2.2 compilÃ©s avec l'option transparent proxy et seulement en mode serveur. Cette option ne se combine pas au mode mandataire (connect) sauf si la route par dÃ©faut du client vers la cible passe par l'hÃ´te qui fait tourner stunnel, qui ne peut Ãªtre localhost.

VALEUR DE RETOUR
stunnel renvoie zÃ©ro en cas de succÃ¨s, une autre valeur en cas d'erreur.

EXEMPLES
Pour encapsuler votre service imapd local avec SSLÂ :

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

Pour tunneliser un daemon pppd sur le port 2020Â :

    [vpn]
    accept = 2020
    exec = /usr/sbin/pppd
    execargs = pppd local
    pty = yes

Configuration de stunnel.conf pour utiliser stunnel en mode inetd qui lance imapd Ã  son tour (il ne doit pas y avoir de section [service_name])Â :

    exec = /usr/sbin/imapd
    execargs = imapd

FICHIERS

stunnel.conf
    Fichier de configuration de stunnel

stunnel.pem
    Certificat et clef privÃ©e de stunnel

BOGUES
L'option execargs n'admet pas les quotes.

RESTRICTIONS
stunnel ne peut Ãªtre utilisÃ© pour le daemon FTP en raison de la nature du protocole FTP qui utilise des ports multiples pour les transferts de donnÃ©es. Il existe cependant des versions SSL de FTP et de telnet.

NOTES

  MODE INETD
L'utilisation la plus commune de stunnel consiste Ã  Ã©couter un port rÃ©seau et Ã  Ã©tablir une communication, soit avec un nouveau port avec l'option connect, soit avec un programme avec l'option exec. On peut parfois cependant souhaiter qu'un autre programme reÃ§oive les connexions entrantes et lance stunnel, par exemple avec inetd, xinetd ou tcpserver.

Si, par exemple, la ligne suivante se trouve dans inetd.confÂ :

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

Dans ces cas, c'est le programme du genre inetd-style qui est responsable de l'Ã©tablissement de la connexion (imaps ci-dessus) et de passer celle-ci Ã  stunnel. Ainsi, stunnel ne doit alors avoir aucune option accept. Toutes les options de niveau service doivent Ãªtre placÃ©es dans la section des options globales et aucune section [service_name] ne doit Ãªtre prÃ©sente. Voir la section EXEMPLES pour des exemples de configurations.

  CERTIFICATS
Chaque daemon Ã  propriÃ©tÃ©s SSL doit prÃ©senter un certificat X.509 valide Ã  son interlocuteur. Il a aussi besoin d'une clef privÃ© pour dÃ©chiffrer les donnÃ©es entrantes. La mÃ©thode la plus simple pour obtenir un certificat et une clef est d'engendrer celles-ci avec le paquetage libre OpenSSL. Plus d'informations sur la gÃ©nÃ©ration de certificats se trouvent dans les pages indiquÃ©es plus bas.

Deux choses importantes lors de la gÃ©nÃ©ration de paires certificat-clef pour stunnelÂ :

•   la clef privÃ©e ne peut Ãªtre chiffrÃ©e puisque le serveur n'a aucun moyen d'obtenir le mot de passe de l'utilisateurÂ ; pour produire une clef non chiffrÃ©e, ajouter l'option -nodes Ã  la commande req de OpenSSLÂ ;

•   l'ordre du contenu du fichier .pem est significatifÂ : il doit contenir d'abord une clef privÃ©e non chiffrÃ©e, puis un certificat signÃ© (et non une demande de certificat). Il doit aussi y avoir des lignes vides aprÃ¨s le certificat et aprÃ¨s la clef privÃ©e. L'information textuelle ajoutÃ©e au dÃ©but d'un certificat doit Ãªtre supprimÃ©e afin que le fichier ait l'allure suivanteÂ :

        -----BEGIN RSA PRIVATE KEY-----
        [clef encodÃ©e]
        -----END RSA PRIVATE KEY-----
        [ligne vide]
        -----BEGIN CERTIFICATE-----
        [certificat encodÃ©]
        -----END CERTIFICATE-----
        [ligne vide]

  ALEATOIRE
stunnel doit Â«Â salerÂ Â» le gÃ©nÃ©rateur de pseudo-alÃ©atoires PRNG (pseudo random number generator) afin que SSL utilise un alÃ©atoire de qualitÃ©. Les sources suivantes sont chargÃ©es dans l'ordre jusqu'Ã  ce qu'une quantitÃ© suffisante de donnÃ©es soit lueÂ :

•   le fichier spÃ©cifiÃ© par RNDfileÂ ;

•   le fichier spÃ©cifiÃ© par la variable d'environnement RANDFILE, Ã  dÃ©faut le fichier .rnd du rÃ©pertoire $HOME de l'utilisateurÂ ;

•   le fichier spÃ©cifiÃ© par Â«Â --with-randomÂ Â» lors de la compilationÂ ;

•   le contenu de l'Ã©cran (MS-Windows seulement)Â ;

•   le socket EGD spÃ©cifiÃ© par EGDÂ ;

•   le socket EGD spÃ©cifiÃ© par Â«Â --with-egd-sockÂ Â» lors de la compilationÂ ;

•   le pÃ©riphÃ©rique /dev/urandom.

Avec un OpenSSL rÃ©cent (>=OpenSSL 0.9.5a) le chargement de donnÃ©es s'arrÃªte automatiquement lorsqu'un niveau d'entropie suffisant est atteint. Les versions prÃ©cÃ©dentes continuent Ã  lire toutes les sources puisqu'aucune fonction SSL ne leur permet de savoir que suffisamment de donnÃ©es sont disponibles.

Sur les machines MS-Windows qui n'ont pas d'interaction utilisateur sur la console, (mouvements de souris, crÃ©ation de fenÃªtres, etc.), le contenu de l'Ã©cran n'est pas suffisamment changeant et il est nÃ©cessaire de fournir un fichier d'alÃ©atoire par le biais de RNDfile.

Le fichier spÃ©cifiÃ© par RNDfile doit contenir des informations alÃ©atoires -- c'est-Ã -dire des informations diffÃ©rentes Ã  chaque lancement de stunnel. Cela est gÃ©rÃ© automatiquement sauf si l'option RNDoverwrite est utilisÃ©e. Si l'on souhaite procÃ©der manuellement Ã  la mise Ã  jour de ce fichier, la commande openssl rand des versions rÃ©centes d'OpenSSL sera sans doute utile.

Note importanteÂ : si /dev/urandom est disponible, OpenSSL a l'habitude d'utiliser celui-ci pour Â«Â salerÂ Â» le PRNG mÃªme lorsqu'il contrÃ´le l'Ã©tat de l'alÃ©atoireÂ ; ainsi, mÃªme si /dev/urandom est dernier de la liste ci-dessus, il est vraisemblable qu'il soit utilisÃ© s'il est prÃ©sent. Ce n'est pas le comportement de stunnel, c'est celui d'OpenSSL.

VOIR AUSSI

tcpd(8)
    Service de contrÃ´le d'accÃ¨s pour les services internet

inetd(8)
    Â«Â super-serveurÂ Â» internet

http://www.stunnel.org/
    Page de rÃ©fÃ©rence de stunnel

http://www.openssl.org/
    Site web du projet OpenSSL

AUTEUR

MichaÅ Trojnara
    <Michal.Trojnara@mirt.net>

ADAPTATION FRANÃAISE

Bernard Choppy
    <choppy AT free POINT fr>