Security — Deep Reference

Gated content notice. This page is part of the gated reference surface. Distribution is restricted by NDA. Do not mirror this page to public channels.

At a glance

This is the deep reference for the NextPDF Pro security surface: generation-time masking, text-layer PII detection, the remote and cloud-KMS signing session, multi-party sequential signing, the CAdES and XAdES ingest path, the PAdES B-B baseline level, and PAdES B-T signing support (a B-B signature plus one RFC 3161 signature-time-stamp on the signature value). It states the public-API contract, the externally observable behavior, and the Enterprise B-LT/B-LTA boundary. It is behavior-level; it cites no internal implementation paths.

Edition gate

This surface requires NextPDF Pro. Core ships the software CMS signer, the RFC 3161 timestamp client, RFC 5280 path validation, and OCSP and CRL revocation checking. Pro adds the masking, PII detection, remote and cloud-KMS signing surface, and PAdES B-T signing support (it composes the Core RFC 3161 stack to add a signature-time-stamp) described here. Get a license.

License feature flag

The capability flag for this surface is pro. A deployment without an active Pro entitlement does not load these classes. The Core signing contract continues to work unchanged, and code that depends on the Core contract does not break when the entitlement is absent.

Install

composer require nextpdf/pro:^3

Behavior contract

The masking engine applies an ordered rule list to text before the page is written. A rule matches a PCRE pattern and replaces a match in one of three modes:

• BlackBox — removes the matched text from the content stream and reserves a fill region. This mode removes the underlying text objects as tested.
• Asterisks — replaces each matched character with an asterisk, preserving the character count.
• FixedLabel — replaces the entire match with a configurable label, [REDACTED] by default.

A rule is built from an exact literal through MaskingRule::exactMatch (the literal is regex-escaped) or from a custom PCRE pattern through MaskingRule::regex. MaskingConfig holds the ordered rule list, a default mode, and the fill color. MaskingConfig::fromArray parses a configuration map and silently drops a rule entry that has no usable string pattern, rather than failing the whole import.

The PII surface extracts the PDF text layer, then applies built-in patterns for email addresses, phone numbers, United States Social Security numbers, and credit-card numbers. It returns a structured result: a boolean for whether any match was found, a match count, the masked text view, and the list of scanned types. The caller may restrict the scan to a subset of the four types. The surface does not overwrite the rendered page glyphs; a scanned page with no text layer yields no matches. Treat the result as text-layer pattern detection of the configured types, not as complete personal-data removal and not as a regulatory-compliance statement.

The signing session is two-phase. RemoteSigningSession::create opens a session. prepare computes the document digest over the two ByteRange regions, then builds the CMS signed attributes. complete calls the strategy and embeds the result; suspend serializes the session so a worker can resume it later with resume and completeWithRawSignature. The session assembles a CMS SignedData and stores it DER-encoded in the signature dictionary Contents entry — ISO 32000-2 §12.8.1. When a parseable X.509 certificate is supplied, the session emits the full PAdES B-B mandatory signed-attribute set: content-type, message-digest, signing-time, signing-certificate-v2, and an algorithm-protection attribute — RFC 5652 §5.3 and RFC 5652 §5. The verifier recomputes the content digest and compares it with the message-digest attribute; the comparison must match for the signature to be valid — RFC 5652 §5.4.

When the configured PAdES level is B-T (RemoteSigningConfig::default->withLevel(SignatureLevel::PAdES_B_T), or via SequentialSigner::withTimestamping) and a timestamp provider is wired, the session additionally embeds exactly one RFC 3161 signature-time-stamp as a CMS unsigned attribute on the first SignerInfo. A signature-time-stamp is an unsigned attribute carrying one time-stamp token computed on the digital signature value for a signer — ETSI EN 319 122-1 §5.3; its MessageImprint is the hash of the SignerInfo signature field value with the ASN.1 tag and length excluded — ETSI EN 319 122-1 §5.3 and RFC 3161 Appendix A (OID id-aa-timeStampToken = 1.2.840.113549.1.9.16.2.14). Because the timestamp is an unsigned attribute, the B-B signed attributes, the message-digest, the SignerInfo signature value, and the PDF /ByteRange are byte-identical to the B-B output; only the CMS grows by the unsigned attribute, and the B-T reserved /Contents space is raised so it fits. The token is requested from the configured timestamp provider (the default Core RFC 3161 client, or a caller-supplied provider). On the default provider path the imprint digest is SHA-256; the SHA-1-bound legacy ESSCertID v1 form is refused and ESSCertIDv2 is required — RFC 5816 §1. A TSA fault, a refused request, a bad nonce or message-imprint echo, a malformed or unsupported-algorithm token, or a token that fails cryptographic verification surfaces as a typed PadesBt exception with the originating Core exception preserved as the previous throwable. NextPDF Pro implements PAdES B-T signing support per ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, and RFC 5816, and it is fixture-verified; it does not assert an independent ETSI EN 319 142-1 certification and does not assert document legal validity.

SequentialSigner coordinates multi-party signing. Each signer is a separate incremental-update revision. The first signer may be a certification signature with a DocMDP restriction set through certifyFirst. PadesWrapper ingests an existing signature: fromCades embeds a CMS structure directly, fromXades parses an XAdES document and reuses its core signature material, and detect auto-selects by format. The XAdES path reuses the certificate, chain, signature value, and algorithm; it does not transfer XAdES qualifying properties.

Public API surface

composer require nextpdf/pro:^3

SigningStrategy contract

A strategy operates on the DER-encoded signed attributes and returns the raw signature bytes. The session, not the strategy, assembles the CMS SignedData. A strategy exposes the signer certificate DER, the chain DER ordered leaf-to-root, the signature-algorithm OID, the digest-algorithm name, and an isAsync flag that marks a strategy whose session can be serialized and resumed.

KmsSignerInterface SPI

KmsSignerInterface extends the Core HSM signer contract. It adds a stable providerId for registry lookup, a signWithVersion method with an explicit per-call key-version parameter, and supportsAlgorithm and supportedAlgorithms so a caller discovers algorithm compatibility before the sign call. The reserved built-in provider identifiers are aws-kms, azure-keyvault, gcp-kms, pkcs11, openssl-cli, and openssl-engine. A third-party driver must namespace its identifier to avoid a collision. The default key-version semantics vary by provider: an alias-resolving provider resolves the active key from the alias when the version is null; a provider that selects the latest enabled version does so through its transport; a provider that has no server-side active-version concept must use a version pinned in its configuration, and must raise a key-management error when neither the call nor the configuration pins a version. A non-empty version pins that version, and the provider must raise a key-management error when the version is unknown, disabled, or revoked.

Edge cases & gotchas

• A produced signature is not a verified signature. Path validation runs at the verifier with that verifier’s trust anchors and basic-constraint checks — RFC 5280 §6.1. The producer cannot assert the result.
• The session has a legacy three-attribute fallback for non-X.509 synthetic certificate bytes. Production strategies always supply real X.509 DER, so the full B-B attribute set is the production path. The fallback exists for the historical DER-mechanics test surface only.
• The CMS structure must fit the reserved Contents space. The B-B SignedData with a full certificate chain has a size; the session raises an overflow error when the assembled CMS exceeds the reserved hex space. Size the reserved space accordingly. For B-T the embedded RFC 3161 token (dominated by the TSA certificate chain) enlarges the CMS; the B-T reserved space is raised automatically, and an undersized configured space fails closed with a typed configuration error rather than truncating.
• MaskingConfig::fromArray drops an entry with no usable string pattern instead of failing the import. Validate the configuration source if a silent drop is unacceptable.
• The masking black-box mode emits an empty replacement for the matched run and removes the underlying text. A rule that does not match a value does not mask it; the engine does not assert that all sensitive content is found.
• B-T requires a wired timestamp provider. On the default Core RFC 3161 provider path the imprint digest is SHA-256; a non-SHA-256 imprint digest on that path is rejected with a typed configuration error rather than silently downgraded, and a caller-supplied custom provider may legitimately use another approved digest. A timestamp serialNumber is unique per token from a given Time-Stamping Authority, and genTime is the UTC instant the token was created — RFC 3161 §2.4.1, §2.4.2. B-LT/B-LTA long-term validation material remains an Enterprise-boundary concern; Pro produces no DSS, no VRI, and no document timestamp.
• OCSP unknown is not good, and the status freshness is bounded by thisUpdate and nextUpdate — RFC 6960 §2.2, §4.2.

FIPS-mode behavior

Pro selects the algorithm from the configured signature algorithm and the strategy. When configured against a FIPS-validated KMS or HSM, the cryptographic operation runs in that validated boundary, and the algorithm set is whatever that boundary permits. NextPDF Pro performs structural CMS assembly and digest computation; it is not a FIPS-validated cryptographic module and makes no FIPS certification claim. A deployment that requires a FIPS posture must configure a FIPS-validated KMS or HSM, and the FIPS 140-3 crypto-policy profile is an Enterprise capability.

Export-control posture

This module is flagged export_control_class: legal-review-required. Legal sign-off is required before any publish: true flip.

Enterprise boundary

NextPDF Pro produces the B-B baseline and the B-T level. For B-B the session assembles a CMS SignedData with the B-B signed-attribute set and applies no timestamp. For B-T it adds exactly one RFC 3161 signature-time-stamp as a CMS unsigned attribute computed on the digital signature value for a signer — ETSI EN 319 122-1 §5.3. NextPDF Pro implements this per ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, and RFC 5816, and it is fixture-verified; it does not assert an independent ETSI EN 319 142-1 certification, conformance, or compliance, and does not assert document legal validity.

The B-LT and B-LTA levels are Enterprise capabilities and are not produced by Pro. B-LT and B-LTA add a Document Security Store and document time-stamps for long-term archival validation — ETSI EN 319 142-2 §5.5. A signature handler that produces those levels supports DSS entries and document time-stamps — ETSI EN 319 142-2 §6.3.3.3. The Pro RemoteSigningConfig can carry a level above B-T (B-LT or B-LTA) that requests a Document Security Store, but Pro does not ship that producer and does not act on it; such a level is a forward-declared value. The Core signing flow resolves the long-term producer at runtime through the Core contract, and that producer ships in the nextpdf/enterprise package. In a Pro-only deployment, a request for B-LT or B-LTA fails closed with a message that names the missing Enterprise component. Pro produces no DSS, no VRI dictionary, no document timestamp, and no archival loop, and makes no long-term-validation (LTV) claim. Hardware key custody through PKCS#11, and the FIPS 140-3 crypto-policy profile, are also Enterprise capabilities. This page does not document the Enterprise long-term-validation implementation; it states only the boundary and the public package name.

NDA scan status

This page references public-API class names and enum names only. It does not reference an internal namespace path, an internal helper class, an internal trait, a runbook filename, or a ticket prefix. It does not reference the Enterprise long-term-validation implementation type; the Enterprise edition is named only by its public package name, nextpdf/enterprise. The co-located security.nda-checklist.yaml records the attestation.

Core fallback

A deployment without the Pro entitlement keeps the Core signing contract. Code that depends on the Core SignerInterface contract continues to sign with the software CMS signer at the B-B baseline. The masking, PII detection, and remote and cloud-KMS strategies are not present without the Pro package, and a call into those types is a hard dependency error, not a silent no-op.

Data residency & PII mitigations

The masking and PII surfaces run in-process. No document content leaves the host for masking or PII detection. A cloud-KMS strategy sends the signed-attributes digest, not the document, to the provider for the signing operation. PII detection is pattern-matched on the configured types and removes the underlying text objects for the black-box mode as tested. It is not a complete personal-data removal guarantee and is not a regulatory-compliance statement.

Safe telemetry & log scrubbing

The library raises typed exceptions with structural messages. It does not write document content or detected PII values into exception messages or logs. A deployment that logs around the signing path should log structural fields, not document bytes.

Conformance

All clauses are paraphrased. NextPDF does not reproduce normative text. Consult the published standards for the authoritative wording. NextPDF Pro implements PAdES B-T signing support per ETSI EN 319 122-1 §5.3 (signature-time-stamp), RFC 3161, RFC 5652, and RFC 5816, and it is fixture-verified. ETSI EN 319 142-1 (the PAdES baseline-levels part) is outside the cited evidence set; NextPDF Pro therefore does not assert an independent ETSI EN 319 142-1 certification, conformance, or compliance, and does not assert document legal validity. This page states the produced structure, the standards the B-T support implements, and the Enterprise B-LT/B-LTA boundary, not a certified conformance level.

Commercial context

Core ships the software CMS signer, RFC 3161 timestamp consumption, RFC 5280 path validation, and OCSP and CRL revocation checking. Pro adds generation-time masking, text-layer PII detection, remote and cloud-KMS signing strategies, multi-party sequential signing, the PAdES B-B baseline path, and PAdES B-T signing support (an RFC 3161 signature-time-stamp on the signature value). The B-LT and B-LTA long-term-validation producer, PKCS#11 key custody, and the FIPS 140-3 crypto-policy profile ship in the nextpdf/enterprise package. Editions resolve at runtime against the Core contract, so the API does not change on upgrade.

See also

• Core signing — the CMS signer, RFC 3161 timestamp, RFC 5280 path validation, OCSP and CRL.
• PAdES baseline mapping — B-B, B-T, B-LT, B-LTA across editions.
• Security (public landing) — the public Pro security overview.
• CMS · PAdES · RFC 3161 timestamp · KMS · DSS — glossary terms.