HMAC

De afkorting staat voor Hash-based Message Authentication Code. Deze bewerking van berichten waarborgt het kunnen controleren of een bericht tijdens het transport niet is aangepast. Door middel van een secret key wordt het bericht versleuteld en is een (kleine) verandering direct detecteerbaar. Op de authenticatie pagina (EN) staat uitgelegd hoe de afhandeling van de berekening gaat.

De opbouw van de Hash-based code is als volgt : HMAC [Websitekey]:[Base64hash]:[Nonce]:[TimeStamp]. De schuin gedrukte velden in de HMAC staan voor de volgende informatie:

• Website key : terug te vinden in de Buckaroo Plaza onder Instellingen → Websites

• Base64 hash : hierbij wordt de HMAC SHA256 ondertekening gebruikt, waarbij de Secret Key voor de versleuteling wordt gebruikt. Zie ook de uitleg hieronder*

• Nonce : een willekeurig gekozen reeks van karakters, welke voor ieder verzoek uniek dient te zijn

• TimeStamp : tijdsindicatie van het moment van indienen van het request. Zie ook de time stamp beschrijving hieronder

Gebruikte velden in de hash

Zie hieronder de waarden die worden gebruikt om de HMAC SHA256-hash te genereren. Al deze parameters (behalve de secret key) moeten worden samengevoegd tot één tekenreeks voor het genereren van de HMAC SHA256-hash.​

Website key : Overnemen uit de Buckaroo Plaza. Te vinden onder Instellingen → Websites
Request method : GET of POST in hoofdletters
Request URI : waar wordt het request naar toegestuurd? Let op: laat het https:// gedeelte hierbij weg
Request timestamp : de timestamp bevat het aantal seconden dat is verstreken sinds 01-01-1970 (00:00:00:00), uitgedrukt in de UTC tijdszone. UTC staat voor Coordinated Universal Time
Nonce : een willekeurig gekozen reeks van karakters, welke voor ieder verzoek uniek dient te zijn
Request content string : genereer een MD5-hash over de onbewerkte gegevens van het bericht. Converteer deze hash vervolgens naar een Base64-string. *
Secret Key: karakter string die in de Buckaroo Plaza is opgevoerd en welke wordt gebruikt om de verstuurde berichten te decoderen en controleren. De secret key is te vinden in de Plaza via Instellingen → Secret Key. Indien deze leeg is, kan deze worden gevuld met een zelfgekozen willekeurig gekozen letter/cijfer combinatie.

Debugging

Met de authentication debugger
kan de HMAC worden berekend en vergeleken met de uitkomst van de eigen gebouwde functionaliteit. Wanneer in de debugger op Execute wordt geklikt, zal de berekening worden gedaan en staat er uitleg aan de rechterzijde. De gegevens uit de tussenstappen zal ook worden getoond zoals :

1. MD5 hash over de bericht inhoud
2. Base64 over de MD5 hash
3. Concatenation result van de websiteKey, httpMethod, requestUri, timeStamp, nonce + encodedContent
4. De Hmac SHA256 hash over de concatenated string, ondertekent met de secret key
5. De Base64 over de HmacSHA256 hash
6. De complete authorization header : HMAC

Handtekening berekening

In de .NET SDK van Buckaroo staat de manier uitgeschreven waarop de handtekening van een bericht kan worden berekend voor verzending en kan worden geverifieerd bij ontvangst van de berichten. Op die manier kan op eenvoudige wijze worden gecontroleerd of het bericht is verzonden door Buckaroo en onbewerkt is aangekomen bij de Push URL. Gebruik deze link om direct naar de SDK toe te gaan.

Java implementaties

Wanneer er gebruik wordt gemaakt van een Java implementatie, zijn een aantal aandachtspunten van toepassing. Hier is een authenticatie integratie in JavaScript uitgeschreven. Hieronder enkel voorbeelden van problematieken uit de praktijk.

Hash

De Base64 over de MD5 hash wordt vaak uitgevoerd door standaard Java componenten, maar niet altijd met de gewenste output. In een voorbeeld code in ZIP voor Java kan worden terug gevonden hoe de handtekening berekening plaats kan vinden. Vergelijken met de eigen ontwikkelde code geeft de bouwer inzicht in de manier waarop de logica kan worden opgebouwd.

Timestamp

Als eerste kan gebruik worden gemaakt van de uitleg van de Timestamp berekening in java op de website van TecAdmin. Wanneer geprobeerd wordt een lokale timestamp te berekenen, maakt het niet uit of het bericht de tijd uit London of Amsterdam heeft. Wat wel uitmaakt is dat de tijd (soms) in milliseconden wordt berekend in plaats van seconden. Een unix timestamp werkt met een uitgerekende tijdsverschil tussen 1 jan 1970 (epoch) en nu, uitgedrukt in seconden. In java wordt deze tijd standaard opgehaald in milliseconden, wat betekent dat het resultaat moet worden gedeeld door 1000. Als dat niet gebeurt, wordt het resultaat 1000 keer groter en lijkt het alsof een bericht uit de verre toekomst wordt ingeschoten. De volgende voorbeeldcode kan daar een oplossing voor zijn:

// EXAMPLE FOR THE CALCULATION OF THE UNIX TIMESTAMP.
// A UNIX TIMESTAMP IS THE TIMESPAN BETWEEN THE UNIX EPOCH (1-1-1970) AND THE CURRENT TIME, DEFINED IN SECONDS.
private String calculateUnixTimeStamp()
{
long unixTime = System.currentTimeMillis() / 1000L; // the division by 1000 is performed to convert msec -> sec
String timeInSecondsAsString = Long.toString(unixTime);

return timeInSecondsAsString;
}

WSDL en java

Soms komt een HMAC foutmelding naar voren bij de import van de WSDL in een java omgeving. Daarbij is het mogelijk de volgende WSDL voor soap in java te gebruiken, waarbij die foutmelding niet voorkomt.