Skip to content

How-To: Verify a Signature

Check a Keyserver signature with OpenSSL before you publish an artifact, or on a test bench that mimics the device's verifier. You fetch the key's certificate, validate its chain to the ROOT certificate, and verify the signature against the original file.

Prerequisites

  • An access token in KSC_ID_TOKEN, obtained as in Step 1: Authenticate and Obtain an OAuth Token of the Authenticode guide. The token's subject needs a role granting getkeys on the signing key and, for the chain check, on its ROOT key.
  • The signing key's ID, its ROOT key's ID, and its Hash algorithm, shown when the key is opened on the Keys page. See Create and Manage Keys in the Keyserver.
  • The signed file, and the sign order's result, signatureformat and inputformat
  • curl, jq, openssl and xxd (xxd ships with vim, or vim-common on minimal images)
  • For p1363 signatures only: Python 3 with the asn1crypto package (pip install asn1crypto)

Set the server URLs and the hash option that matches the key's Hash algorithm (-sha256, -sha384 or -sha512). Set them before you request the token: the token request uses AUTHSERVER.

export KSC_API_SERVER=https://keyserver.<UNIQUE-ID>.cryptera-security.io
export AUTHSERVER=https://authserver.<UNIQUE-ID>.cryptera-security.io/oauth2/token
export HASH_ALG="-sha256"

Step 1: Get the key's certificate and public key

curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
  "$KSC_API_SERVER/api/keys/<KEYID>" | jq -r .certificate > certificate.pem

openssl x509 -in certificate.pem -noout -subject
openssl x509 -pubkey -noout -in certificate.pem > pubkey.pem

Expected output: a subject= line with the Distinguished Name set when the key was created, for example subject=CN = fw-quickstart, ... (OpenSSL 3.2 and newer omit the spaces around =).

Step 2: Get the ROOT certificate

GET /api/keys/{keyid} returns only that key's certificate, so fetch the ROOT key's certificate separately:

curl -sS --tlsv1.3 -H "Authorization: Bearer $KSC_ID_TOKEN" \
  "$KSC_API_SERVER/api/keys/<ROOT KEYID>" | jq -r .certificate > root-certificate.pem

openssl x509 -in certificate.pem -noout -issuer
openssl x509 -in root-certificate.pem -noout -subject

Expected output: the leaf's issuer= line matches the root's subject= line.

Step 3: Verify the certificate chain

openssl verify -CAfile root-certificate.pem certificate.pem

Expected output:

certificate.pem: OK

An FW key created under a ROOT key chains to it directly. For a chain with an intermediate certificate, pass it with -untrusted, as for device certificates in Step 11: Inspect and Verify the Certificate of the device certificate tutorial:

openssl verify -CAfile root.crt -untrusted intermediate.crt device.crt

Certificates the Keyserver issues for FW keys carry no X.509 extensions. See What to expect from a Keyserver-generated certificate. openssl verify -x509_strict rejects them with "Missing Authority Key Identifier"; the default verification above accepts them.

Before you verify the signature, confirm:

Check Must be If it is not
subject= from Step 1 The key that signed the file Fetch the right key's certificate
openssl verify certificate.pem: OK Do not trust pubkey.pem; see If something fails

Step 4: Convert the signature to binary

The decoding depends on the sign order's signatureformat. See Signature Formats. Put the result field in RESULT. It is hex when the sign order used inputformat: hex, and base64 when it used inputformat: base64. See Result encoding. Then follow the one subsection below that matches your signatureformat: asn1, p1363 or cms.

asn1

ECDSA DER r,s, or RSA PKCS#1 v1.5. Decode it as is.

printf '%s' "$RESULT" | xxd -r -p > sig.der

For a base64 result, use printf '%s' "$RESULT" | base64 -d > sig.der instead.

p1363

ECDSA raw r‖s. OpenSSL cannot read it directly. Convert it to DER with asn1crypto, using the method in Signature Formats:

python3 - "$RESULT" <<'EOF'
import sys
from asn1crypto.algos import DSASignature
result_hex = sys.argv[1]
der = DSASignature.from_p1363(bytes.fromhex(result_hex)).dump()
open("sig.der", "wb").write(der)
EOF

For a base64 result, convert it to hex before you run the conversion above: RESULT=$(printf '%s' "$RESULT" | base64 -d | xxd -p | tr -d '\n').

A device verifier that takes raw r‖s uses the p1363 bytes without conversion.

cms

Skip the rest of this step and Step 5. Verify with openssl cms -verify using the recipe for your combination in Which CMS combination to use?.

Step 5: Verify the signature

OpenSSL hashes the file with $HASH_ALG and checks the signature against that digest:

openssl dgst $HASH_ALG -verify pubkey.pem -signature sig.der firmware.bin

Expected output:

Verified OK

The command is the same for ECDSA and RSA keys. The digest must be made with the key's hash algorithm; how a mismatch behaves on RSA and ECDSA keys is in Hash algorithm.

Tool-specific signatures

Signatures embedded by a signing tool are verified with that tool:

Operational practices

  • Keep the certificate with the release. A revoked key returns 410 on GET /api/keys/{keyid}, so store certificate.pem and root-certificate.pem when you sign if you need to verify old artifacts later.
  • Fail the build on anything but Verified OK. A sign order with the wrong hash algorithm still returns a signature.

If something fails

Symptom Cause and fix
401 "The user/client is not valid" The token's client ID does not match a registered subject
403 fetching a certificate The subject's role has no getkeys on that key; the ROOT key needs its own grant
404 fetching a certificate The key ID is misspelled or does not exist
409 "Signing key is not initialized!" The key is not INITIALIZED yet. Wait, then fetch again
410 "Signing key has been revoked" The key is revoked and its certificate can no longer be fetched. Use the copy stored at signing time
certificate.pem is empty or contains null The request failed. Re-run curl with --fail-with-body to see the error
openssl verify prints unable to get local issuer certificate root-certificate.pem is not the leaf's issuer (compare Step 2), or an intermediate is missing from -untrusted
openssl verify -x509_strict reports "Missing Authority Key Identifier" Expected for Keyserver FW certificates (Step 3)
Verification failure in Step 5 The file changed after signing, pubkey.pem is from another key, $HASH_ALG does not match the hash the signer used, or the result was decoded with the wrong encoding or format
Verification failure on an RSA key where the signer submitted a bare hash with inputpadding: digestinfo digestinfo means the input is already DigestInfo-wrapped. Sign again with inputpadding: none (asn1)
python3 reports No module named 'asn1crypto' Install it with pip install asn1crypto

Full status-code reference: Error Codes.