pdfSign

PAdES signature generation (write side) — levels B / T / LT / LTA.

Module pdfSign | Source packages/front/office/pdf/src/sig/sign.js | Deps pdfErrors, pdfSigOids, pdfByteRange, pdfDssBuilder, pdfIncrementalWriter, pdfParser, asn1, rsa, ecc, ed25519, sha256, sha384, sha512, bitArray, pdfDocument, pdfSecurity, pdfStandardV4, pdfStandardV5, pdfStandardV6 | Worker-safe yes

Companion of pdfSignature (verify side). Produces a detached PKCS#7/CMS SignedData blob and embeds it into a signature dictionary whose /ByteRange covers the whole document minus the whole /Contents <…> token, delimiters included (ISO 32000-2 §12.8.3.3.1 — see pdfByteRange); _emitWithPlaceholder's contentsOffset / contentsLength still name the hex-digit span. Algorithms: RSA-PSS, ECDSA (P-256/P-384/P-521), Ed25519 — PKCS#1 v1.5 is deliberately refused (fw policy, NIST SP 800-131A Rev.2). ECDSA signature values are DER ECDSA-Sig-Value (RFC 3279 §2.2.3); Ed25519 always uses SHA-512 (RFC 8419 §3.1). Default subFilter is adbe.pkcs7.detached — a PAdES emitter MUST explicitly pass subFilter: 'ETSI.CAdES.detached'.

PAdES levels

Every level signs by incremental update (§7.5.6, non-destructive): the base bytes are kept verbatim and the signature object is appended through pdfIncrementalWriter. The update section therefore takes the form of the base's newest cross-reference section (classical table or cross-reference stream), and its /Root, /Info and /ID come from the newest-first merged trailer. The signature takes the first object number at or past the merged /Size, so an object held in an object stream is never overwritten. The fixed-width /ByteRange and /Contents placeholders are found inside the signature object from its own offset, and they are patched without changing the byte length. LT adds a second update: the DSS, plus the Catalog re-defined under its own number with /DSS. The Catalog is resolved through readDocument from the trailer /Root, wherever it lives, including inside an object stream. LTA adds a third update, the DocTimeStamp, appended the same way as the signature. A hybrid-reference base (a classical trailer carrying /XRefStm) is refused, and nothing is written.

The pdfParser dependency is no longer read. It keeps its position so that code calling the factory with positional arguments still works. pdfDocument comes next. Every level needs it, because the signature field is written from the Catalog and page 1 that readDocument resolves. pdfSecurity, pdfStandardV4, pdfStandardV5 and pdfStandardV6 are appended last. They are read only when the base is encrypted, so a hand-wired factory that signs only unencrypted documents may pass null for them.

What the update contains

ISO 32000-2 §12.7.5.5 makes a signature dictionary the value (/V) of a signature field (/FT /Sig), and §12.8.5.2 says a document timestamp is found the same way, by examining signature fields. So the incremental update that carries a signature dictionary also carries the field that holds it:

Every entry these objects already had is copied as it is, so existing form fields, annotations and /AcroForm keys (/DA, /DR, /NeedAppearances and so on) are kept. All new objects come before the update's cross-reference section, so the /ByteRange covers them like every other byte. LT copies the Catalog, /AcroForm included, when it adds /DSS. LTA then appends a second field for its /DocTimeStamp in the timestamp's own update.

Ed25519: the ISO/TS 32002 declaration

EdDSA signatures come from ISO/TS 32002, which requires "PDF documents using enhancements described in this document" to declare it in the Catalog (ISO/TS 32002 §4). For algorithm: 'ed25519', at every level and with every subFilter, the signing update therefore also re-emits the Catalog under its own number with:

• /Extensions holding the prefix ISO_ → a developer extensions dictionary (ISO 32000-2 §7.12.3) with exactly /Type /DeveloperExtensions, /BaseVersion /2.0, /ExtensionLevel 32002, /ExtensionRevision (:2022) and /URL (https://www.iso.org/standard/45875.html);
• /Version /2.0 when the document's effective version is below 2.0: the Catalog /Version name when there is one, else the header version (ISO 32000-2 §7.7.2, the entry exists so that an incremental update can raise the version; ISO/TS 32002 Table 2 marks EdDSA as PDF 2.x). A PDF 2.0 document gets no /Version entry. A /Version that is not a name counts as absent.

The declaration is merged with what the document already has (ISO 32000-2 §7.12.2: the value of a prefix is a developer extensions dictionary or an array of them):

The Catalog is re-emitted whenever the declaration or the version changes it, including when the /AcroForm is indirect (otherwise the signature field alone does not touch the Catalog); every other Catalog entry is copied as it is. The LT and LTA updates copy the Catalog, so the declaration stays in the newest Catalog. ECDSA and RSA-PSS signatures do not touch /Extensions or /Version.

Viewers. Adobe Acrobat Reader does not validate Ed25519 (EdDSA) signatures: it reports an error about the formatting of the signature, with or without the declaration, and also on an Ed25519 signature produced by OpenSSL (measured 2026-10-05). OpenSSL 3.5 and later verify them (openssl cms -verify). Use ECDSA P-256 where Acrobat interoperability matters — see the PAdES guide.

Encrypted base

A base whose trailer carries /Encrypt gets the same field, with its field name encrypted:

• Password. opts.password is required. It may be the owner or the user password, and '' is a valid empty user password. The document key is derived from it through the standard security handler, once per sign() call and before anything is written.
• Permissions. With the user password, /P must grant bit 4 (modify) and bit 6 (annotations and form fields), ISO 32000-2 Table 22. The owner password is not checked against /P.
• Supported encryption. AES only, for both the string and the stream crypt filters: V=4 R=4 with AESV2, V=5 R=5 and V=5 R=6 with AESV3. RC4 (V below 4, or a /V2 crypt filter), AES-GCM (AESV4, ISO/TS 32003) and any handler other than /Standard are refused with a typed error. Nothing is ever signed without its field.
• What is encrypted. The new field's /T is encrypted with the string crypt filter, keyed by the field's own object number, behind a fresh 16-byte IV from opts.randomBytes (default crypto.getRandomValues). When the string filter is Identity, the name is written in clear. The signature dictionary's /Contents is never encrypted (ISO 32000-2 §7.6.2), and /ByteRange holds integers. Re-emitted objects (Catalog, page 1, /AcroForm, /Fields) keep their number and generation, so the encrypted strings they already held keep their key.
• Ed25519 declaration. The two new strings of the ISO/TS 32002 dictionary (/ExtensionRevision, /URL) are encrypted with the string crypt filter under the Catalog's object number and generation, each behind a fresh IV; names and integers are never encrypted. The strings of an indirect /Extensions value that is inlined into the Catalog are decrypted under their former object and encrypted again under the Catalog's, since the V=4 key depends on the object number.
• Trailer. Every incremental update written over an encrypted base repeats the base's /Encrypt in its trailer or cross-reference stream dictionary (ISO 32000-2 §7.5.6).
• Levels LT and LTA. Levels LT and LTA are supported on an encrypted base. The DSS certificate, OCSP and CRL streams, any VRI timestamp stream and the VRI /TU string are encrypted with the document key (stream and string crypt filters of the base's /Encrypt), as is the DocTimeStamp field's /T. Each of these strings and streams gets its own fresh 16-byte IV from opts.randomBytes. The hexadecimal /Contents of the /Sig and /DocTimeStamp dictionaries is never encrypted (ISO 32000-2 §7.6.2). Every incremental update repeats the base's /Encrypt (§7.5.6). Copied objects (Catalog, page, AcroForm) keep their existing ciphertext under their own object numbers.

To pick a field name that is not taken yet, the existing root field names are decrypted first.

Signed attributes

When signed attributes are emitted (levels T, LT and LTA, or useSignedAttrs: true), they are written in DER SET OF order. Each attribute is encoded first. The encodings are then sorted as unsigned byte strings, and an encoding that is a prefix of a longer one sorts first (X.690 §11.6). The signature covers these sorted bytes (RFC 5652 §5.4). A verifier that re-encodes the attributes before it checks the signature, as OpenSSL does for Ed25519, therefore checks the bytes that were signed. Signatures written in the earlier fixed order (contentType, messageDigest, signingTime, signing-certificate-v2) still verify with pdfSignature, which checks the attributes as received.

Resolve

const s = runtime.resolve('pdfSign');
// Returns: { sign, _buildPkcs7, _buildSignedAttrs, _sortDerSetOf,
//            _buildUnsignedAttrsTsa, _extractIssuerSerial,
//            _emitWithPlaceholder, _hashBytes, _toDer, HASH_TABLE }

The factory also returns internal helpers with a leading underscore, exposed for white-box testing only — prefer sign for the stable contract.

API

SignOpts

{
    cert: Uint8Array | string,        // X.509 DER bytes or PEM string
    privateKey:                        // algorithm-specific:
        { n, e, d }                    //   RSA-PSS — Uint8Array each
      | { curve, secretKey }           //   ECDSA — ecc.curves.c256|c384|c521 + ecc.ecdsa.secretKey
      | Uint8Array,                    //   Ed25519 — 64 bytes (seed || pub)
    algorithm: 'rsa-pss' | 'ecdsa' | 'ed25519',
    hashAlg?: 'sha256' | 'sha384' | 'sha512',  // default 'sha256'; 'sha512' only (and default) for Ed25519
    level?: 'B' | 'T' | 'LT' | 'LTA',           // default 'B'
    subFilter?: string,                          // default 'adbe.pkcs7.detached'
    useSignedAttrs?: boolean,                    // default false for level 'B'
    placeholderBytes?: number,                   // default 8192
    docTimeStamp?: boolean,                      // internal — DocTimeStamp object emission
    signingTime?: Date,
    tsaSign?: (args: { digest, hashAlg }) => Uint8Array,  // required for T/LT/LTA
    dss?: { certs?, ocsps?, crls?, vri?, autoVri?, vriTime? },  // LT/LTA — see pdfDssBuilder
    docTimeStampPlaceholder?: number,            // LTA — default = placeholderBytes
    password?: string | Uint8Array,              // encrypted base: owner or user password ('' = empty user password)
    randomBytes?: (n: number) => Uint8Array      // encrypted base: IV source (field names, DSS strings and streams), default crypto.getRandomValues
}

Examples

Level B — RSA-PSS, PAdES SubFilter

const s = runtime.resolve('pdfSign');
const signed = s.sign(pdfBytes, {
    cert, privateKey: { n, e, d },
    algorithm: 'rsa-pss', hashAlg: 'sha256',
    subFilter: 'ETSI.CAdES.detached'   // required for PAdES — not the default
});

Level T — with a timestamp authority callback

const signed = s.sign(pdfBytes, {
    cert, privateKey, algorithm: 'ecdsa',
    level: 'T',
    tsaSign: ({ digest, hashAlg }) => callRealTsa(digest, hashAlg) // returns RFC 3161 TimeStampToken DER
});

Level LTA — full chain with DSS + DocTimeStamp

const signed = s.sign(pdfBytes, {
    cert, privateKey, algorithm: 'ed25519',
    level: 'LTA',
    tsaSign: myTsaCallback,
    dss: { certs: [leafDer, caDer], ocsps: [ocspDer], autoVri: true }
});

Errors

Raised as ContractError unless noted.

See also

• pdfSignature — verify side (the counterpart this module's output is checked against).
• pdfDssBuilder — DSS construction for levels LT/LTA.
• pdfByteRange · pdfTimestamp · pdfCertChain
• pdfIncrementalWriter — underlying append mechanism for every level.