Accueil » Formations » Hygiène numérique » Authentification multifacteur : TOTP, FIDO2 et bonnes pratiques » TP01 – Générer et vérifier des codes TOTP avec oathtool

TP01 – Générer et vérifier des codes TOTP avec oathtool

← Authentification multifacteur : TOTP, FIDO2 et bonnes pratiques

// travaux pratiques · Hygiène numérique

TP01 - Générer et vérifier des codes TOTP avec oathtool

  • TP 1 / 6
  • 7 étapes
  • ≈ 40 min
  • Accès libre

Objectif : préparer le laboratoire du cours, générer un secret TOTP, calculer les codes en ligne de commande avec oathtool, les comparer à ceux d’une application sur smartphone et observer l’effet de l’horloge et de la fenêtre de tolérance.

Contexte

Avant de protéger un serveur ou un service par TOTP, il faut comprendre ce qui se passe quand un code est refusé. Dans la grande majorité des tickets « mon code ne marche pas », la cause est l’une de trois : une horloge décalée, un secret mal recopié, ou un code déjà utilisé. Ce TP démonte le mécanisme décrit par la RFC 6238 en reproduisant le calcul à la main : vous verrez que le téléphone et le serveur ne communiquent jamais, ils font simplement le même calcul à partir du même secret et de la même heure.

À la fin du TP, vous saurez générer un secret de taille correcte, l’enregistrer dans une application d’authentification par QR code, calculer et vérifier un code TOTP, et diagnostiquer un refus lié au temps. Cette VM servira aux TP suivants.

Prérequis : une machine virtuelle Debian 12 ou 13 (2 Go de RAM suffisent) avec un compte utilisateur membre du groupe sudo et un accès SSH ; un smartphone avec une application TOTP (FreeOTP, Aegis sous Android, ou l’application de votre choix).

Durée estimée : 40 minutes.

Actions à réaliser

1. Installer les outils

Le paquet oathtool fournit l’outil de calcul HOTP/TOTP de l’OATH Toolkit ; qrencode affichera le QR code d’enrôlement dans le terminal. On vérifie aussi que l’horloge est synchronisée, condition de base de tout TOTP.

sudo apt update
sudo apt install oathtool qrencode
timedatectl

Résultat attendu : les deux paquets s’installent sans erreur. La sortie de timedatectl affiche l’heure locale, l’heure universelle (UTC) et une ligne System clock synchronized: yes. Si elle indique no, réglez la synchronisation avant de continuer (voir Problèmes fréquents).

2. Générer un secret de 160 bits

La RFC 4226 impose un secret d’au moins 128 bits et en recommande 160, soit 20 octets, la taille de sortie de HMAC-SHA-1. On lit 20 octets aléatoires et on les encode en base32, le format attendu par les applications.

SECRET=$(head -c 20 /dev/urandom | base32)
echo "$SECRET"

head -c 20 lit exactement 20 octets depuis le générateur aléatoire du noyau ; base32 (coreutils) les transforme en 32 caractères majuscules et chiffres de 2 à 7. Résultat attendu : une chaîne de 32 caractères sans signe = final, puisque 20 octets tombent juste en base32.

Ce secret est un secret de laboratoire : en production, il ne doit jamais apparaître dans un historique de shell ni dans une capture d’écran.

3. Calculer un code avec oathtool

oathtool --totp -b "$SECRET"
oathtool --totp -b -v "$SECRET"

--totp active le mode temporel (HMAC-SHA-1 par défaut ; --totp=SHA256 ou SHA512 pour les variantes), -b indique que la clé est en base32 (sinon oathtool attend de l’hexadécimal), -v affiche le détail du calcul. Résultat attendu : un code de 6 chiffres ; en mode verbeux, oathtool rappelle le secret en hexadécimal, le pas de temps (30 secondes), l’heure de départ (1970-01-01 UTC), l’heure courante et le compteur utilisé, suivis du code.

4. Retrouver le compteur à la main

Le compteur T de la RFC 6238 vaut l’heure Unix divisée par 30, arrondie à l’entier inférieur. Le shell suffit pour le vérifier :

echo $(( $(date +%s) / 30 ))

Résultat attendu : le nombre affiché est égal au compteur indiqué par oathtool -v lancé dans la même demi-minute (ou supérieur d’une unité si 30 secondes se sont écoulées entre les deux commandes). Vous venez de vérifier qu’aucune donnée ne transite entre le serveur et l’application : seule l’heure commune compte.

5. Enrôler le secret dans l’application du smartphone

Les applications importent un secret via une URI otpauth:// encodée en QR code. On construit l’URI avec un émetteur (issuer) et un nom de compte, qui servent uniquement à l’affichage.

qrencode -t ANSIUTF8 "otpauth://totp/Lab:alice?secret=${SECRET}&issuer=Lab"

-t ANSIUTF8 dessine le QR code avec des caractères Unicode dans le terminal. Scannez-le avec l’application. Résultat attendu : une entrée « Lab (alice) » apparaît dans l’application et affiche un code qui change toutes les 30 secondes. Agrandissez la fenêtre du terminal si le QR code est coupé.

6. Comparer et valider les codes

Lancez oathtool --totp -b "$SECRET" et comparez avec le code de l’application : ils doivent être identiques dans la même tranche de 30 secondes. Validez ensuite le code lu sur le téléphone, comme le ferait un serveur, avec une fenêtre de tolérance :

oathtool --totp -b -w 1 "$SECRET" 123456

Remplacez 123456 par le code affiché sur le téléphone. Quand un code est fourni, -w définit la fenêtre de validation. Résultat attendu : pour un code valide, oathtool affiche la position du code trouvé dans la fenêtre et rend la main avec le code de retour 0 (echo $?) ; pour un code faux, il signale l’échec et renvoie un code non nul.

7. Observer l’effet du temps

oathtool --totp -b -N "2026-01-01 08:00:00 UTC" "$SECRET"
oathtool --totp -b -N "2026-01-01 08:00:29 UTC" "$SECRET"
oathtool --totp -b -N "2026-01-01 08:00:30 UTC" "$SECRET"
oathtool --totp -b -w 2 "$SECRET"

-N fixe l’heure utilisée pour le calcul. Résultat attendu : les deux premières commandes donnent le même code (même pas de 30 secondes), la troisième un code différent. La dernière affiche trois codes : le code courant suivi des deux suivants, ce que vous verriez si l’horloge du téléphone avançait.

Vérification

  • Le code d’oathtool et celui du téléphone coïncident sur trois périodes successives.
  • La validation d’un code du téléphone avec -w 1 renvoie 0, et celle d’un code inventé échoue.
  • Vous savez expliquer pourquoi deux heures séparées de 29 secondes peuvent donner le même code, et deux heures séparées d’une seconde des codes différents.

Problèmes fréquents

  • Codes toujours différents du téléphone. Cause : horloge de la VM ou du téléphone décalée, fréquent après une restauration d’instantané. Correction : timedatectl, puis sudo timedatectl set-ntp true et vérifier que le téléphone est en heure automatique.
  • oathtool répond qu’il ne peut pas décoder la clé. Cause : option -b oubliée, la clé est alors lue comme de l’hexadécimal ; ou caractère invalide (base32 n’utilise ni 0, 1, 8 ni 9). Correction : ajouter -b et recopier le secret.
  • L’application refuse le QR code. Cause : le & de l’URI interprété par le shell faute de guillemets, ou variable vide dans un nouveau terminal. Correction : mettre l’URI entre guillemets doubles et vérifier echo "$SECRET".
  • QR code illisible. Cause : police ou fenêtre trop petite. Correction : agrandir le terminal ou générer une image avec qrencode -o lab.png.

Bonnes pratiques et sécurité

  • Générez les secrets avec une source aléatoire du système et une taille d’au moins 160 bits pour SHA-1.
  • Ne laissez pas un secret réel dans l’historique : history -c en fin de laboratoire, et jamais de secret de production dans un script versionné.
  • Considérez le QR code d’enrôlement comme un mot de passe : ne l’envoyez ni par courriel ni par messagerie.
  • Gardez la synchronisation NTP active sur tous les serveurs qui valident des codes TOTP et surveillez-la.

Questions de contrôle

1. Le serveur et le téléphone échangent-ils des données pour produire le même code ?

Voir la réponse

Non. Ils partagent le secret depuis l’enrôlement et calculent chacun HMAC(secret, heure Unix / 30). Seule l’heure doit concorder.

2. Pourquoi lire 20 octets aléatoires plutôt que 8 ?

Voir la réponse

20 octets donnent 160 bits, la taille recommandée par la RFC 4226 et la longueur de sortie de HMAC-SHA-1 ; 8 octets (64 bits) sont sous le minimum de 128 bits.

3. Que permet l’option -w lors d’une validation ?

Voir la réponse

Elle accepte un code proche dans le temps (fenêtre de tolérance), pour absorber un léger décalage d’horloge ou de saisie.

Pour aller plus loin

  • Testez les variantes --totp=SHA256 et -d 8 et vérifiez que votre application les accepte : toutes ne prennent pas en charge ces paramètres.
  • Lisez la RFC 6238, en particulier les sections sur la resynchronisation et le rejeu.
  • Pour situer le TOTP parmi les autres facteurs, relisez l’article L’authentification multifacteur : renforcez la sécurité.

Conservez la VM et l’entrée « Lab » du téléphone : le secret sera réutilisé au TP02.

// formation sur mesure

Former votre équipe sur ce sujet ?

Azur Secure anime des sessions intra-entreprise, à distance ou dans vos locaux sur la Côte d'Azur, adaptées au niveau de vos équipes.

Demander un programme
Défiler vers le haut