Skip to content

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: true signs the data directly with no signed attributes; false includes signed attributes (contentType, signingTime, messageDigest, algorithm-protection)
  • cmsencapsulate: true embeds the content in the structure; false produces 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.