HMAC-generator

Hoe je dit gebruikt HMAC-generator

1. Voer het bericht en de geheime sleutel in.
2. Kies het algoritme, meestal SHA-256.
3. Vergelijk de gegenereerde handtekening met de ontvangen.

Waar het voor dient

Het dagelijkse toepassingsgeval zijn webhooks.

Als een externe dienst een verzoek naar je server stuurt — een betaalbevestiging, een statuswijziging — weet je in eerste instantie niet of het echt van die dienst komt, want je URL kan iedereen kennen.

HMAC lost dat op: de afzender berekent uit de berichtinhoud en een gedeeld geheim een handtekening en stuurt die mee. Jij berekent dezelfde handtekening met hetzelfde geheim en vergelijkt.

Komen ze overeen, dan komt het bericht van iemand die het geheim kent en is het niet gewijzigd.

Het tweede geval zijn ondertekende API-verzoeken, waarbij methode, pad, tijdstempel en berichtinhoud samen worden ondertekend.

Een belangrijke nuance: HMAC is geen versleuteling. Het bericht blijft leesbaar; HMAC waarborgt alleen herkomst en integriteit.

En het is ook geen elektronische handtekening in juridische zin: beide partijen kennen hetzelfde geheim, dus beide kunnen de handtekening maken. Voor rechtsgeldigheid gelden de eIDAS-verordening en de gekwalificeerde elektronische handtekening, die op asymmetrische cryptografie berust.

Correct verifiëren

Bij het verifiëren worden steeds dezelfde fouten gemaakt.

Vergelijk de handtekeningen in constante tijd. Een gewone tekstvergelijking stopt bij het eerste afwijkende teken, en uit die looptijd is de juiste handtekening stap voor stap af te leiden. Vrijwel elke taal heeft daar een eigen functie voor.

Onderteken de ruwe inhoud van het verzoek, niet het geparseerde en opnieuw geserialiseerde object. Een andere spatiëring of een andere volgorde van JSON-sleutels verandert de handtekening.

Controleer de tijdstempel als de aanbieder die meestuurt, en wijs te oude verzoeken af. Anders kan een aanvaller een geldig bericht later opnieuw versturen.

Let op de precieze codering: hexadecimaal of Base64, hoofdletters of kleine letters, met of zonder voorvoegsel. Aanbieders doen dat verschillend, en dat is de meest voorkomende oorzaak van een handtekening die "bijna" klopt.

En behandel het geheim als een wachtwoord: niet in de broncode, niet in de repository, maar in de omgevingsconfiguratie.

Welk algoritme

De keuze van het hash-algoritme is eenvoudiger dan het lijkt.

SHA-256 is de verstandige standaardinstelling en wat de meeste aanbieders gebruiken.

Opvallend is dat HMAC zelf vrij goed bestand is tegen zwakheden van de onderliggende hashfunctie, waardoor HMAC-SHA1 niet direct als gebroken geldt. Toch is er geen reden om er iets nieuws mee te bouwen.

De sleutellengte zou minstens gelijk moeten zijn aan de uitvoerlengte van de hashfunctie, bij SHA-256 dus 32 willekeurige bytes.

En de sleutel moet echt willekeurig zijn. Een zelfbedacht geheim is de zwakste schakel in de hele keten.

Deze tool rekent volledig in je browser en de sleutel verlaat je apparaat niet. Toch geldt: gebruik voor productiegeheimen geen webinterface maar je eigen omgeving.

Veelgestelde vragen