HMAC is the abriviation of Hash-based Message Authentication Code. The handling of messages using HMAC, ensures that a message is not modified during transport. The message is encrypted by means of a secret key and a (small) change is immediately detectable. The development page explains how the calculation takes place.
The structure of the Hash-based code is as follows: HMAC [Websitekey]:[Base64hash]:[Nonce]:[TimeStamp]. The itallic fields in the HMAC represents the following information :
* Please note : the Base64 hash should be a string of 44 characters. If the calculation leads to more then 44 characters, it is probably calculated in hexadecimal format.
The values below are used to generate the HMAC SHA256 hash. All these parameters (except the secret key) must be concatenated into one string to generate the HMAC SHA256 hash.
* Please note : the Base64-string must contain 24 characters. If there are more than 24 characters, the Base64 string will probably be calculated using the MD5-hash in hexadecimal format
The Buckaroo Authentication Debugger on the Buckaroo development environment can be used to calculate the HMAC. The calculated value can be compared with the outcome of the own build calculation functionality. If the Execute button is used in de debugger, the calculation will be made. At the right half of the screen the explanation on the calculation will be given. The values of the steps in between will be shown like :
The Buckaroo .NET SDK specifies how the signature of a message can be calculated before sending and verified upon receipt of the messages. In this way it is easy to check whether the message has been sent by Buckaroo and arrived unedited at the Push URL. Use the button below to go directly to the SDK.
The following points of attention are applicable when JAVA is used to implement the Buckaroo Payment solutions. The checkout of Buckaroo hosts an example for java encoding. The following examples of implementation issues are good to take notice of:
The Base64 on the MD5 hash is often calculated by standard JAVA components. The requested output can sometimes not be delivered by these components. The example code in a ZIP for java describes how the signature can be calculated. By comparing this example with the own written code, the developer of the functionality can distinguish the way the logic should be build up.
First of all: please take notice of the way the Timestamp calculation is build up in java. Please consult the website of TecAdmin for this. For calculating the local timestamp it does not matter if the local London or Amsterdam time is used. The most common issue is the calculation to be done in seconds : do not use milliseconds. An unix timestamp works on the time difference in seconds between 1 jan 1970 (epoch) and now. In java this time is normally withdrawn in milliseconds. Therefore the result should be divided by 1000. If this is forgotten, the result is 1000 time bigger and it looks as if the message comes from a moment in the very far future. The following example code can help the developer out on this:
// 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);
Sometimes a HMAC error message appears after importing the Buckaroo WSDL in the java environment. In that cas: please try to load the following WSDL for soap using java. The error should not show up using this WDSL.