Generate Signatue – Jenga Docs

Why signatures?

To ensure the security of your transactions or requests, we have implemented security controls that ensure transactions can only be initiated by you and no one else. To achieve this, we use message signatures.

How it works

All requests, other than the Identity API, will be required to have a signature in the header. The structure of the header will be as follows:

HTTP: Signature Header

Signature: {{signature_in_base64}}

To generate the signature, you will need create a key pair of private key and public key. You will share the public key with us and use the private key to generate the signature.

Creating private & public keys

Use following command in your preferred terminal to generate a keypair with a self-signed certificate.

In this command, we are using the openssl. You can use other tools e.g. keytool (ships with JDK - Java Developement Kit), keystore explorer (opens in a new tab) e.t.c

Generate Private Key

openssl genrsa -out privatekey.pem 2048

Once you are successful with the above command a file (privatekey.pem) will be created on your present directory, proceed to export the public key from the keypair generated. The command below shows how to do it.

Generate Public Key

openssl rsa -in privatekey.pem -outform PEM -pubout -out publickey.pem

If the above command is successful, a new file (publickey.pem) will be created on your present directory. Copy the contents of this file and add it on our jengaHQ portal. Make sure to copy only the contents of the keyblock and paste as is.

The Generated Key Files

The privatekey.pem file looks something like this:

Example Private Key

Example Public Key

Generating the signature

The first step to generating the signature is to prepare the data to be signed. This is done by concatenating (joining) particular values within the API request payload. Different APIs will have different formulae for concatenation and this is detailed in each API's documentation.

To illustrate this, we use the Opening and Closing Account Balance API (opens in a new tab).

The request payload looks like this:

{
  "countryCode": "KE",
  "accountId": "0011547896523",
  "date": "2018-08-09"
}

The instructions further say:

A SHA-256 signature to proof that this request is coming from the merchant. Build a String of concatenated values of the request fields with the following order: accountId, countryCode, date. The resulting text is then signed with Private Key and Base64 encoded.

We can see that the data to be signed is a concatenation of the values in the fields: accountId, countryCode and date and in that order and from our payload above, that would be: 0011547896523KE2018-08-09. This is the data we will sign.

Now onto signing. The mechanism of signing this data will depend on the language you are using. For instance, if you are using PHP or Python, you would go about it as follows;

<?php
$plainText  = "0011547896523KE2018-08-09"; // See separate instruction on how to create this concatenation
$privateKey = openssl_pkey_get_private(("file://path/to/privatekey.pem"));
$token      = "QNg9X7cLJSpZVOpaJJ33wX0AbcRF";
 
openssl_sign($plainText, $signature, $privateKey, OPENSSL_ALGO_SHA256);

from base64 import b64encode
 
from Crypto.Hash import SHA256
from Crypto.Signature import PKCS1_v1_5
from Crypto.PublicKey import RSA
 
message = "0011547896523KE2018-08-09".encode('utf-8') # See separate instruction on how to create this concatenation
digest = SHA256.new()
digest.update(message)
 
private_key = False
with open("privatekey.pem", "r") as myfile:
    private_key = RSA.importKey(myfile.read())
 
signer = PKCS1_v1_5.new(private_key)
sigBytes = signer.sign(digest)
signBase64 = b64encode(sigBytes)

Your generated signature is now in a variable $signature or signBase64 in the Python example.

You can now include it in your request as follows;

<?php
$plainText  = "0011547896523KE2018-08-09";
$privateKey = openssl_pkey_get_private(("file://path/to/privatekey.pem"));
$token      = "QNg9X7cLJSpZVOpaJJ33wX0AbcRF";
 
openssl_sign($plainText, $signature, $privateKey, OPENSSL_ALGO_SHA256);
 
 
$curl        = curl_init();
$data_string = '{
    "countryCode":"KE",
    "accountId":"0011547896523",
    "date":"2018-08-09"
    }';
 
curl_setopt_array($curl, array(
    CURLOPT_URL => "https://sandbox.jengahq.io/account-test/v3/accounts/accountbalance/query",
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => "",
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_POSTFIELDS => $data_string,
    CURLOPT_HTTPHEADER => array(
        "Authorization: Bearer " . $token,
        "cache-control: no-cache",
        "Content-Type: application/json",
        "signature: " . base64_encode($signature)
    )
));
$result = curl_exec($curl);
$err    = curl_error($curl);
 
curl_close($curl);
 
if ($err) {
    echo "cURL Error #:" . $err;
} else {
    echo $result;
}
?>

import json
import requests
 
 
from base64 import b64encode
 
from Crypto.Hash import SHA256
from Crypto.Signature import PKCS1_v1_5
from Crypto.PublicKey import RSA
 
message = "0011547896523KE2018-08-09".encode('utf-8')
digest = SHA256.new()
digest.update(message)
 
private_key = False
with open("privatekey.pem", "r") as myfile:
    private_key = RSA.importKey(myfile.read())
 
signer = PKCS1_v1_5.new(private_key)
sigBytes = signer.sign(digest)
signBase64 = b64encode(sigBytes)
 
headers = {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer ipARkr578zcp2fYPiZpEL1cpG6qE',
    'signature': signBase64
}
 
params = {}
 
payload = {
    "countryCode": "KE",
    "accountId": "0011547896523",
    "date": "2018-08-09"
}
 
url = 'https://sandbox.jengahq.io/account-test/v3/accounts/accountbalance/query'
response = requests.post(url, headers=headers, params=params,
                         data=json.dumps(payload))
print(response.text)

And viola! You have done your first secure API request

Account Alerts Your First API Call