Pro edition

Security — Deep Reference

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.

Availability & licensing

This capability ships in NextPDF Pro (nextpdf/pro) and activates with a Pro-tier license envelope. A deployment without that entitlement does not load the capability’s classes. Compare editions and get a license.

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. 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.

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.

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

Type	Kind	Role	Stability	Since
`RemoteSigningSession`	class	Two-phase remote or asynchronous signing session	stable	1.9.0
`RemoteSigningConfig`	class	Immutable session configuration, including PAdES level and algorithm	stable	1.9.0
`SequentialSigner`	class	Multi-party sequential signing with DocMDP support	stable	1.9.0
`SequentialSigningResult`	class	Result of a sequential run: PDF bytes, chain, count, completeness	stable	1.9.0
`SigningStrategy`	interface	The signing-mechanism contract a session calls	stable	1.9.0
`PadesWrapper`	class	Wraps an existing CAdES or XAdES signature for PAdES embedding	stable	1.9.0
`KmsSignerInterface`	interface (SPI)	Third-party HSM and KMS driver contract; extends the Core HSM signer contract	stable	2.1.0
`SignatureAlgorithm`	enum	Pro signature-algorithm OIDs and digest names	stable	2.1.0
`GenerationTimeMasker`	class	Rule-driven masking applied before the page is written	stable	1.9.0
`MaskingConfig`	class	Immutable masking configuration	stable	1.9.0
`MaskingRule`	class	A single masking rule (literal or PCRE)	stable	1.9.0
`MaskingMode`	enum	BlackBox, Asterisks, FixedLabel	stable	1.9.0

`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.
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. 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 concerns cryptographic functionality; treat it as security-sensitive in your own review.

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.

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. 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.

PAdES level	Adds	Producer edition
B-B	CMS signature with signed attributes	Core, Pro
B-T	One RFC 3161 signature-time-stamp unsigned attribute on the signature value	Core, Pro
B-LT	Document Security Store with validation material	Enterprise (`nextpdf/enterprise`)
B-LTA	Document timestamps for archival validity	Enterprise (`nextpdf/enterprise`)

Publication boundary

This page documents externally observable behavior and the supported public API surface only. Internal namespace paths, helper classes, mechanism tables, runbook filenames, and ticket prefixes are out of scope.

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.

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

Claim	Standard	Clause
The CMS signature is stored DER-encoded in the signature dictionary `Contents` entry.	ISO 32000-2	§12.8.1
The message digest calculation process; signed attributes carry content-type and message-digest.	RFC 5652	§5.4
The verifier must not rely on originator-computed digests; it independently recomputes and compares (signature verification process).	RFC 5652	§5.6
SignerInfo carries the digest-algorithm identifier and the signed-attributes block.	RFC 5652	§5
A timestamp request returns a TSTInfo structure.	RFC 3161	§2.4.1
A timestamp serialNumber is unique per token from a given TSA.	RFC 3161	§2.4.2
The timestamp genTime is the UTC instant the token was created.	RFC 3161	§2.4.2
A PAdES B-T signature-time-stamp is an unsigned attribute carrying one time-stamp token computed on the digital signature value for a signer (Pro produces B-T).	ETSI EN 319 122-1	§5.3
The signature-time-stamp imprint is the hash of the SignerInfo signature field value with the ASN.1 tag and length excluded.	ETSI EN 319 122-1	§5.3
The signature-time-stamp token uses the `id-aa-timeStampToken` OID; its MessageImprint is a hash of the SignerInfo signature field value.	RFC 3161	Appendix A
On the verify side, NextPDF binds a signature-time-stamp’s MessageImprint to the SignerInfo signature value and fails closed on a mismatch, missing/duplicated token, or SHA-1 imprint (strict verification).	RFC 3161	Appendix A
ESSCertIDv2 replaces the SHA-1-bound legacy ESSCertID; the strict B-T path requires ESSCertIDv2.	RFC 5816	§1
Certification path validation checks basic constraints and path inputs to a trust anchor.	RFC 5280	§6.1
OCSP reports certStatus as good, revoked, or unknown.	RFC 6960	§2.2
OCSP status freshness is bounded by thisUpdate and nextUpdate.	RFC 6960	§4.2
B-LT and B-LTA add a Document Security Store and document time-stamps for long-term validation (Enterprise boundary).	ETSI EN 319 142-2	§5.5
A signature handler that produces long-term levels supports DSS entries and document time-stamps (Enterprise boundary).	ETSI EN 319 142-2	§6.3.3.3

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.