Authentication

All API calls to the Decryptx Parser require authentication. Our endpoints support the following authentication methods:

Transparent

The transparent method requires that you include the partnerId and partnerKey in the body of the request. This is implemented separately for each API, so you can find details on the guide for each API call.

Basic

The basic method requires the partnerId and partnerKey in the auth header.

Digest, HMAC and RSA

The Digest, HMAC, and RSA methods pass the partnerId in the auth header, but they also embed a hash value in the header that is signed with either a SecretKey or an RSA private key.

Our authentication methods provide security protection against replay attacks, time-to-live, request integrity, and private key.

Replay Attacks

Digest, HMAC, and RSA provide protection against replay attacks by requiring that a nonce be included in the authentication header. If you opt to adopt an auth mechanism that protects against replay attacks, you need to ensure that your code is generating nonces that are unique over a 15 minute period. We recommend that you use a Globally Unique Identifier (GUID) or a Universal Unique Identifier (UUID). GUID's and UUIDGUIDs and UUIDs are both 128-bit numbers used as a unique identifiers. and are generally interchangeable. The key difference is that the GUID is a Microsoft-specific standard. Most programming languages will have a core function/method that generates GUIDs or GUIDs or UUIDs.

A nonce is an arbitrary string that may only be used once. It can't be altered since it is contained in a string that is signed/hashes. If the nonce is altered in transit (man-in-the-middle attack) the signature/hash will no longer be valid and the API call will be rejected. Our service keeps a record of these nonces; an API call is rejected if a nonce is encountered more than once over a 15 minute period

Time-to-live

The HMAC and RSA methods provide time-to-live protection, by requiring the API caller to include a Unix timestamp in the authentication header. Our service will reject API calls that are older than 15 minutes. Again, in both the HMAC and RSA methods the timestamp is included in the hash/signature and therefore cannot be altered in transit.

If you decide to adopt an auth mechanism that has time-to-live protection, your server must be able to produce accurate timestamps. The best way to ensure that is to use the Network Time Protocol (NTP) with a trusted NTP server. Note: Unix time is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT) and it is timezone independent. Most programming languages provide utility methods/functions that convert between local time and Unix time.

Request Integrity

Request integrity protection is provided by the HMAC and RSA methods. Both HMAC and RSA require that the authentication header contain a hash/signature of HTTP request.

Our service reconstructs and validates the signature/hash using a shared key. The trade-off for adopting this increased protection is that it is difficult to construct the string to hash correctly.

📘

To help with integration we have created an Authentication Debug Endpoint to help with debugging.

Private Key

Only the RSA authentication method provides this additional protection. The requests are signed with the RSA private key and our service validates the signatures with the RSA public key. By using this method you do not have to share your private key with anyone. The downside of using RSA is that the RSA algorithm requires a lot more CPU resources than the HMAC. The HMAC SHA-256 hashing algorithm is ~250 times faster than RSA 2048 bit signing.

The following table outlines our supported authentication methods and the protections that each provides.

Integration Guides

We have a number of guides that describe how to adopt each of the authentication methods into your software. Where appropriate, the guides describe the parameters to include in the auth header and how to construct those. Before reading the guides you should note the following:

1. Some programming languages and software libraries output hexadecimal strings with the alphabet characters in upper case (e.g. E9C8), while others output them in lower case (e.g. e9c8). Typically this is not a problem when comparing them directly as they both can be converted to the same case before comparison. However, when generating the final hash for our auth header we incorporate another sha-256 hexadecimal hash. Our service expects you to convert the inner hash to lowercase before including it in the final hash. If it is upper case, the final hash will be different and the API call will be rejected.

2. The Digest, HMAC and RSA methods uses the following structure for their auth headers.

Authorization: <Method> <List of parameters in name="value" format>
    ////e.g. Authorization: Digest a="b", c="d", e="f"

3. If you opt to adopt an auth mechanism that protects against replay attacks then you need to ensure that your code is generating nonces that are unique over 15 minute period.

4. If you choose to adopt the HMAC or RSA auth methods, this will result in all API calls being rejected.

5. To enable the HMAC method, you must request your secret key from Bluefin Support. With the RSA method you must send us your public key.