Custom Program
Authentication

As the API endpoint is created on your end, the responsibility of ensuring the validity of the message lies there. Galileo will create and send a Hash-based Message Authentication Code (HMAC) along with each request. The HMAC is a signature used to authenticate the source of the messages as well as a way to insure data integrity.

Using a secret key that has been agreed upon with Galileo, the HMAC can be generated at the endpoint and then compared to the Signature parameter found in the message header. To generate the HMAC, use the following steps:

1 Extract and sort

Extract the following header parameters:

  • Encryption-Type
  • Content-Length
  • Date
  • Content-Type
  • User-ID

Using the extracted header parameters and all of the POST parameters, sort the parameters alphabetically with all parameters that are capitalized first, and then lowercase. Most sorting functions in programming languages will sort by ASCII code value which will work the same.

Please Note: Some HTTP libraries will lowercase the D in 'User-ID' resulting in 'User-Id' being passed in the header parameter (shown in sample). Please change the parameter name 'User-Id' to 'User-ID' to calculate the HMAC value.

From the sample request above, sorting the parameters will result in the following (single quotes added to show any extra white-space in parameter value):

  • Content-Length: '360'
  • Content-Type: 'application/x-www-form-urlencoded'
  • Date: '20170504:141752UTC'
  • Encryption-Type: 'HMAC-SHA256'
  • User-ID: 'galileo'
  • Balance_id: '55555'
  • act_type: 'DB'
  • amount: '16.45'
  • open_to_buy: '0.56'
  • cad: '166666'
  • mcc: '6011'
  • merchant_location: 'VERONA, MS'
  • merchant_name: 'RENASANT BANK'
  • merchant_numer: 126786 '
  • network: 'D'
  • otype: 'W'
  • prn: '199999999998'
  • prod_id: '5043'
  • prog_id: '511'
  • response_code: '00'
  • timestamp: '2017-05-04 14:17:51 MST'
  • auth_id: '10542539'
  • type: 'auth'
2 Encode

 Take the URL decoded value of the parameters and base64 encode the value. The values should not be trimmed leaving all white-space that may have been pass in the request. From the sample request above, the encoded values should match the values listed below:

  • Content-Length: MzYw
  • Content-Type: YXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVk
  • Date: MjAxNzA1MDQ6MTQxNzUyVVRD
  • Encryption-Type: SE1BQy1TSEEyNTY=
  • User-ID: Z2FsaWxlbw==
  • account_id: NTU1NTU=
  • act_type: REI=
  • amount: LTE2LjQ1
  • auth_tran_type: Nw==
  • open_to_buy: MC41Ng==
  • card_id: MTY2NjY2
  • cur_code: ODQw
  • mcc: NjAxMQ==
  • merchant_location: VkVST05BLCBNUw==
  • merchant_name: UkVOQVNBTlQgQkFOSw==
  • merchant_number: UkVOQVNBTlQgQkFOSyAg
  • network: RA==
  • otype: Vw==
  • prn: MTk5OTk5OTk5OTk4
  • prod_id: NTA0Mw==
  • prog_id: NTEx
  • response_code: MDA=
  • auth_id: MTA1NDI1Mzk=
  • tran_timestamp: MjAxNy0wNS0wNCAxNDoxNzo1MQ==
  • tran_type: YXV0aA==
  • type: YXV0aA==
3 Combine

 Take the parameter name, followed by a pipe ('|') character, and then the parameter value base64 encoded and combine all of the parameters into a single string. Please Note: There is no space in-between the previous parameter's value and the next parameter name. From the example request, the result will be:


Content-Length|MzYwContent-
Type|YXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkDate|MjAxNzA1MDQ6MTQxNzUyVVRDEncryptionType|SE1BQy1TSEEyNTY=User-
ID|Z2FsaWxlbw==account_id|NTU1NTU=act_type|REI=amount|LTE2LjQ1auth_id|MTIzNDU=auth_network|RA== auth_tran_type|Nw==balance|MC41Ng==card_id|MTY2NjY2cur_code|ODQwmcc|NjAxMQ==merch_loc|VkVST05 BLCBNUw==merch_name|UkVOQVNBTlQgQkFOSw==merch_num|UkVOQVNBTlQgQkFOSyAgotype|Vw==prn|MT k5OTk5OTk5OTk4prod_id|NTA0Mw==prog_id|NTExresponse_code|MDA=tran_id|MTA1NDI1Mzk=tran_timestam p|MjAxNy0wNS0wNCAxNDoxNzo1MQ==tran_type|YXV0aA==type|YXV0aA==
4 Generate HMAC

Using the secret key agreed upon previously with Galileo and the hashing algorithm from the header parameter, use the HMAC libraries found in most modern languages and generate the HMAC digest. Currently, only SHA256 is supported. Base64 encode the digest to generate the final signature. Below are examples in some common languages to generate the HMAC.

Python

import base64
import hmac
import hashlib

hmac_key = "secret key"
encoded_params = "Content..."
dig = hmac.new(hmac_key, msg=encoded_params, digestmod=hashlib.sha256).digest()
signature = base64.b64encode(dig)
print(signature) # rINogDh6RL6EDw+XCiNMKiDCchfZ+kUNJhHJuThssYY=
PHP
$secretKey = "secret key";
$dataString = "Content...";
$digest = hash_hmac('sha256', $dataString, $secretKey, false);
$signature = base64_encode($digest); echo $signature; // rINogDh6RL6EDw+XCiNMKiDCchfZ+kUNJhHJuThssYY=
Java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

String key = "secret key";
String data = "Content...";
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec secret = new SecretKeySpec(key.getBytes("utf-8"), "HmacSHA256");
mac.init(secret); byte[] digest = mac.doFinal(data.getBytes("utf-8"));
String signature = Base64.getEncoder().encodeToString(digest);
System.out.println(signature); // rINogDh6RL6EDw+XCiNMKiDCchfZ+kUNJhHJuThssYY=
5 Compare

Compare the generated HMAC with the 'Signature' parameter in the header. If they match, the message should be considered authenticated