API Authentication

All API calls will require authentication. HMAC is a more secure solution, but it can be faster to get started on basic authentication, however, for production use, we require HMAC authentication be used. This is the same as Decryptx.

Basic Authentication

Our Basic authentication method requires that you place the partnerId and partnerKey in the authentication header.

Build a Basic Authentication Header

1. Concatenate your partnerId and partnerKey with a colon(:) separator.

WATERFORD:ef1ad938150fb15a1384b883a104ce70

2. Base64 encode the string.

base64Encode('WATERFORD:ef1ad938150fb15a1384b883a104ce70')

//output V0FURVJGT1JEOmVmMWFkOTM4MTUwZmIxNWExMzg0Yjg4M2ExMDRjZTcw

3. Build the Basic Auth Header.

authorization: Basic V0FURVJGT1JEOmVmMWFkOTM4MTUwZmIxNWExMzg0Yjg4M2ExMDRjZTcw

Example

curl 'https://secure-cert.shieldconex.com/api/template/validate' \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'authorization: Basic V0FURVJGT1JEOmVmMWFkOTM4MTUwZmIxNWExMzg0Yjg4M2ExMDRjZTcw' \
    -d '{
            "reference"  : "723f57e1-e9c8-48cb-81d9-547ad2b76435"
        }'

HMAC Authentication

The hash-based message authentication code (HMAC) method provides replay protection, time-to-live, and request integrity. Our implementation requires that you use the sha-256 and hmac-sha-256 hashing algorithms. Before you can implement this auth method, you must ensure that you have a shared key. If you were not given a shared key when you registered, please request one from Bluefin Support.

An HMAC authentication header must contain the following properties:

Building an HMAC Authentication Header

1. Generate a nonce

var nonce = crypto.lib.WordArray.random(32);
//nonce: 90ec4cff53d4094e683a4424cffadf8c539e9fb8c9a0c569c3f8002856e93f9a

2. Generate a unix timestamp

var timestamp = Math.round(new Date().getTime()/1000)
//timestamp: 1726097361

(int) (System.currentTimeMillis() / 1000L)
//output 1489574949

3. Generate the content hash by SHA-256 hashing the request body.

\n represents a newline character and \t represents a tab character.

sha-256({"partnerId":"WATERFORD","partnerKey":"ef1ad938150fb15a1384b883a104ce70","templateRef":"generic_template","reference":"723f57e1-e9c8-48cb-81d9-547ad2b76435s"})

//output 9db4a2e377abca97c72c5d8b449948d3fb22fa18f305c3730f227e4f6514d4ce

4. Build the String-to-Hash.

When creating the String-to-Hash, it is important that you follow the format described exactly as outlined below, otherwise the request will be rejected. The String-to-Hash is composed of the following elements.

The String-to-Hash is composed of these elements gathered together in this exact format. Once you have the String-to-Hash, you pass it into the HMAC-SHA256 hashing algorithm to generate the HMAC authentication header's response property.

var hash = HttpVerb + " " + CanonicalizedResource + "\n" + nonce + "\n" + timestamp
  + "\n" + "\n" + ContentHash;

For our example the String-to-Hash is:

"POST /api/authdebug
1l5daa1ju1b7lmljc5p4nev0ve
1489574949

9db4a2e377abca97c72c5d8b449948d3fb22fa18f305c3730f227e4f6514d4ce"

5. HMAC-SHA256 hash the String-to-Hash with the secret key:

Hex( HMAC-SHA256( 'ef1ad938150fb15a1384b883a104ce70',
                 "POST /api/authdebug\n1l5daa1ju1b7lmljc5p4nev0ve\n1489574949\n\n9db4a2e377abca97c72c5d8b449948d3fb22fa18f305c3730f227e4f6514d4ce" ) )

//output 7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac

6. Build the Digest authentication header:

Authorization: Hmac username="WATERFORD", nonce="1l5daa1ju1b7lmljc5p4nev0ve",  timestamp=1489574949, response="7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac"

Example:
The following example is for demonstration purposes only. The WATERFORD user is not configured for HMAC authentication and the header's timestamp is out of date; if you try the cURL command, you will receive an authentication required error message.

curl 'https://secure-cert.shieldconex.com/api/template/validate' \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'authorization: Hmac username="WATERFORD", nonce="1l5daa1ju1b7lmljc5p4nev0ve",  timestamp=1489574949, response="7fd904ec88c5dc9217e178bc8e115b950c243197b5116e3e1fc43061eeb846ac"' \
    -d '{
            "reference"  : "723f57e1-e9c8-48cb-81d9-547ad2b76435"
        }'

RSA Authentication

Generate RSA Key Pair

The following section outlines the steps involved in generating an RSA key pair with OpenSSL. We recommend that you generate a 2048 bit key pair as 1024 bit keys are no longer considered secure and 4096 bit keys consume considerable CPU resources when signing API calls.

1. Generate a 2048-bit RSA private key and write it to a file private.pem.

#Output an RSA private key with 2048 bit protection.
openssl genrsa -out private.pem 2048

2. Generate a PKCS8 formatted file from the private key and write it to file private8.pem. The private8.pem file must be used in the RSA-DIGEST function to sign the requests.

#Generate a pk8 file from the private key.
openssl pkcs8 -topk8 -inform PEM -outform PEM -nocrypt -in private.pem -out private8.pem

3. Generate the public key file from the private key and write it to a file public.pem.

#Generate a public key from the private key.
openssl rsa -in private.pem -outform PEM -pubout -out public.pem

Authentication Header Guide

The RSA authentication method is almost identical to HMAC. The only difference is that it uses an RSA private key to sign the String-to-Hash and a RSA public key to validate that the signature is valid. RSA keys provide a more secure way of signing your auth headers than using a password. While a password can eventually be cracked with a brute force attack, RSA keys are nearly impossible to decipher by brute force alone. The downside of using RSA to sign API calls, is that RSA signatures require a lot more CPU resources (up to ~250 times) than HMAC hashing.

Our Generating an RSA key pair guide outlines how you can create a public and a private key. You must send the public key to Bluefin, and keep the private key on your server.

Next Steps

Once you're set up to add authentication to your headers, iFrame users will probably want to move along to iFrame Tokenization. For those of you that plan to tokenize with the API move along to API Tokenization.