DragonFly On-Line Manual Pages
STUNNEL.FR(8) stunnel 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 concu pour fonctionner comme une couche de
chiffrement SSL entre des clients distants et des serveurs locaux
(inetd-demarrables) ou distants. Le concept est qu'a partir de daemons
non-SSL presents sur le systeme, on peut facilement les configurer pour
communiquer avec des clients sur des liens securises SSL.
stunnel peut etre utilise pour ajouter des fonctionnalites SSL a des
daemons classiques Inetd tels que les serveurs POP-2, POP-3 et IMAP, a
d'autres autonomes tels que NNTP, SMTP et HTTP, ainsi que pour
tunneliser PPP sur des sockets reseau sans modification du code source.
Ce produit inclut du code de chiffrement ecrit par Eric Young
(eay@cryptsoft.com)
OPTIONS
[fichier]
Utilisation du fichier de configuration specifie.
-fd [n] (Unix seulement)
Lecture du fichier de configuration depuis le descripteur de
fichier indique.
-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 defaut.
-install (NT/2000/XP seulement)
Installe un service NT.
-uninstall (NT/2000/XP only)
Desinstalle un service NT.
FICHIER DE CONFIGURATION
Chaque ligne du fichier de configuration peut etre soit :
o une ligne vide (ignoree) ;
o un commentaire commencant par << # >> (ignore) ;
o une paire << option = valeur >> ;
o << [service_name] >> indiquant le debut de la definition d'un
service ;
OPTIONS GLOBALES
CApath = repertoire
Repertoire des autorites de certification (CA)
C'est le repertoire dans lequel stunnel cherche les certificats si
l'on utilise verify. Les certificats doivent etre denommes selon la
forme XXXXXXXX.0, ou XXXXXXXX est la valeur de hachage du
certificat.
Le cas echeant, le repertoire CApath est relatif au repertoire
chroot.
CAfile = fichier
Fichier d'autorites de certification
Ce fichier, utilise avec verify, contient plusieurs certificats de
CA.
cert = fichier
Fichier de chaine de certificats PEM
Une PEM est toujours necessaire en mode serveur. En mode client,
cette option utilise cette PEM comme une chaine cote client.
L'utilisation de certificats cote client est optionnelle. Les
certificats doivent etre au format PEM et tries par ordre de niveau
decroissant (CA racine en premier).
chroot = repertoire (Unix seulement)
Repertoire de chroot du processus stunnel
chroot enferme stunnel dans une cellule chroot. CApath, CRLpath,
pid et exec sont situes a l'interieur de la cellule et les
repertoires doivent etre relatifs au repertoire correspondant.
Pour que le controle 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
Selection des chiffres SSL autorises
Liste delimitee par deux-points (<< : >>) des chiffres autorises
pour la connexion SSL. Exemple : DES-CBC3-SHA:IDEA-CBC-MD5
client = yes | no
Mode client (Le service distant utilise SSL)
Par defaut : no (mode server)
CRLpath = repertoire
Repertoire des listes de revocation de certificats (CRL)
C'est le repertoire dans lequel stunnel recherche les CRL avec
l'option verify. Les CRL doivent etre denommes selon la forme
XXXXXXXX.0 ou XXXXXXXX est la valeur de hachage de la CRL.
Le cas echeant, le repertoire CRLpath est relatif au repertoire
chroot.
CRLfile = fichier
Fichier de listes de revocation de certificats (CRL)
Ce fichier, utilise avec verify, contient plusieurs CRL.
debug = [facilite.]niveau
niveau de deverminage
Le niveau est un nom ou un numero conforme a 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 indique et des
niveaux numeriquement inferieurs seront affichees. debug = debug ou
debug = 7 donneront le maximum d'informations. La valeur par defaut
est notice (5).
La facilite syslog << daemon >> est utilisee, sauf si un autre nom
est specifie (Win32 ne permet pas l'usage des facilites.)
La casse est ignoree, aussi bien pour la facilite que pour le
niveau.
EGD = chemin (Unix seulement)
Emplacement du socket du daemon de recueil d'entropie (EGD -
Entropy Gathering Daemon)
Socket EGD a utiliser pour alimenter le generateur d'aleatoires de
OpenSSL (disponible seulement si la compilation a ete effectuee
avec OpenSSL 0.9.5a ou superieur).
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 specifie).
Par default : arriere-plan en mode daemon.
key = fichier
Fichier de clef privee pour le certificat specifie par cert
La clef privee est necessaire pour authentifier le titulaire du
certificat. Puisque ce fichier doit rester secret, il ne doit etre
lisible que par son proprietaire. Sur les systemes Unix, on peut
utiliser la commande suivante :
chmod 600 fichier
Par default : Valeur de cert
options = Options_SSL
Options de la bibliotheque OpenSSL
Le parametre est l'option OpenSSL decrite dans la page de man
SSL_CTX_set_options(3ssl), debarassee du prefixe SSL_OP_.
Plusieurs options peuvent etre specifiees.
Par exemple, pour la compatibilite avec l'implantation SSL
defaillante d'Eudora, on peut utiliser :
options = DONT_INSERT_EMPTY_FRAGMENTS
output = fichier
Ajoute la trace a la fin d'un fichier au lieu d'utiliser syslog.
/dev/stdout peut etre utilise 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 cree.
Le cas echeant, le chemin pid est relatif au repertoire chroot.
RNDbytes = nombre
Nombre d'octets a lire depuis les fichiers de << sel >> aleatoire
Avec les SSL de version inferieure a 0.9.5a, determine aussi le
nombre d'octets consideres comme suffisants pour << saler >> le
PRNG. Les versions plus recentes d'OpenSSL ont une fonction
integree qui determine lorsque l'aleatoire est suffisant.
RNDfile = fichier
chemin du fichier de donnees de << sel >> aleatoire
La bibliotheque SSL utilise prioritairement les donnees de ce
fichier pour << saler >> le generateur d'aleatoire.
RNDoverwrite = yes | no
Recouvre les fichiers de << sel >> avec de nouvelles donnees
aleatoires.
Par defaut : yes
service = nom
Definit le nom de service a utiliser
Sous Unix : nom de service du mode inetd pour la bibliotheque TCP
Wrapper.
Par defaut : stunnel
session = timeout
Timeout du cache de session
setgid = nom (Unix seulement)
Nom de groupe utilise en mode daemon (les eventuels autres noms de
groupe attribues sont supprimes)
setuid = nom (Unix seulement)
Nom d'utilisateur utilise 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
definit un delai d'une minute pour la cloture des sockets locaux
socket = r:SO_OOBINLINE=yes
Place directement les donnees hors-bande dans le flux de reception
des sockets distants
socket = a:SO_REUSEADDR=no
desactive la reutilisation d'adresses (activee par defaut)
socket = a:SO_BINDTODEVICE=lo
limite l'acceptation des connexions sur la seule interface de bouclage
taskbar = yes | no (WIN32 seulement)
active l'icone de la barre de taches
Par defaut : yes
verify = niveau
Verifie le certificat du correspondant
niveau 1 - verifie le certificat s'il est present
niveau 2 - verifie le certificat
niveau 3 - controle le correspondant avec le certificat local
Par defaut - pas de verification
OPTIONS DE SERVICE
Chaque section de configuration commence par le nom du service entre
crochets. Celui-ci est utilise par le controle d'acces de libwrap (TCP
Wrappers) et sert a 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 a la section MODE INETD plus bas.
accept = [hote:]port
Accepte des connexions sur le port specifie
Si l'hote n'est pas indique, le port est ouvert pour toutes les
adresses IP de la machine locale.
connect = [hote:]port
Se connecte au port distant indique
Par defaut, l'hote est localhost.
delay = yes | no
Retarde la recherche DNS pour l'option << connect >>
exec = chemin_executable (Unix seulement)
Execute un programme local de type inetd
Le cas echeant, le chemin exec est relatif au repertoire chroot.
execargs = $0 $1 $2 ... (Unix seulement)
Arguments pour exec, y compris le nom du programme ($0)
Les quotes ne peuvent actuellement pas etre utilisees. Les
arguments sont separes par un nombre quelconque d'espaces.
ident = nom
Applique le controle d'identite d'utilisateur IDENT (RFC 1413)
local = hote
Adresse IP de l'interface de sortie utilisee pour les connexions
distantes. Cette option permet de relier une adresse statique
locale.
protocol = protocole
Negocie avec SSL selon le protocole indique
Actuellement geres : cifs, nntp, pop3, smtp
pty = yes | no (Unix seulement)
Alloue un pseudo-terminal pour l'option << exec >>
TIMEOUTbusy = secondes
Duree d'attente de donnees
TIMEOUTclose = secondes
Duree d'attente du close_notify (mis a 0 pour MSIE qui est bogue)
TIMEOUTidle = secondes
Duree d'attente sur une connexion inactive
transparent = yes | no (Unix seulement)
Mode mandataire transparent
Re-ecrit les adresses pour qu'elles apparaissent provenir de la
machine client SSL plutot que de celle qui execute stunnel. Cette
option n'est disponible en mode local (option exec) qu'avec la
bibliotheque partagee LD_PRELOADing env.so shared library et en
mode distant (option connect) sur les noyaux Linux 2.2 compiles
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 defaut du client vers la cible passe par l'hote qui fait
tourner stunnel, qui ne peut etre localhost.
VALEUR DE RETOUR
stunnel renvoie zero en cas de succes, 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 a 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 privee de stunnel
BOGUES
L'option execargs n'admet pas les quotes.
RESTRICTIONS
stunnel ne peut etre utilise pour le daemon FTP en raison de la nature
du protocole FTP qui utilise des ports multiples pour les transferts de
donnees. Il existe cependant des versions SSL de FTP et de telnet.
NOTES
MODE INETD
L'utilisation la plus commune de stunnel consiste a ecouter un port
reseau et a etablir 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 recoive 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'etablissement de la connexion (imaps ci-dessus) et de
passer celle-ci a stunnel. Ainsi, stunnel ne doit alors avoir aucune
option accept. Toutes les options de niveau service doivent etre
placees dans la section des options globales et aucune section
[service_name] ne doit etre presente. Voir la section EXEMPLES pour des
exemples de configurations.
CERTIFICATS
Chaque daemon a proprietes SSL doit presenter un certificat X.509
valide a son interlocuteur. Il a aussi besoin d'une clef prive pour
dechiffrer les donnees entrantes. La methode 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 generation de
certificats se trouvent dans les pages indiquees plus bas.
Deux choses importantes lors de la generation de paires certificat-clef
pour stunnel :
o la clef privee ne peut etre chiffree puisque le serveur n'a aucun
moyen d'obtenir le mot de passe de l'utilisateur ; pour produire
une clef non chiffree, ajouter l'option -nodes a la commande req de
OpenSSL ;
o l'ordre du contenu du fichier .pem est significatif : il doit
contenir d'abord une clef privee non chiffree, puis un certificat
signe (et non une demande de certificat). Il doit aussi y avoir
des lignes vides apres le certificat et apres la clef privee.
L'information textuelle ajoutee au debut d'un certificat doit etre
supprimee afin que le fichier ait l'allure suivante :
-----BEGIN RSA PRIVATE KEY-----
[clef encodee]
-----END RSA PRIVATE KEY-----
[ligne vide]
-----BEGIN CERTIFICATE-----
[certificat encode]
-----END CERTIFICATE-----
[ligne vide]
ALEATOIRE
stunnel doit << saler >> le generateur de pseudo-aleatoires PRNG
(pseudo random number generator) afin que SSL utilise un aleatoire de
qualite. Les sources suivantes sont chargees dans l'ordre jusqu'a ce
qu'une quantite suffisante de donnees soit lue :
o le fichier specifie par RNDfile ;
o le fichier specifie par la variable d'environnement RANDFILE, a
defaut le fichier .rnd du repertoire $HOME de l'utilisateur ;
o le fichier specifie par << --with-random >> lors de la
compilation ;
o le contenu de l'ecran (MS-Windows seulement) ;
o le socket EGD specifie par EGD ;
o le socket EGD specifie par << --with-egd-sock >> lors de la
compilation ;
o le peripherique /dev/urandom.
Avec un OpenSSL recent (>=OpenSSL 0.9.5a) le chargement de donnees
s'arrete automatiquement lorsqu'un niveau d'entropie suffisant est
atteint. Les versions precedentes continuent a lire toutes les sources
puisqu'aucune fonction SSL ne leur permet de savoir que suffisamment de
donnees sont disponibles.
Sur les machines MS-Windows qui n'ont pas d'interaction utilisateur sur
la console, (mouvements de souris, creation de fenetres, etc.), le
contenu de l'ecran n'est pas suffisamment changeant et il est
necessaire de fournir un fichier d'aleatoire par le biais de RNDfile.
Le fichier specifie par RNDfile doit contenir des informations
aleatoires -- c'est-a-dire des informations differentes a chaque
lancement de stunnel. Cela est gere automatiquement sauf si l'option
RNDoverwrite est utilisee. Si l'on souhaite proceder manuellement a la
mise a jour de ce fichier, la commande openssl rand des versions
recentes 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 meme lorsqu'il controle
l'etat de l'aleatoire ; ainsi, meme si /dev/urandom est dernier de la
liste ci-dessus, il est vraisemblable qu'il soit utilise s'il est
present. Ce n'est pas le comportement de stunnel, c'est celui
d'OpenSSL.
VOIR AUSSI
tcpd(8)
Service de controle d'acces pour les services internet
inetd(8)
<< super-serveur >> internet
http://www.stunnel.org/
Page de reference de stunnel
http://www.openssl.org/
Site web du projet OpenSSL
AUTEUR
Michal Trojnara
<Michal.Trojnara@mirt.net>
ADAPTATION FRANCAISE
Bernard Choppy
<choppy AT free POINT fr>
5.05 2014.09.22 STUNNEL.FR(8)