Signature API HMAC-SHA256

Ce qu'est réellement HMAC

HMAC (Hash-based Message Authentication Code) est un hachage à clé. Il prend un secret et un message et produit une signature de taille fixe qui dépend des deux.

Parce que le secret est intégré au calcul, seule une personne qui connaît le secret peut produire ou vérifier la signature. Cela fait de HMAC le cheval de trait de l'authentification API, de la vérification de webhooks et des charges utiles signées.

HMAC n'est pas du chiffrement : la signature ne cache rien, et quiconque l'intercepte peut la lire. HMAC apporte l'authentification et l'intégrité — la preuve que le message vient de quelqu'un qui détient le secret.

Quand vous avez besoin de signatures HMAC

Les cas les plus courants : les webhooks et les requêtes API. Quand un fournisseur publie un événement sur votre point de terminaison, la signature confirme l'authenticité de la charge utile. Quand un client appelle votre API, une requête signée prouve qu'il détient le secret.

• Webhooks : le destinataire vérifie la signature pour prouver que la charge utile provient de l'expéditeur
• Authentification API : les clients signent les requêtes avec un secret partagé au lieu d'envoyer un mot de passe
• Contrôles d'intégrité : détecter les altérations de message entre services
• Protection contre le rejeu : signer un message qui inclut un horodatage ou un nonce

Créer une signature HMAC-SHA256 : pas à pas

La canonicalisation fait échouer les intégrations le plus souvent. Lors de ma première configuration de webhook, chaque signature échouait : l'expéditeur ajoutait un saut de ligne final inattendu. La solution : nous mettre d'accord sur les octets exacts — clés JSON, échappement, fins de ligne.

// Exemple : chaîne canonique et HMAC-SHA256 en Node.js
const canonical = [method, path, timestamp, body].join('\n');
const signature = crypto.createHmac('sha256', secret).update(canonical).digest('hex');

1. Ouvrez le générateur HMAC dans votre navigateur.
2. Sélectionnez SHA-256 comme algorithme.
3. Collez votre clé secrète dans le champ clé. Générez-en une avec le générateur de mot de passe si nécessaire.
4. Collez le message ou la charge utile exacte à signer, octet pour octet.
5. Copiez la signature générée et joignez-la à la requête, par exemple comme en-tête Authorization ou X-Signature.

Vérifier les signatures en toute sécurité côté réception

La vérification est un second calcul HMAC avec le même secret et le même message, comparé à la signature reçue.

La comparaison doit être en temps constant. Une comparaison de chaînes classique peut fuiter des informations de timing qui aident les attaquants à forger des signatures.

Une comparaison classique s'arrête au premier caractère différent ; le temps de réponse révèle la proximité de la tentative. Avec assez d'échantillons, la signature se reconstitue octet par octet ; une comparaison en temps constant exécute toujours les mêmes opérations.

// Node.js : comparaison en temps constant
const crypto = require('crypto');
const expected = Buffer.from(signature, 'hex');
const received = Buffer.from(given, 'hex');
const valid = expected.length === received.length && crypto.timingSafeEqual(expected, received);

Erreurs HMAC courantes

• Coder le secret en dur dans le code côté client où tout le monde peut le lire
• Signer le corps mais pas la méthode, le chemin et l'horodatage, permettant les attaques par rejeu
• Utiliser == ou une comparaison de chaînes classique pour vérifier la signature
• Réutiliser le même secret entre environnements ou ne jamais le faire tourner
• Envoyer la signature dans un outil qui journalise le secret avec le message
• Construire la chaîne canonique différemment du destinataire : ordre des clés JSON, espaces de fin
• Comparer les octets de la signature dans des encodages différents, hex contre base64

FAQ

Références

• RFC 2104 – HMAC : Hachage à clé pour l'authentification de message : https://www.rfc-editor.org/rfc/rfc2104
• NIST FIPS 198-1 – The Keyed-Hash Message Authentication Code (HMAC) : https://csrc.nist.gov/pubs/fips/198-1/final
• RFC 7515 – JSON Web Signature (JWS) : https://www.rfc-editor.org/rfc/rfc7515
• OWASP Secrets Management Cheat Sheet : https://cheatsheetseries.owasp.org/cheatsheets/Secrets_Management_Cheat_Sheet.html