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: 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: 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 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 |
