Message Signature

To generate a message signature, cryptographic keys of the ED25519 variants must first be created.

We currently only support ED25519 key types.

Determine Signature Base

The example signature base below is determined from the content digest example request.

"Authorization": Bearer 123
"Content-Digest": sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
"Content-Length": 18
"Content-Type": application/json
"X-Client-Id": 123456
"X-Idempotency-Key": 123456
"@method": POST
"@target-uri": https://api.pipevest.com
"@path": /v1/customers
"@query: ?sort=ASC
"@signature-params": ("Authorization" "Content-Digest" "Content-Length" "Content-Type" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584

Signature Parameters

The field @signature-params contains an ordered list of components that make up the signature base. It is made up of two sections, fields and meta data.

"@signature-params": (fields...);meta

fields: ordered, space ( ) separated and contained within ellipsis (...)
meta: unorder, semi-colon (;) separated and specify additional information about the cryptographic operation

The order in which the fields show up in the signature base must match the fields order in the signature params

Generate Message Signature

Retrieve Private Key

Identify the private key for the given environment. You should have one for:

Staging
Production

How to Generate Cryptographic keys

Determine Signature Base

Use the instructions here to determine which fields to include to generate the signature.

Calculate Signature

Using sha-512, hash the signature base
Sign the resulting hash with the environment specific private key.
Base64 encode the signed hash, this is the final computed message signature (computed-signature).

For the example request below, the computed-signature will be OTEyMjY4...A5NTNDMEQ=

Signature Input

The signature input is the same as the @signature-params and will be passed along the header. The inputs allow for the signature to be recomputed and verified.

Make Signed Request

Add Signature and Signature-Input to the request header

Signature: sig1=:<computed-signature>:
Signature-Input: sig1=<@signature-params>

  curl --request POST \
    --url https://api.pipevest.com/v1/customers?sort=ASC \
    --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
    --header 'Content-Length: 18' \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer 123456' \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    --header 'Signature-Input: sig1=("Content-Type" "Content-Digest" "Content-Length" "Authorization" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
    --header 'X-Client-Id: 123456' \
    --header 'X-Idempotency-Key: 123456' \
    ...
    --data '{"firstName": "John", "lastName": "Doe"}'

Verify Message Signature

Retrieve Public Key

Identify the public key for the given environment. You should have one for:

Staging
Production

For webhook message validation, refer to Step 1 in Validate Webhook Message

Recompute Message Signature

Use the Signature-Input from the http header to determine the signature base.
Create a sha-512 digest from the signature base

We will call this computed-message-signature.

Identify Header Signature

You will need to strip the sig1=: prefix and the : suffix to end up with the header-base64-signature.

In the example below, the header-message-signature equals OTEyMjY4...A5NTNDMEQ=

  curl --request POST \
    --url https://api.pipevest.com/v1/customers \
    --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
    ....

Decode Signature

Using a base64 decoder, decode the header-base64-signature.

We will call this final result, the header-message-signature.

Compare Signatures

Compare the computed-message-signature to the header-message-signature.

  computed-message-signature === header-message-signature

Verify or Reject

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

Example Verification Code:

import crypto from 'node:crypto'

// Get the Public key
const publicKey = ...

// Get Signature and Signature inputs from the original http message header
const signature = request.headers['Signature']
const signatureInput = request.headers['Signature-Input']

// Recompute message signature using the signature inputs
const computedSignatureBase = `...` // determined using `signatureInput`
const computedMessageSignature = crypto.createHash('sha512').update(computedSignatureBase).digest()

// Decode the signature to get the signed http message
const headerBase64Signature = signature.match(/:(.*):/).pop()
const headerMessageSignature = Buffer.from(headerBase64Signature, 'base64')

// Use public key to verify that computed and header signatures are the same
const isSignatureVerified = crypto.verify(null, computedMessageSignature, publicKey, headerMessageSignature)

import crypto from 'node:crypto'

// Get the Public key
const publicKey = ...

// Get Signature and Signature inputs from the original http message header
const signature = request.headers['Signature']
const signatureInput = request.headers['Signature-Input']

// Recompute message signature using the signature inputs
const computedSignatureBase = `...` // determined using `signatureInput`
const computedMessageSignature = crypto.createHash('sha512').update(computedSignatureBase).digest()

// Decode the signature to get the signed http message
const headerBase64Signature = signature.match(/:(.*):/).pop()
const headerMessageSignature = Buffer.from(headerBase64Signature, 'base64')

// Use public key to verify that computed and header signatures are the same
const isSignatureVerified = crypto.verify(null, computedMessageSignature, publicKey, headerMessageSignature)

  import hashlib
  import re

  # Get the Public key
  public_key = ...

  # Get Signature and Signature inputs from the original http message header
  signature = request.headers.get("Signature", "")
  signature_input = request.headers.get("Signature-Input", "")

  # Recompute message signature using the signature inputs
  computed_signature_base = `...` # determined using `signature_input`
  computed_message_signature = hashlib.sha512().update(computed_signature_base)

  # Decode the header signature to get the signed http message
  header_base64_signature = re.search(r'\:(.*)\:', signature).group(1)
  header_message_signature = base64.b64decode(header_base64_signature)

  # Use public key to verify that computed and header signatures are the same
  is_signature_verified = ... # use `public_key` to make this determination

Fields

Fields	Request Types	Required	Note
`Content-Type`	`POST`, `PUT`, `PATCH`	Yes
`Content-Digest`	`POST`, `PUT`, `PATCH`	Yes
`Content-Length`	`POST`, `PUT`, `PATCH`	Yes
`Authorization`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	Yes	Not required for `/auth`
`X-Client-Id`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	Yes	Not required for `/auth`
`X-Idempotency-Key`	`POST`, `PUT`, `PATCH`, `DELETE`	Yes
`@method`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	Yes
`@target-uri`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	Yes
`@path`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	Yes
`@query`	`GET`, `DELETE`	Yes
`@signature-params`	`GET`, `POST`, `PUT`, `PATCH`, `DELETE`	Yes

Name	Description	Required	Note
`keyid`	This is the id of the public key sent over to pipevest.	Yes	ex: `staging-pipevest-ed25519`
`created`	The unix time when the cryptographic operation took place	Yes
`expires`	Unit time stamp that represents `created + 100 ms`	No	Not needed, but recommended

Welcome

Concepts

Determine Signature Base

Signature Parameters

Generate Message Signature

Verify Message Signature

Example Verification Code:

Fields

Meta

Welcome

Concepts

​Determine Signature Base

​Signature Parameters

​Generate Message Signature

​Verify Message Signature

​Example Verification Code:

​Fields

​Meta

Determine Signature Base

Signature Parameters

Generate Message Signature

Verify Message Signature

Example Verification Code:

Fields

Meta