Provided by: stunnel4_4.53-1.1ubuntu1_amd64 
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>