Bluefin's Developer Portal

Authentication

This article introduces the different API authentication methods used in Decryptx API library and the security protection against replay attacks, time-to-live, request for integrity, and private key.

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 authentication header.

Digest, HMAC and RSA

The Digest, HMAC, and RSA methods pass the partnerId in the authorization 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 for integrity, and private key.

Replay Attacks

Digest, HMAC, and RSA provide protection against replay attacks by requiring that a nonce be included in the authorization 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 GUID or UUID. A UUID (Universal Unique Identifier) is a 128-bit number used as a unique identifier. Most programming languages will have a core function/method that generates UUIDs.

A nonce is an arbitrary string that may only be used once. It also can't be altered since it is also 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 authorization 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, therefore it cannot be altered in transit.

If you decide to adopt an auth mechanism that has time-to-live protect you need to ensure that your server is 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 timezone independent; Unix time is the number of seconds that have elapsed since January 1, 1970 (midnight UTC/GMT). 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 authorization 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 auth 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 RSA algorithm requires a lot more CPU resources than HMAC. The HMAC SHA-256 hashing algorithm is ~250 times faster than RSA 2048 bit signing.

The following table outlines our supported Auth methods and the protections that each provide.

TypeAuth.Replay ProtectionTime-to-liveRequest IntegrityPrivate Key
Transparentyesnononono
Basicyesnononono
Digestyesyesnonono
HMACyesyesyesyesno
RSAyesyesyesyesyes

Integration Guides

We have a number of guides that describe how you can adopt each of the auth methods into your software. Where appropriate, the guides describe the parameters to include in the authentication header and how to construct the parameters. 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"
  1. 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.

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

  3. 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.

Updated 16 days ago



Authentication


This article introduces the different API authentication methods used in Decryptx API library and the security protection against replay attacks, time-to-live, request for integrity, and private key.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.