# Instructions détaillées

## Démarrage et prise en main

Le plus simple est de faire fonctionner le démonstrateur sur une machine virtuelle Linux dotée de Docker qui soit accessible en SSH.

Le démonstrateur démarre un serveur Web sur le port 8225. Pour des raisons de sécurité, ce service n’est accessible que sur la boucle locale de votre machine virtuelle. Pour pouvoir l’utiliser sur votre machine, il vous faut vous connecter à la machine qui exécute le démonstrateur à l’aide de la commande :

    $ ssh -L 8225:localhost:8225 <nom de votre machine>

Vérifiez que Docker et `tmux` soient bien installées sur la machine exécutant le démonstrateur.

Rendez-vous dans le répertoire dans lequel vous avez cloné le dépôt Git du démonstrateur, puis démarrez l’environnement en exécutant le script `start.sh` :

    $ ./start.sh

Vous devriez alors voir s’afficher une fenêtre comme celle-ci (TODO capture d’écran)

Notez la dernière ligne du terminal, qui indique une liste de fenêtres. Ce sont des onglets : vous pouvez cliquer sur l’un des cinq onglets (« Système », « Expéditeur », « Destinataire », « Attaquant », « DNS ») pour changer de point de vue.

Si la souris ne fonctionne pas, il est possible d’utiliser le clavier pour changer de fenêtre : pour cela, tapez **Ctrl+B**, relâchez toutes les touches, puis tapez le chiffre entre parenthèses (compris entre 0 et 4 inclus) correspondant au numéro de la fenêtre que vous souhaitez afficher.

En parallèle, dans un navigateur, ouvrez un nouvel onglet et connectez-vous à l’adresse <http://localhost:8225>. Vous devriez obtenir une page de connexion pour la webmail Roundcube. Connectez-vous avec l’identifiant **destinataire** et le mot de passe **PasSecretDuTout**. Vous devriez alors arriver sur une boîte mail entièrement vierge.

## La fausse confirmation de commande

Nous allons étudier le cas d’un attaquant qui usurpe l’identité de l’entreprise pour envoyer de fausses confirmations de commande. Ces confirmations de commande, qui font croire à une commande pour des milliers d’euros de produits, sont conçues pour faire peur et pousser la victime à cliquer sur le lien d’annulation présent dans le mail et remplir ses informations de carte bleue.

### Envoi d’un mail légitime

Tout d’abord, pour tester le système, envoyez un mail de confirmation de commande légitime en utilisant l’infrastructure de l’expéditeur :

 1. Dans le terminal, basculez sur la fenêtre **Expéditeur**.

 2. Exécutez le script d’envoi de mail de confirmation avec la commande `./scripts/send_confirmation_email.sh` (vous pouvez utiliser la touche **Tab**  pour compléter les noms de fichiers et de répertoires).

 3. Dans la boîte mail du destinataire devrait apparaître un nouveau message : une confirmation de commande pour une savonnette.

### Envoi d’un mail frauduleux

Il est maintenant temps de passer du côté de l’attaquant et d’envoyer votre premier courriel frauduleux. Pour cela :

 1. Dans le terminal, basculez sur la fenêtre **Attaquant**.

 2. Exécutez le script de l’attaquant avec la commande `./scripts/send_email.py`.

 3. Sélectionnez le scénario **Fausse confirmation de commande** en tapant **2** puis **Entrée**.

 4. Utilisez la même adresse dans l’enveloppe SMTP que dans le corps du mail : sélectionnez le choix **1**.

 5. Utilisez le HELO par défaut en tapant directement **Entrée**.

 6. N’ajoutez pas de signature DKIM en tapant directement **Entrée**.

Le script remet ensuite le courriel frauduleux au serveur du destinataire. Ce faisant, le programme affiche les échanges au moyen du protocole SMTP.

La première ligne, `220 mx.destinataire.example ESMTP Postfix`, indique que le serveur est prêt. Notez en particulier :

 * la commande `MAIL FROM`, qui donne une adresse e-mail qui n’est pas celle de l’attaquant ;
 * le corps du message, transmise après la commande `DATA`, qui contient une ligne `From` dont l’adresse e-mail est également fausse.

Et lorsque vous affichez la boîte de réception du destinataire, vous verrez qu’une fausse confirmation de commande a bien été remise dans la boîte de réception.

Vous venez de réaliser votre première usurpation d’identité !

### Installation de la politique SPF

Nous allons maintenant nous défendre contre ce scénario précis en déployant une politique SPF.

Avec SPF, nous allons spécifier que seul le serveur de `expediteur.example`, c’est-à-dire la machine qui a envoyé la vraie confirmation de commande, a le droit d’envoyer des courriels avec ce nom de domaine. Cela se fait en ajoutant une entrée TXT dans la zone `expediteur.example` dont le contenu suit les règles de SPF.

Pour cela :

 1. Dans le terminal, basculez sur la fenêtre **DNS**.

 2. Ouvrez le fichier de zones pour `expediteur.example` avec la commande :

        nano example/expediteur.zone

 3. Utilisez les flèches du clavier pour atteindre la ligne repérée par le commentaire `;; Politique SPF`, puis supprimez le caractère `;` en début de ligne pour activer la politique SPF.

 4. Sauvegardez le fichier de zone modifié (tapez **Ctrl+O** puis **Entrée**), puis quittez (en tapant **Ctrl+X**).

 5. De retour à l’invite de commandes, rechargez le fichier de zones avec la commande :

        nsd-control reload expediteur.example

    Vous devriez voir le message « ok ». Sinon, cela signifie qu’une erreur de syntaxe s’est glissée dans le fichier de zone.

 6. Interrogez le DNS pour vérifier que votre politique SPF a été bien installée, avec la commande :

        dig TXT expediteur.example

    Dans l’affichage de cette commande, vous devriez pouvoir identifier la politique SPF que vous venez d’installer.

Pour les lecteurs avertis : normalement, après chaque modification d’un fichier de zone, il faudrait incrémenter le numéro de série contenu dans l’entrée SOA. Pour simplifier les choses, le démonstrateur a été conçu pour que cette manipulation ne soit pas nécessaire. Par ailleurs, les TTL de toutes les entrées DNS servies dans ce démonstrateur est fixé à 0 pour que les effets soient visibles immédiatement, juste en rechargeant le fichier de zones dans `nsd`.

### Activation du contrôle SPF chez le destinataire

Ce que vous venez de faire est la configuration nécessaire chez l’expéditeur.

Cependant, si vous réessayez d’envoyer le même mail frauduleux via la fenêtre « Attaquant », vous verrez que le mail passe toujours. Comment est-ce possible ?

Vous avez certes installé une politique SPF pour `expediteur.example`, mais le serveur de courriels chez `destinataire.example` ne fait pas encore de contrôle de politiques SPF. Il s’agit d’activer cela. Pour ce faire, procédez ainsi :

 1. Dans le terminal, basculez sur la fenêtre **Destinataire**.

 2. Ouvrez le fichier de configuration principal du serveur mail dans un éditeur de texte :

        nano /etc/postfix/main.cf

 3. Repérer la ligne qui suit le commentaire « Décommenter pour activer le contrôle SPF au niveau SMTP » (celle qui commence par `smtpd_recipient_restrictions`). Sur cette ligne, supprimez le caractère `#` et l’espace qui suivait ce caractère (c’est important ; ne laissez pas de blanc au début de la ligne).

 4. Sauvegardez le fichier ainsi modifié (**Ctrl+O**, **Entrée**) puis quittez (**Ctrl+X**).

 5. Informez le serveur de courriel que sa configuration a été modifiée, qu’il doit la relire et la prendre en compte :

        postfix reload

    Un message devrait apparaître, indiquant que Postfix est en train de relire la configuration.

### Victoire ?

En enfilant le chapeau de l’attaquant, essayez d’envoyer une fausse confirmation de commande avec les mêmes paramètres que plus haut. Vous verrez que les choses ne se passent plus comme prévu : le serveur de courriels du destinataire refuse désormais le message. En fait, l’attaquant n’a même pas l’occasion d’envoyer le contenu du courriel, car c’est l’adresse de l’expéditeur dans la commande `MAIL FROM` qui est contrôlée.

D’ailleurs, vous pouvez vérifier que les vraies confirmations de commande passent toujours : depuis la fenêtre **Expéditeur**, relancez le script d’envoi d’e-mail de confirmation. Vous verrez ce courriel apparaître quelques secondes plus tard dans la boîte de réception du destinataire.

## SPF tout seul ne suffit pas ##

Peut-on crier victoire ? Pas tout de suite. L’attaquant peut encore contourner cette mesure.

Sur un courrier physique, on peut écrire une adresse retour sur l’enveloppe et une adresse différente sur le papier à en-têtes qu’on glisse dans l’enveloppe. Un attaquant peut faire la même chose avec un courriel, ce qui a pour effet de contourner la protection que devait apporter SPF.

### Envoi d’un mail frauduleux avec une enveloppe différente ###

Pour voir cela en action, procédez ainsi :

 1. Dans le terminal, basculez sur la fenêtre **Attaquant**.

 2. Exécutez le script de l’attaquant avec la commande `./scripts/send_email.py`.

 3. Sélectionnez le scénario **Fausse confirmation de commande** en tapant **2** puis **Entrée**.

 4. Cette fois, utilisez une adresse différente dans l’enveloppe SMTP : sélectionnez le choix **2**, et non pas **1** comme vous le faisiez précédemment.

 5. Utilisez le HELO par défaut ; tapez directement **Entrée**.

 6. N’ajoutez pas de signature DKIM ; tapez directement **Entrée**.

Cette fois, le courriel est accepté par le serveur SMTP : l’attaquant a prétendu que le courriel frauduleux venait de chez lui dans l’enveloppe ; mais dans le courriel lui-même, visible après la commande DATA, l’attaquant se fait toujours passer pour le service client. De plus, c’est toujours l’adresse du service client qui apparaît dans les en-têtes que voit le destinataire dans son logiciel de courriels.

Pour se défendre contre cela, nous avons besoin de DMARC. DMARC requiert que l’expéditeur ait mis en place SPF, mais aussi DKIM. Nous allons donc installer DKIM dans un premier temps, puis mettre en place DMARC pour compléter notre protection.

### Génération de clefs DKIM ###

DKIM consiste à signer cryptographiquement le corps et certains en-têtes de courriels. Dans l’infrastructure de l’expéditeur, c’est le logiciel **opendkim** qui se charge d’insérer les signatures. Ce même logiciel est aussi responsable de la vérification des signatures DKIM chez le destinataire.

La première chose à faire est de générer des clefs DKIM chez l’expéditeur. On en génère deux : le premier est utilisé tout de suite et le second est une clef de réserve. Les clefs cryptographiques ont besoin d’être renouvelées régulièrement, donc lorsque la première clef est retirée du service, une troisième clef est générée et toutes les signatures se font avec la deuxième clef.

Générons des clefs DKIM pour le domaine `expediteur.example`. Pour cela, procédez ainsi :

 1. Dans le terminal, basculez sur la fenêtre **Expéditeur**.

 2. Créez l’arborescence de répertoires nécessaire pour gérer proprement les clefs :

        cd /etc/opendkim/keys
        mkdir expediteur.example
        cd expediteur.example

 3. Génerez ensuite deux clefs. On utilise les sélecteurs `demo1` et `demo2`. Le choix des sélecteurs est libre (vous pouvez choisir `toto1` et `toto2` par exemple), mais il faut utiliser les bons sélecteurs partout pour que les courriels soient correctement signés.

    Tapez deux fois la commande `opendkim-genkey` ci-dessous, ceci afin de bien générer deux clefs différentes :

        opendkim-genkey -d expediteur.example -b 2048 -s demo1
        opendkim-genkey -d expediteur.example -b 2048 -s demo2

 4. Donnez les bonnes permissions pour que le logiciel **opendkim** puisse accéder aux clefs privées :

        chown -R opendkim /etc/opendkim/keys

Les clefs sont maintenant générées. Les clefs privées, à garder secrètes, se trouvent dans des fichiers appelés `demo1.private` et `demo2.private`. Les clefs publiques, quant à elles, se trouvent dans les fichiers `demo1.txt` et `demo2.txt` et doivent être publiées dans le DNS.

### Publication des clefs publiques DKIM dans le DNS ###

L’étape suivante est donc de publier les clefs publiques dans le DNS :

 1. Toujours dans la fenêtre **Expéditeur**, obtenez les clefs publiques :

        cat demo1.txt demo2.txt

 2. Les clefs publiques se présentent sous le format nécessaire pour un fichier de zone DNS. Sélectionnez à la souris l’intégralité de la sortie de la commande précédente (il se peut que vous ayez besoin de maintenir la touche **Maj** enfoncée pour pouvoir sélectionner), puis copiez cette sélection dans le presse-papiers.

 3. Basculez sur la fenêtre **DNS**.

 4. Éditez le fichier de zone pour le domaine `expediteur.zone`, comme pour l’installation de la politique SPF :

        nano example/expediteur.zone

 5. Placez le curseur au début de la ligne suivant immédiatement le commentaire `;; Clef publique DKIM`. Supprimez cette ligne, puis collez le contenu du presse-papiers (suivant le terminal que vous utilisez, la combinaison de touches à utiliser est **Ctrl+Maj+V** ou **Maj+Inser**). Il se peut que l’affichage de l’éditeur `nano` soit perturbé par ce collage ; tapez **Ctrl+L** pour forcer un rafraîchissement complet de l’écran. Vérifiez que vous avez bien ajouté deux entrées DNS de type TXT : une pour chaque clef.

 6. Sauvegardez et quittez l’éditeur. Rechargez la zone :

        nsd-control reload expediteur.example

 7. Vérifiez la bonne présence de clefs DKIM avec `dig` :

        dig TXT demo1._domainkey.expediteur.example
        dig TXT demo2._domainkey.expediteur.example

### Terminer la configuration de DKIM chez l’expéditeur ###

Nous avons donc bien publié nos clefs DKIM dans le DNS. Finissons de configurer **opendkim** chez l’expéditeur :

 1. Rebasculez sur la fenêtre **Expéditeur**.

 2. Éditez le fichier `/etc/opendkim/opendkim.conf` et décommentez les deux lignes, à la fin du fichier, commençant par `SigningTable` et par `KeyTable` respectivement. Là encore, pensez bien à supprimer le caractère `#` mais aussi l’espace qui le suivait.

 3. Éditez le fichier `/etc/opendkim/signing_table` et décommentez la ligne commençant par `expediteur.example`. Ceci active l’ajout de signatures DKIM pour ce domaine et spécifie que la clef de signature à utiliser est celle dont le sélecteur est `demo1`.

 4. Éditez le fichier `/etc/opendkim/key_table` et décommentez les deux lignes commençant par `demo1._domainkey.expediteur.example` et `demo2._domainkey.expediteur.example` respectivement. Ceci spécifie l’emplacement des fichiers de clef privées associées aux clefs que nous comptons utiliser pour `expediteur.example`.

 5. Informez **opendkim** de la nécessité de recharger sa configuration en tapant la commande :

        killall -USR1 opendkim

Le serveur Postfix de l’expéditeur est déjà configuré pour que les courriels sortants passent par **opendkim** avant d’être remis au serveur mail destinataire. Mais il faut aussi que le serveur de courriels du destinataire vérifie les signatures !

### Configurer la vérification DKIM et DMARC chez le destinataire ###

Nous allons faire d’une pierre deux coups et activer à la fois la vérification DKIM et DMARC chez le destinataire. Pour cela :

 1. Basculez sur la fenêtre **Destinataire**.

 2. Placez-vous sur la ligne qui suit le commentaire `# Décommenter pour activer DKIM et DMARC`. Supprimez le `#` et l’espace qui suivait ce caractère.

 3. Sauvegardez, quittez puis notifiez Postfix d’un changement de configuration (`postfix reload`).

### Essai de DKIM ###

Nous allons maintenant envoyer une nouvelle confirmation de commande, qui devrait désormais arriver dans la boîte de réception du destinataire munie d’une signature DKIM :

 1. Basculez sur la fenêtre **Expéditeur**.

 2. Renvoyez le mail de confirmation de commande :

        cd /home/expediteur
        ./scripts/send_confirmation_email.sh

Vous devriez voir un nouveau courriel non lu chez le destinataire. Ouvrez-le, puis cliquez sur « En-têtes » pour visionner l’intégralité des en-têtes. Notez l’apparition de plusieurs nouveaux en-têtes.

Les en-têtes **Authentication-Results** ont été insérés par le système destinataire, au moment du contrôle SPF, DKIM (et aussi DMARC). Notez le `spf=pass`, `dkim=pass` et `dmarc=none` : cela signifie que le courriel a été émis par un serveur autorisé par la politique SPF, que la signature DKIM est bonne mais qu’il n’y avait aucune politique DMARC.

Vous devriez aussi voir un en-tête **DKIM-Signature**, contenant la signature DKIM.

#### Dépannage ####

Si le courriel n’arrive pas, il se peut qu’il n’ait pas pu être signé par opendkim. Le symptôme est l’apparition, dans la fenêtre **Système**, de messages comme :

    milter-reject: END-OF-MESSAGE from localhost[127.0.0.1]: 4.7.1 Service unavailable - try again later; from=<support@expediteur.example> to=<destinataire@destinataire.example>

Dans ce cas :

 * vérifiez qu’il n’y ait pas eu d’erreurs dans la configuration d’opendkim ;
 * vérifiez que le compte UNIX `opendkim` ait bien accès aux clefs privées.

Après contrôle, il est possible de resoumettre le message avec la commande `postqueue -f`. Le courriel devrait arriver dans la boîte du destinataire.

## DMARC, la clef de voûte ##

À ce stade, nous n’avons toujours pas contrecarré la campagne de hameçonnage que mène l’attaquant au moyen de ces fausses confirmations de commande. C’est là où DMARC entre en jeu.

Maintenant que le système destinataire contrôle SPF, DKIM et DMARC, nous pouvons protéger l’expéditeur en ajoutant une politique DMARC.

### Configuration DMARC chez l’expéditeur ###

Pour configurer DMARC chez l’expéditeur :

 1. Basculez sur la fenêtre **DNS**.

 2. Ouvrez une nouvelle fois le fichier de zone du domaine `expediteur.example`.

 3. Repérez la ligne `;; Politique DMARC`. Décommentez la ligne suivante en supprimant le caractère `;`. Changez le `p=none` en `p=reject`.

 4. Rechargez le fichier de zones, puis vérifiez la bonne publication de la politique DMARC avec la commande `dig TXT _dmarc.expediteur.example`.

### L’attaquant est-il vaincu ? ###

Voyons voir maintenant si les mails d’hameçonnage de l’attaquant passent encore. Pour rappel :

 1. Dans le terminal, basculez sur la fenêtre **Attaquant**.

 2. Exécutez le script de l’attaquant avec la commande `./scripts/send_email.py`.

 3. Sélectionnez le scénario **Fausse confirmation de commande** (choix **2**).

 4. Utilisez une adresse différente dans l’enveloppe SMTP (choix **2**).

 5. Utilisez le HELO par défaut ; tapez directement **Entrée**.

 6. N’ajoutez pas de signature DKIM ; tapez directement **Entrée**.

Cette fois, après que l’attaquant ait envoyé le mail complet, le serveur de courriels du système destinataire effectue le contrôle SPF, DKIM et DMARC. Le message ne passe pas le contrôle et est rejeté par le serveur : on peut le voir avec l’erreur `550 5.7.1 rejected by DMARC policy for expediteur.example`, vers la fin de la conversation.

Vous pourrez ensuite vérifier que les confirmations de commande authentiques passent encore.

## Et les sous-domaines ? ##

(TODO : Les newsletters ne marchent plus ; c’est parce que la politique DMARC `p=reject` s’applique aux sous-domaines de `expediteur.example`. Il manque aussi une politique SPF pour `newsletter.expediteur.example` et des clefs DKIM pour ce sous-domaine.)