Signature generation

All humm APIs are publicly accessible. In order to prevent against request-tampering, man-in-the-middle attacks, and other malicious behavior, humm requires all API requests to include a digital signature and will include a digital signature on all API responses.

For all API requests to humm, the digital signature will be verified. Responses should always be verified on the POS side before continuing.

The signing mechanism used by humm is based on HMAC-SHA256. Every individual device that communicates with humm must use its cryptographic signing-key known as the 'device-signing-key' to generate the HMAC (hash-based message authentication code). The device-signing-key is installed securely during the one-time 'device initialisation' operation.

To generate a digital signature, do the following steps:

1. Create a string of all "x_" fields (i.e. with a name starting with "x_") in the request as key-value pairs, sorted alphabetically, and concatenated without separators.
2. Sign the message using HMAC_SHA256 to produce a signature.

Add the 'signature' to the request and that's it!

On the humm side, we'll perform the same algorithm with the same device-signing-key for the HMAC_SHA256 to produce a matching signature. If anything changes on the request, even just a single character, then a completely different signature would be generated. A non-matching signature would result in an authorisation error.

Below is a C#.NET code snippet that demonstrates how a signature might be generated:

public static string GenerateHMAC(string apiKey, IDictionary<string,string> payloadValues)
{
  using (var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(apiKey)))
  {
      string payloadSignature = 
        payloadValues
          .Where(kvp=> kvp.Key.StartsWith("x_"))
          .OrderBy(kvp=>kvp.Key)
          .Select(kvp => $"{kvp.Key}{kvp.Value}")
          .Aggregate((current, next) => $"{current}{next}");

      var rawHmac = hmac.ComputeHash(Encoding.UTF8.GetBytes(payloadSignature));

      return BitConverter.ToString(rawHmac).Replace("-", string.Empty).ToLower();
  }
}