stunnel.8

- NOM
- SYNOPSIS
- DESCRIPTION
- OPTIONS
- FICHIER DE CONFIGURATION

- OPTIONS GLOBALES
- OPTIONS DE NIVEAU SERVICE

- VALEUR DE RETOUR
- EXEMPLES
- FICHIERS
- BUGS
- RESTRICTIONS
- NOTES

- MODE INETD
- CERTIFICATS
- ALÉATOIRES

- VOIR AUSSI
- AUTEUR

# NOM

stunnel - tunnel SSL universel

# SYNOPSIS

stunnel [filename] | -help | -version | -sockets

# DESCRIPTION

Le programme stunnel est conçu pour agir en tant que wrapper de chiffrement SSL entre des clients distants et des serveurs locaux (activables par inetd) ou distants. Le concept est qu'ayant des daemons non-SSL sur votre système, il est possible de les configurer aisément pour communiquer avec des clients sur des canaux SSL sécurisés.

stunnel peut être utilisé pour ajouter une fonctionnalité SSL à des daemons Inetd communs, tels que les serveurs POP-2, POP-3 et IMAP, à des daemons autonomes tels que NNTP, SMTP et HTTP et pour tunneliser PPP sur des sockets réseaux sans modification du code source.

Ce produit contient du code de chiffrement écrit par Eric Young (eay@cryptsoft.com)

# OPTIONS

[filename]
  Utilise le fichier de configuration spécifié

-help
  Affiche le menu d'aide de stunnel

-version
  Affiche la version et la configuration de compilation de stunnel

-sockets
  Affiche les options par défaut des sockets

-install (NT/2000/XP seulement)
  Installe le service NT

-uninstall (NT/2000/XP seulement)
  Désinstalle le service NT

# FICHIER DE CONFIGURATION

Chaque ligne du fichier de configuration peut être soit :

- une ligne vide (ignorée) ;

- un commentaire débutant par un ``#'' (ignoré) ;

- une paire ``option = valeur'' ;

- ``[service]'' indiquant le début d'une définition de service.

## OPTIONS GLOBALES

CApath = répertoire
  Répertoire de l'autorité de certification

  C'est le répertoire dans lequel stunnel cherche les certificats avec verify. Les certificats doivent être nommés XXXXXXXX.0 où XXXXXXXX est la valeur de hachage du certificat.

CAfile = fichier
  Fichier de l'autorité de certification

  Ce fichier contients plusieurs certificats utilisés avec verify.

cert = fichier
  Nom du fichier de la chaîne de certification PEM

  Une PEM est toujours nécessaire en mode serveur. En mode client, cette option utilise cette chaîne comme chaîne de certificat client. L'utilisation de certificats clients est optionnelle. Les certificats doivent être au format PEM et triés par ordre de niveau décroissant (à partir de l'autorité racine).

chroot = répertoire (Unix seulement)
  répertoire de chroot pour le processus stunnel.

  chroot enferme stunnel dans une cellule d'arborescence. CApath, pid et exec sont disposés à l'intérieur de la cellule et les chemins doivent être relatifs au répertoire chroot.

  Pour que le contrôle libwrap (TCP wrappers) soit effectif en environnement chroot, il faut y copier ses fichiers de configuration (/etc/hosts.allow et /etc/hosts.deny).

ciphers = liste
  Sélection des codages SSL autorisés

  Liste délimitée des codages à autoriser dans une connexion SSL. Par exemple : DES-CBC3-SHA:IDEA-CBC-MD5

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

  défaut: no (mpde serveur)

debug = [facilité.]niveau
  Niveau de déverminage

  Le niveau est en phase avec ceux de syslog : emerg (0), alert (1), crit (2), err (3), warning (4), notice (5), info (6), ou debug (7). Toutes les traces de niveau inférieur ou égal numériquement seront affichées. debug = debug ou debug = 7 donne le niveau de détail maximal. La valeur par défaut est notice (5).

  La facilité syslog 'daemon' sera utilisée par défaut (les facilités ne sont pas supportées par Win32).

  La casse des caractères est sans signification.

EGD = chemin (Unix seulement)
  Chemin vers la socket du daemon de rassemblement d'entropie (EGD, Entropy Gathering Daemon socket).

  Socket d'EGD à utiliser pour alimenter le générateur d'aléatoires d'OpenSSL (disponible seulement à partir d'OpenSSL 0.9.5a).

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

  Maintien en avant-plan (sans fork) et trace sur stderr au lieu de syslog (sauf si output est spécifié).

  défaut : arrière-plan en mode daemon.

key = fichier
  Clef privée pour le certificat spécifié à cert

  La clef privée est nécessaire pour l'authentification du propriétaire du certificat. Puisque ce fichier doit rester secret, il ne doit être lisible que par son propriétaire. Sous Unix on peut utiliser :

          chmod 600 fichier

  défaut : valeur de cert

options = options_SSL
  Options de la bibliothèque OpenSSL

  Ce paramètre est le nome de l'option OpenSSL ainsi que décrite dans le manuel SSL_CTX_set_options(3ssl), mais sans le préfixe SSL_OP_. Plusieurs options peuvent être utilisées.

  Par exemple, la compatibilité avec l'implantation défectueuse de SSL dans Eudora peut être assurée par :

          options = DONT_INSERT_EMPTY_FRAGMENTS

output = fichier
  Spécification du fichier de messages au lieu de syslog.

pid = fichier (Unix seulement)
  Emplacement du fichier pid (contenant le numéro de processus).

  Si l'argument est vide, aucun fichier pid ne sera créé.

RNDbytes = octets
  Nombre d'octets à lire depuis les fichiers de sel aléatoire.

  Avec SSL de version inférieure à 0.9.5a, détermine aussi le nombre d'octets suffisants pour saler le PRNG. Les versions plus récentes d'OpenSSM ont une fonction intégrée qui détermine lorsque le niveau d'aléatoire est suffisant.

RNDfile = fichier
  Chemin vers le fichier de données de sel.

  La bibliothèque SSL utilisera en priorité les données de ce fichier pour alimenter le générateur d'aléatoires.

RNDoverwrite = yes | no
  Écrase les fichiers de sel aléatoire avec de nouvelles valeurs.

  défaut : yes

service = service
  Spécification du nom de service.

  Sur Unix : nom de service de mode inetd pour TCP Wrapper ;

  Sur NT/2000/XP : nom de service NT dans le panneau de configuration.

  défaut : stunnel

session = timeout
  Timeout du cache de session

setgid = groupe (Unix seulement)
  En mode daemon, `setgid()` vers le groupe spécifié et désactivation de tous les autres groupes de rattachement.

setuid = utilisateur (Unix seulement)
  En mode daemon, `setuid()` vers l'utilisateur spécifié.

socket = a|l|r:option=valeur[:valeur]
  Positionne une option sur les sockets accept/local/remote

  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
              positionne un timeout d'une minute pour la clôture d'un socket local.
          socket = r:TCP_NODELAY=1
              désactive l'algorithme Nagle pour les sockets distants.
          socket = r:SO_OOBINLINE=1
              place les données out-of-band directement dans le flux de réception
              pour les sockets distants.
          socket = a:SO_REUSEADDR=0
              désactive la réutilisation d'adresses (activée par défaut).
          socket = a:SO_BINDTODEVICE=lo
              n'accepte les connexions que sur l'interface de rebouclage.

verify = niveau
  Vérification du certificat de l'interlocuteur

          niveau 1 - vérification du certificat s'il est présent ;
          niveau 2 - vérification du certificat ;
          niveau 3 - contrôle de l'interlocuteur avec le certificat installé en local ;
          défaut   - pas de vérification.

## OPTIONS DE NIVEAU SERVICE

Chaque section de configuration débute par le nom du service entre crochets. Celui-ci est utiliser pour le contrôle d'accès libwrap (TCP Wrappers) et permet de distinguer les services stunnel dans les fichiers de trace.

Si l'on veut utiliser stunnel en monde inetd (dans lequel un socket réseau est fourni par un serveur comme inetd, xinetd, ou tcpserver), il faut lire la section MODE INETD ci-après.

accept = [hôte:]port
  Accepte les connexions du hôte spécifié sur le port spécifié.

  Si aucun hôte n'est spécifié, toutes les adresses IP par défaut pour l'hôte local.

connect = [hôte:]port
  Connextion à l'adresse hôte:port.

  Si aucun hôte n'est spécifié, connexion sur localhost.

delay = yes | no
  Délai de recherche DNS pour l'option 'connect'.

exec = chemin (Unix seulement)
  Exécution d'un programme local de type inetd.

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

  Les guillemets ne sont pas supportés actuellement. Les arguments sont séparés par un nombre quelconque d'espaces.

ident = utilisateur
  Utilisation du contrôle de nom d'utilisateur IDENT (RFC 1413).

local = hôte
  Adresse IP de l'interface de sortie pour les connexions distantes. Cette option permet de connecter une adresse IP statique.

protocol = protocole
  Négociation SSL avec le protocole indiqué (actuellement : smtp, pop3 ou nntp).

pty = yes | no (Unix seulement)
  Allocation d'un pseudo-terminal pour l'option 'exec'.

TIMEOUTbusy = secondes
  Durée d'attente des données.

TIMEOUTclose = secondes
  Durée d'attente pour close_notify (positionné à 0 pour MSIE buggé).

TIMEOUTidle = secondes
  Durée de maintien d'une connexion inactive.

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

  Réécriture de l'adresse afin que la connexion apparaisse comme provenant de la machine client SSL plutôt que de celle exécutant stunnel. Cette option n'est disponible en mode local (option exec) qu'avec l'option LD_PRELOAD de la bibliothèque partagée env.so ou en mode distant (option connect) sur un noyau Linux 2.2 compilé avec l'option transparent proxy puis seulement en mode serveur. Cette option est incompatible avec le mode mandataire (connect) sauf si la route par défaut vers la machine cible passe par l'hôte 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 un service local imapd dans SSL :

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

Pour tunnelliser le daemon pppd sur le port 2020 :

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

Pour que stunnel lance le processus imapd en mode inetd, le fichier stunnel.conf sera ainsi (il ne doit y avoir aucune section [service]):

        exec = /usr/sbin/imapd
        execargs = imapd

# FICHIERS

stunnel.conf
  Fichier de configuration de stunnel.

stunnel.pem
  Certificat et clef privée de stunnel.

# BUGS

L'option execargs ne supporte pas les guillemets.

# RESTRICTIONS

stunnel ne peut être utilisé pour le daemon FTP en raison de la nature de ce protocole qui ouvre de multiples ports pour les transferts de données. Il existe cependant des versions de FTP et de telnet qui permettent l'utilisation de SSL.

# NOTES

## MODE INETD

L'utilisation la plus courante de stunnel est l'écoute sur un port réseau pour établir des communications, soit sur un nouveau port avec l'option connect, soit avec un programme avec l'option exec. Dans certains cas, il est souhaitable qu'un autre programme accepte les connexions entrantes puis passe la main à stunnel (par exemple avec inetd, xinetd, ou tcpserver).

Imaginons la ligne suivante dans inetd.conf :

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

Dans ce cas, le programme de style inetd est en charge de la connexion du socket réseau (imaps ci-dessus) et du passage à stunnel une fois la connexion reçue. Ainsi, stunnel ne doit pas avoir d'option accept/ Toutes les options de niveau service doivent être dans la section des options globales et il ne doit pas y avoir de section [service]. Se reporter à la section EXEMPLES.

## CERTIFICATS

Chasue daemon SSL-isé doit présenter un certificat X.509 valide à son interlocuteur. Il nécessite aussi une clef privée pour déchiffrer les données entrantes. La méthode la plus simple d'obtention d'un certificat et d'une clef est de les engendrer à l'aide du paquetage lible OpenSSL. Plus d'informations sur la génération de certificats est disponible sur les pages indiquées plus bas.

Deux points importants lors de la génération de paires certificat-clef pour stunnel : la clef privée ne peut être chiffrée car le serveur n'a aucun moyen d'accéder au mot de passe de l'utilisateur ; l'option -nodes de la commande req du kit OpenSSL permet de produire une clef non chiffrée.

L'ordre du contenu du fichier .pem est important aussi : il doit contenir la clef privée non chiffrée en premier, puis un certificat signé (pas de requête de certificat). Il doit y avoir aussi des lignes vides après le certificat et la clef privée. L'information en texte simple ajoutée sur le certificat engendré doit être supprimée. Ainsi, le fichier doit se présenter comme suit :

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

## ALÉATOIRES

stunnel doit alimenter le générateur d'aléatoires (PRNG - pseudo random number generator) pour fournir à SSL un bon niveau d'aléatoires. Les sources suivantes sont chargées dans l'ordre jusqu'à ce qu'une quantité suffisante d'informations aléatoires ait été rassemblée :

- le fichier spécifié par RNDfile ;

- le fichier spécifié par la variable d'environnement éventuelle RANDFILE ;

- le fichier $HOME/.rnd si RANDFILE n'est pas positionné ;

- le fichier spécifié avec '--with-random' lors de la compilation ;

- le contenu de l'écran en environnement Windows ;

- le socket spécifié par EGD ;

- le socket spécifié avec '--with-egd-sock' lors de la compilation ;

- le périphérique /dev/urandom.

Si les versions récentes (>=OpenSSL 0.9.5a) de SSL cessent le chargement automatiquement lorsqu'une entropie suffisante a été rassemblée, ce n'est pas le cas des versions précédentes qui ne disposent pas d'une fonction permettant de déterminer cela.

Sur les machines Windows sans interaction utilisateur (mouvements de souris, création de fenêtres, etc.), le contenu de l'écran n'est pas suffisamment variable et il faut fournir un fichier d'aléatoires à l'aide de RNDfile.

Le fichier spécifié par RNDfile doit contenir des données aléatoires -- donc des données différentes pour chaque lancement de stunnel. Cela est réalisé automatiquement sauf si RNDoverwrite est utilisé. Pour la mise à jour manuelle de ce fichier, la commande openssl rand des versions récentes d'OpenSSL peut être utile.

Note importante -- si /dev/urandom est disponible, OpenSSL a pour habitude de l'utiliser, quel que soit l'état d'aléatoire, donc il sera vraisemblablement utilisé même s'il est indiqué en dernière position de la liste ci-dessus. C'est un comportement de OpenSSL, pas de stunnel.

# VOIR AUSSI

tcpd(8)
  système de contrôle d'accès pour les services internet.

inetd(8)
  ``super-serveur'' internet

http://stunnel.mirt.net/
  Site de stunnel

http://www.stunnel.org/
  Foire aux questions stunnel

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

# AUTEUR

Michal Trojnara
  <Michal.Trojnara@mirt.net>

Adaptation française Bernard Choppy <choppy@imaginet.fr>