Authentication

All API calls to the Decryptx Parser require authentication; our endpoints support Transparent, Basic, Digest, HMAC, and RSA authentication methods. To help you decide which one to use in your application we give an overview of each method below. Each of our Auth methods provide you a different level security and protection. As is the case with most security solutions, the methods with the more protection are also more complex and require increased effort to adopt.

The security protections provided by our auth methods can be broken into a number of categories, including: authentication, replay protection, time-to-live, request integrity, and key privacy. Not all of our auth methods provide all of these protections. The table below maps the protection to the auth method. The description and benefits are as follows:

  • Authentication: All our auth methods provide Authentication. However, not all of them use the same keys or mechanisms to provide authentication. The transparent method requires that you include the partnerId and partnerKey in the body of the request, whereas the basic auth requires that you include the same values in the auth header. 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.
  • Replay Protection: The Digest, HMAC and RSA auth methods provide protection against replay attacks. They do this by requiring that the authorization header includes a nonce. A nonce is an arbitrary string that may only be used once. 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. The nonce cannot be altered as 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. 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 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.
  • 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 opt 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 require that the authorization header includes a hash/signature of HTTP requests body with other properties. 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've 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.

Type Authentication Replay Protection Time-to-live Body Integrity Private Key
Transparent yes no no no no
Basic yes no no no no
Digest yes yes no no no
HMAC yes yes yes yes no
RSA yes yes yes yes yes


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 describes 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 isn't 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 authentication methods then all API calls that use transparent, basic, and digest auth methods will be 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.

Guides