pdfSignature

Digital signature handler — ISO 32000-2 §12.8 + ISO TS 32001 (CAdES) + ISO TS 32002 (Ed25519).

Module pdfSignature | Source packages/front/office/pdf/src/sig/signature.js | Deps pdfErrors, pdfParser, pdfSigOids, asn1, rsa, ecc, ed25519, sha256, sha384, sha512, bitArray | Worker-safe yes

Typing and end-to-end verification of PDF signatures (detached PKCS#7/CMS). Supported SubFilters: adbe.pkcs7.detached, adbe.pkcs7.sha1 (legacy), ETSI.CAdES.detached, ETSI.RFC3161 (timestamp only), plus Ed25519 (ISO TS 32002). verifySignature reconstructs the /ByteRange-covered bytes, recomputes the digest, locates the signer's certificate inside the embedded PKCS#7 SignedData, and does dispatch and execute the public-key check itself (rsa.pssVerify / ECDSA / ed25519.verify via the internal verifyPk dispatcher) — see § Semantics of verified vs valid vs pkVerified below. The result's valid field is a deprecated alias of verified: read verified.

Resolve

const sig = runtime.resolve('pdfSignature');
// Returns: { typeSignature, verifySignature, verifyAllSignatures, verifyPk,
//            locatePkcs7, DIGEST_OIDS, SIG_OIDS }

API

DIGEST_OIDS and SIG_OIDS (constants, re-exported from pdfSigOids) are also returned for callers that need to map OIDs to algorithm names directly.

The factory also returns five internal helpers with a leading underscore (_hashByteRange, _scanSignatureObjects, _verifyPkcs7Signature, _verifyTsaSignature, _ecdsaSigToRaw) — exposed for internal reuse/testing, not part of the stable public contract; prefer the methods above.

Shape Signature

{
    kind: 'Sig' | 'DocTimeStamp',
    filter, subFilter, contents: Uint8Array,
    byteRange: [start1, len1, start2, len2],
    reference, cert, name, m, location, reason, contactInfo,
    v, propBuild, propAuthTime, propAuthType,
    raw   // the source dict
}

Examples

Semantics of verified vs valid vs pkVerified

verifySignature(...) returns:

{
    verified:    true,           // public-key check executed AND succeeded
    valid:       true,           // deprecated alias of verified
    pkVerified:  true,           // explicit strict-crypto boolean
    errors:      [ /* { code, message, context?, cause? } */ ],
    signerCerts: [ /* { der } */ ],
    hashAlg:     'sha256' | 'sha384' | 'sha512' | null,
    signatureAlg:'rsa' | 'rsa-pss' | 'ecc' | 'ed25519' | null,
    computedDigest: Uint8Array | null   // digest recomputed over /ByteRange
}

valid is a deprecated alias of verified: it always carries the same value, is kept for compatibility, and will be removed in a future major version. Read verified. The same holds for the valid field of each verifyAllSignatures entry, signatures and document timestamps alike.

verified / pkVerified are true only when the public-key check (verifyPk, dispatched internally) actually ran and succeeded against the signer's certificate SPKI. There is no pdf/sig/pk-verify-not-wired code in this module — the public-key verification path is wired by construction; a failed check surfaces a specific errors[] record instead (e.g. pdf/sig/pk-verify-failed, pdf/sig/rsa-pkcs1v15-deprecated for the deliberately-refused legacy scheme).

Structural verification + digest

const sig = runtime.resolve('pdfSignature');
const typed = sig.typeSignature(sigFieldDict.v);
const result = sig.verifySignature(typed, documentBytes, fwBundle);
result.verified;                 // true when the PK check passed
result.computedDigest;           // Uint8Array — /ByteRange digest
result.pkVerified;                // strict-crypto boolean, same as `verified`

Multi-signature + timestamp scan

const sig = runtime.resolve('pdfSignature');
const { signatures, timestamps } = sig.verifyAllSignatures(documentBytes, fwBundle);
signatures.every((s) => s.verified);
timestamps.every((t) => t.verified);

Each timestamps[] entry (TsVerifyResult) has this shape:

{
    objNum, objGen,                 // the /DocTimeStamp object
    verified:        true,          // imprint matches AND the gap is exact
    valid:           true,          // deprecated alias of verified
    kind:            'DocTimeStamp',
    subFilter:       'ETSI.RFC3161' | string | null,
    hashAlg:         'sha256' | 'sha384' | 'sha512' | string | null,
    tstInfo:         { hashAlg, imprint, rawSd } | null,
    imprintVerified: true,          // messageImprint == /ByteRange digest (imprint outcome alone)
    tsaVerified:     false,         // TSA signature check — informational
    gapForm:         'token' | 'digits' | null,
    errors:          [ /* { code, message, context?, cause? } */ ],
    signerCerts:     [ /* the TSA signer certificates, when located */ ]
}

gapForm names the accepted /ByteRange gap form, in the vocabulary of pdfByteRange.auditByteRange: 'token' when the gap is exactly the whole <…> token of the /Contents value, 'digits' when it is exactly its hex digits, null for any other gap. It is present on every entry, failure paths included. A non-exact gap adds a pdf/sig/byterange/gap-start-mismatch / gap-end-mismatch record to errors[] and leaves verified: false even when imprintVerified is true; the earlier pdf/ts/* failures keep their first error code. signatures[] entries carry objNum / objGen plus the verifySignature result shape above, with no gapForm key.

Inspecting the decoded CMS

const sd = sig.locatePkcs7(typed.contents);
// sd is the parsed SignedData children array (ASN.1 nodes), or `false`.

Errors

See also

• pdfByteRange · pdfTimestamp · pdfCertChain
• pdfSignatureField