HTTP Message Signatures - Staking API

Learn how to verify staking integration API HTTP signatures.

The Blockdaemon Staking API provides HTTP Signatures that can verify the response body wasn't transformed (e.g., by intermediaries).

These signatures are created and verified according to the HTTP Message Signatures IETF RFC Draft.

Verification process

➡️ Step 1. Get the Blockdaemon public key from your account TAM and save it as a file named publickey.pem.

➡️ Step 2. Parse the signature headers, extract and save the signature base inputs from the request you want to validate.

signature: the base64 text between sig=: and :.
- This header contains the generated signatures.
signature-input: the text after sig=.
- This header contains the metadata for the generated signatures.
content-digest: the hash between sha-256=: and :.
- This is the SHA-256 digest of the response body. You can generate this value yourself or use the header value.

➡️ Step 3. Re-create the signature base text:

"content-digest": sha-256=:<the parsed content-digest value>:
"@signature-params": "<the parsed Signature-Input value>"

The text must match the examples exactly (no extra spaces, newlines, etc.).

➡️ Step 4. Save the parsed signature header value in a file named sigbase. This file should be digested with SHA-256 and saved into a new one called data. e.g.:

openssl dgst -sha256 sigbase |  awk '{printf $2}' > data

➡️ Step 5. Verify that the signature is valid for the given data and public key. The output should be Verified OK, if not, do not use the response body returned by and contact Blockdaemon.

openssl dgst -sha256 -verify publickey.pem -signature sig data

Bash script

If you prefer, use the Bash script below, updating the environment variables with the Blockdaemon public key and response header values. Save it as verify.sh, enable the execution with chmod +x verify.sh, and execute with ./verify.sh.

#!/usr/bin/env bash

# Verify the signature using openssl.
# Make sure to fill PUBLIC_KEY, SIGNATURE, SIGNATURE_INPUT and CONTENT_DIGEST values.
# Example:
# PUBLIC_KEY="-----BEGIN PUBLIC KEY-----
# MIGbMBAGByqGSM49AgEGBSuBBAAjA4GGAAQB0tD6ueoq+mlHePffuT5kXjUjW06v
# 6Gd135jhxsLkKlI3mhaJfiFwSmRdOrAhBm+XG8KAJPkq5ZBC6v7DNSjyAVoA279e
# P0s7fx+ocYyZ5Tm/RxrtbuJ0gvtAGEyQi8aK/9Olq2whgWfbTMyOU3NQaA5wayaA
# /fbxkigyed/M2gXNfIQ=
# -----END PUBLIC KEY-----"
# SIGNATURE="sig=:MIGHAkE4t9pn8QdIQPC45b7zgS3lhU10bPYgd61nC9/wsXIbisJDZw0DquQ+tRLh+MQ6ZzL0fdtytdjiAyqxVwkFMG7T0AJCASkzk1iSqr7uW8bA6elF+tezoHPsojTwvMpqrJ9bBeAeMp1K6ku7NbII1uggsDDL/+uW3IHnuWI0oXcFqFPm5MUb:"
# SIGNATURE_INPUT="sig=(\"content-digest\");created=1692792689;keyid=\"blockdaemon-ecdsa-p521\""
# CONTENT_DIGEST="2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

# Public key
PUBLIC_KEY=""
# signature request header value
SIGNATURE=""
# signature-input request header value
SIGNATURE_INPUT=""
# content-digest header value/SHA-256 hash of the response body
CONTENT_DIGEST=""

# Remove label from signature and signature input
SIGNATURE=${SIGNATURE#*:}
SIGNATURE=${SIGNATURE%:}
SIGNATURE_INPUT=${SIGNATURE_INPUT#*=}

# Create files
echo "$PUBLIC_KEY" > publickey.pem
echo "$SIGNATURE" | base64 -d > sig

# Define signature base
SIGNATURE_BASE="\"content-digest\": sha-256=:${CONTENT_DIGEST}:
\"@signature-params\": ${SIGNATURE_INPUT}"
printf "%s" "$SIGNATURE_BASE" > sigbase
openssl dgst -sha256 sigbase |  awk '{printf $2}' > data

# Verify signature
echo "Verifying signature using openssl..."
openssl dgst -sha256 -verify publickey.pem -signature sig data

Verification process

Bash script

👋 Need Help?