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)
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 ;
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.
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 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).
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.
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.
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).
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 :
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 :
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.
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:TCP_NODELAY=1
désactive l'algorithme Nagle pour les sockets distants
socket = r:SO_OOBINLINE=1
Place directement les données hors-bande dans le flux de réception
des sockets distants
socket = a:SO_REUSEADDR=0
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
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.
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.
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.
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 :
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.
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 :
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.