03. HMAC et authenticité partagée

Comprendre le mécanisme

HMAC combine une fonction de hash et une clé selon une construction définie. Un MAC valide établit une authenticité relative aux détenteurs de cette clé ; il ne cache pas le message et ne distingue pas lequel de plusieurs détenteurs l’a produit. Ne remplacez pas HMAC par une concaténation improvisée de clé et de message. Le format exact des octets authentifiés doit être partagé par les participants.

Raisonner et vérifier

Pour un webhook, documentez corps brut ou représentation canonique, version du protocole, métadonnées couvertes et protection contre le rejeu. Un MAC correct sur un ancien événement ne le rend pas nouveau. Les clés doivent être propres à l’usage et à l’environnement. Vérifiez avec une API adaptée et bornez les entrées avant les opérations coûteuses.

Clé partagée

HMAC utilise une clé secrète partagée. L’authenticité dépend notamment de la protection de cette clé. Émetteur et vérificateur possèdent le même secret. Limitez ce groupe de confiance et distribuez la clé dans un gestionnaire de secrets ; une copie publique dans un dépôt retire la propriété attendue.

Auteur dans le groupe

Tout détenteur de la clé peut calculer un MAC. La capacité symétrique n’est pas séparée. Si deux services connaissent la clé, chacun peut produire le même MAC. La preuve ne permet pas à elle seule d’attribuer l’origine à l’un plutôt qu’à l’autre devant un tiers.

Message visible

HMAC ne chiffre pas le message. Le contenu peut rester lisible. Le corps authentifié reste lisible pour qui le reçoit. Utilisez un canal chiffré ou une construction de chiffrement adaptée lorsqu’une confidentialité est nécessaire, sans confondre secret de clé et secret du contenu.

Octets exacts

Les octets authentifiés doivent être définis. Les octets peuvent changer malgré un sens métier similaire. Pour un webhook, le protocole peut signer timestamp et corps brut. Ne parsez puis resérialisez pas le JSON avant vérification si cela change les octets couverts par la preuve reçue.

Construction dédiée

Une concaténation maison ne remplace pas HMAC. Une construction standard possède des propriétés spécifiques. hash(key . message) n’est pas une définition interchangeable de HMAC. Utilisez hash_hmac ou la bibliothèque du protocole, avec algorithme et représentation explicitement fixés des deux côtés.

Rejeu

Le rejeu demande un contrôle distinct. La preuve d’origine ne garantit pas la nouveauté. Un message ancien peut garder un MAC valide. Vérifiez la fenêtre temporelle prescrite et consommez une identité d’événement de façon durable et atomique pour empêcher la répétition d’un effet métier.

Séparation des clés

Les clés doivent être séparées par usage pertinent. Le partage élargit les capacités affectées. Une clé de signature de webhook ne doit pas servir par commodité de clé de chiffrement ou de session. La séparation limite les interactions entre protocoles et l’impact d’une divulgation.

Comparaison

Une comparaison adaptée doit vérifier la preuve. Une conversion peut confondre des représentations. Calculez la référence avec les octets et la clé attendus puis utilisez une comparaison adaptée, comme hash_equals pour les chaînes de ce contrat. Vérifiez format et taille avant la comparaison.

Métadonnées liées

Les métadonnées couvertes doivent suivre le protocole. Seuls les octets couverts participent à la preuve. Signer le corps sans les métadonnées nécessaires peut laisser une ambiguïté de destination ou d’interprétation. Suivez exactement le profil du fournisseur, y compris version de signature et timestamp lorsqu’ils sont prescrits.

Fixtures publiques

Les fixtures ne doivent pas contenir les clés réelles. Le support ne doit pas exposer une capacité réelle. Les clés répétées dans les exemples servent uniquement au laboratoire. Générez un secret réel adapté dans l’environnement concerné et excluez-le des captures, logs de tests et exports de diagnostic.

Atelier guidé : lire, expliquer et vérifier le code

<?php
declare(strict_types=1);
$key = str_repeat('k', 32); // fixture publique de laboratoire
$a = hash_hmac('sha256', 'amount=10', $key);
$b = hash_hmac('sha256', 'amount=11', $key);
var_dump(hash_equals($a, $b));

Les messages amount=10 et amount=11 sont différents au niveau des octets ; leurs MAC calculés avec la même clé diffèrent. Exécutez le programme puis changez également la clé. Observez que cette preuve ne masque pas le montant et qu’une répétition du premier message garderait sa preuve valide.

HMAC admet ces deux messages. Comparer des preuves n’accorde pas de permission métier. Les octets couverts changent ; les deux MAC calculés sont différents. La clé identique ne rend pas tous les messages équivalents.

Travail pratique : Modifiez les espaces du JSON, rejouez un message valide et testez une autre clé dans un récepteur local.

Critères de correction : Selon le contrat de corps brut, des octets modifiés invalident le MAC. Ajoutez le suivi d’événement et la fenêtre temporelle requis pour refuser le rejeu indépendamment de l’authenticité.

Webhook PSP : preuve, fraîcheur et transition durable

Commencez par conserver le corps brut borné reçu et le timestamp requis par le contrat. Vérifiez le format de signature exact avec la bibliothèque ou construction prescrite. Parser puis resérialiser le JSON avant vérification peut changer les octets et invalider la preuve, ou conduire à vérifier autre chose que le message reçu.

Contrôlez la fraîcheur selon une fenêtre bornée et une horloge maîtrisée. Une signature valide ne prouve pas à elle seule que l’événement est nouveau : le fournisseur peut relivrer et un message ancien peut être rejoué.

Enregistrez durablement l’identité d’événement et appliquez une transition métier autorisée dans une frontière cohérente, ou utilisez une inbox durable avant traitement différé. Acquittez selon ce point de durabilité, puis prévoyez reprise et déduplication. Testez signature incorrecte, timestamp ancien, doublon simultané et panne après effet avant réponse. Chaque scénario doit conserver un seul effet et permettre un diagnostic sans token ni secret dans les traces.

Points de vigilance : La vérification doit suivre le contrat exact du PSP ; la transaction ou l’inbox durable protège ensuite l’effet contre les relectures. La réécriture peut changer les octets signés ; supprimer le contrôle temporel affaiblit la protection contre le rejeu. Un événement authentique peut être relivré légitimement plusieurs fois. L’IP ne remplace pas les contrôles du contrat, et les événements n’annoncent pas tous un succès.