Content Digest

The content digest signature that is used to validate the HTTP message content. A hashing algorithm is used to create a digest of the message body. With the algorithm you can then rehash the message body and validate it against the pre-computed content-digest.

Note

The content digest should only be computed for requests where message body is present

Generate Content Digest

Although sha-256 generated digests are considered secure, we recommend using sha-512.

Caution

Send exactly one algorithm. The header must be a single entry of the form sha-512=:<base64>: (or sha-256=:<base64>:). A comma-separated list of several digests, or any additional parameters, is rejected as malformed with 401 Content-Digest verification failed.

Compute Content Digest

Javascript

  import crypto from "crypto";

  // Define the algorithm
  let algorithm = "sha512";

  // Define the message
  let message = JSON.stringify({
    firstName: "John",
    ...
  });

  // Create the digest in base64 encoding
  const digestBase64 = crypto.createHash(algorithm).update(message).digest("base64");

  // Create content digest string
  const contentDigest = `sha-512=:${digestBase64}:`;

Python

  import base64
  import hashlib
  import json

  # Define the message (encode to bytes)
  message = json.dumps({
    "firstName": "John",
    ...
  }).encode("utf-8")

  # Create the sha-512 digest of the raw body
  digest = hashlib.sha512(message).digest()

  # Base64-encode the digest
  digest_base64 = base64.b64encode(digest).decode("ascii")

  # Create content digest string
  content_digest = f"sha-512=:{digest_base64}:"

Make Signed Request

In the below example request:

• sha-512: The algorithm used to hash the content message
• RK/0...abDg=: Base64 representation resulting from the hashed content message

  curl --request POST \
    --url https://api.pipevest.com/v1/customers?sort=ASC \
    --header 'Content-Type: application/json' \
    --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
    --header 'Content-Length: 18' \
    --header 'Authorization: Bearer 123456' \
    --header 'X-Client-Id: 123456' \
    --header 'X-Idempotency-Key: 123456' \
    ...
    --data '{"firstName": "John", "lastName": "Doe"}'

Verify Content Digest

Re-compute Content Digest

See Step 1 in Generate Content Digest

Note

We will call this computed-content-digest.

Compare Digests

Compare computed-content-digest to the one that was passed along in the original http header (i.e. - header-content-digest).

computed-content-digest === header-content-digest

Tip

In the example below, the header-content-digest equals RK/08...FabDg=

  curl --request POST \
    --url https://api.pipevest.com/v1/customers \
    --header 'Content-Digest: sha-512=:RK/08...FabDg=:' \
    ....

Verify or Reject

Reject the message, if computed-content-digest does not equal header-content-digest.