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>