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 grantinggetkeyson 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,signatureformatandinputformat curl,jq,opensslandxxd(xxdships with vim, orvim-commonon minimal images)- For
p1363signatures only: Python 3 with theasn1cryptopackage (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¶
Expected output:
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:
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.
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:
Expected output:
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:
- JAR files:
jarsigner -verify, as in Step 8: Verify the JAR of the JAR signing guide - Windows executables:
osslsigncode verify, as in Step 8: Verify the Signature of the Authenticode guide - Container images:
cosign verify, as in Step 7: Verify of the Cosign guide
Operational practices¶
- Keep the certificate with the release. A revoked key returns
410onGET /api/keys/{keyid}, so storecertificate.pemandroot-certificate.pemwhen 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.
Related pages¶
- Tutorial Part 2: Sign Code Using the Trial Environment: the REST signing flow that produces the signature verified here
- Use OpenSSL 3.x with PKCS#11 for Signing: signatures made through
libpkcs11ks, with the certificate read over PKCS#11