Digest Authentication

The Digest method provides replay protection as well as authentication. A Digest auth header must contain the following properties: username, realm, nonce, uri, and response.

A Digest authentication header must contain the following properties:

Property Description
username This property must be set to your partnerId.
realm This property must be set to Users at all times. Note: the value is case sensitive.
nonce This property must be set to a nonce. A nonce is a unique random string. If a nonce is encountered more than once during a 15 minute period, the API call is rejected. It is your responsibility to ensure that the nonce is unique.
uri This property must be set to the API endpoint's URI; the following list outlines the appropriate value for each endpoint:
  • validate partner = /api/partner/validate
  • validate device = /api/v1/device/validate
  • process payload = /api/v1/decrypt/parser
Note: the value must be in lower case.
response The response value is an MD5 hash (in hexadecimal format) of the API call. The string to be hashed is composed of three sub-strings with a colon separating them. Two of the sub-strings are themselves hashed with MD5 before they are included in the final string to be hashed. The three sections are composed of the following elements:
  • sub-string 1: MD5 hash in hexadecimal format of the partnerId, realm, partnerKey separated with a colon.
  • sub-string 2: nonce in plain text.
  • sub-string 3: MD5 hash in hexadecimal format of the API call's method (always POST) and the uri value as set in the URI property above.
In pseudocode the hash is generated like this md5(md5(<partnerId>:<realm>:<partnerKey>): <nonce>: md5(<method>:<url>)))

Build a Digest Authentication Header

  1. Build the first part of the string to hash for the response property.
    md5( partnerId:realm:partnerKey )
md5(WATERFORD:Users:ef1ad938150fb15a1384b883a104ce70)
  1. Build the second part of the string by generating a nonce:
c5rcvu346qavqf3hnmsrnqj5up
  1. Build the third part of the string to hash for the response property. md5( method:url ):
md5(POST:/api/partner/validate)
  1. Concatenate the three parts together and MD5 hash it. md5(part1:nonce:part3):
md5(e77afc7cdfdea4a19535b78e4b4658db:c5rcvu346qavqf3hnmsrnqj5up:aa9ddafb9fe7a76649748c6cecd8e264)
  1. Build the Digest authentication header:
Authorization: Digest username="WATERFORD",
                realm="Users",
        nonce="c5rcvu346qavqf3hnmsrnqj5up",
        uri="/api/partner/validate",
        response="57c8d9f11ec7a2f1ab13c5e166b2c505"

Example

The following example is for demonstration purposes only. If you try the cURL command, you will receive an authentication required error message.

curl 'https://secure-cert.decryptx.com/api/partner/validate' \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'authorization: Digest username="WATERFORD", realm="Users", nonce="c5rcvu346qavqf3hnmsrnqj5up", uri="/api/partner/validate", response="57c8d9f11ec7a2f1ab13c5e166b2c505"' \
    -d '{
            "reference"  : "723f57e1-e9c8-48cb-81d9-547ad2b76435"
        }'

Did this page help you?