Signature Formats¶
The signatureformat field on POST /api/signorders sets the format of the returned signature. It is set per sign order, not per key, so choose the format the verifying side expects. The examples use OpenSSL 3.5.
Comparison¶
| Format | ECDSA keys | RSA keys | Verify with | Use when |
|---|---|---|---|---|
asn1 | DER SEQUENCE { INTEGER r, INTEGER s }, variable length (about 70–72 bytes on P-256) | Standard PKCS#1 v1.5 signature: a fixed-length block the size of the key, not DER-wrapped | openssl dgst -verify | The default for OpenSSL and most desktop and server tools |
p1363 | Fixed-width r‖s concatenation (64 bytes on P-256) | Refused with 400 | Embedded verifiers directly; convert to DER for OpenSSL | Embedded and hardware verifiers, IEEE P1363-style APIs |
cms | CMS/PKCS#7 SignedData (DER) | CMS/PKCS#7 SignedData (DER) | openssl cms -verify | Toolchains that require CMS |
pem | Same output as asn1 | Same output as asn1 | As asn1 | Do not use |
pem is not a distinct format
signatureformat: pem passes validation but returns the same payload as asn1, with no PEM armor, and the response still reports signatureformat: pem. inputformat: pem also passes validation but has no decoder behind it. Use asn1, and hex or base64 for the input. Later releases reject both.
asn1¶
For ECDSA keys, the signature is a DER SEQUENCE of r and s. For RSA keys, it is a standard PKCS#1 v1.5 signature; asn1 is only the name of the format. The Keyserver wraps the submitted RSA hash in a PKCS#1 DigestInfo unless the sign order sets inputpadding: digestinfo, which means the input is already wrapped. The DigestInfo the Keyserver builds names the key's hash algorithm. A DigestInfo you build is signed as submitted, even if it names another hash algorithm than the key's.
Verify a hex-encoded result with OpenSSL (xxd ships with vim):
printf '%s' "$RESULT" | xxd -r -p > sig.der
openssl dgst -sha256 -verify pubkey.pem -signature sig.der firmware.bin
p1363¶
ECDSA only. The signature is the raw, fixed-width concatenation of r and s. A sign order with p1363 on an RSA key returns 400 "Signature format p1363 is only allowed for ECDSA signing keys".
OpenSSL cannot read this form directly. Convert it to DER first, for example with the Python asn1crypto package, then verify as for asn1:
from asn1crypto.algos import DSASignature
der = DSASignature.from_p1363(bytes.fromhex(result_hex)).dump()
open("sig.der", "wb").write(der)
cms¶
A CMS/PKCS#7 SignedData container (DER). Three booleans on the sign order shape it. All three are required with cms and refused with any other format (400):
cmsincludecert: embed the signing certificate (leaf only, no chain)cmsdirectsignature:truesigns the data directly with no signed attributes;falseincludes signed attributes (contentType,signingTime,messageDigest, algorithm-protection)cmsencapsulate:trueembeds the content in the structure;falseproduces a detached signature
Which CMS combination to use?¶
Use cmsincludecert=true, cmsdirectsignature=false, cmsencapsulate=false: detached, with signed attributes. The Keyserver signs a client-submitted hash, not the file, and this is the only combination that verifies against the original file:
openssl cms -verify -binary -inform DER -in sig.der \
-content firmware.bin -CAfile root-cert.pem -out /dev/null
It verifies because the messageDigest signed attribute equals the submitted hash, which is the file's digest, so OpenSSL's own recomputation matches. To check the signature without validating the certificate chain, use -noverify in place of -CAfile root-cert.pem.
The other three combinations behave differently:
| Combination | Behavior |
|---|---|
cmsdirectsignature=true, detached | The signature covers the key's hash algorithm applied to the submitted hash (a second hash). It verifies only with the raw digest as content: -content hash.bin, where hash.bin holds the raw bytes of the submitted hash, not the original file. |
cmsdirectsignature=true, encapsulated | Verifies with plain openssl cms -verify (no -content), but the recovered content is the submitted digest, not the file. The verifier must compare it against the file's hash. |
cmsdirectsignature=false, encapsulated | Produces a CMS structure that standard verifiers, including OpenSSL, reject as inconsistent. Do not use this combination. |
Result encoding¶
The result field's encoding follows the sign order's inputformat: hex in, hex out; base64 in, base64 out. The API reference describes result as hex in every case; base64 input returns base64.
Related pages¶
- Production Notes: Sign Code Using the REST API: production practices for sign orders
- Error Codes Reference: the
400validation errors for sign orders - Verify a Signature: decoding and verifying each format with OpenSSL