Pro edition

Security

At a glance

NextPDF Pro adds a security surface on top of NextPDF Core: generation-time content masking, text-layer PII detection, remote and cloud-KMS signing strategies, and multi-party sequential signing. NextPDF Core produces the PAdES B-B and B-T levels; Pro produces the same levels and adds these signing workflows over them (for B-T, a B-B signature plus one RFC 3161 signature-time-stamp on the signature value). This page is behavior-level. It states what each part does, what it does not do, and where the Enterprise boundary begins.

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, and remote/cloud-KMS/sequential signing workflows; those workflows produce the same Core B-B and B-T levels through the Core RFC 3161 stack (for B-T, one signature-time-stamp on the signature value). A deployment without an active Pro entitlement does not load these classes; the Core signing contract continues to work unchanged.

Install

composer require nextpdf/pro:^3

Conceptual overview

The masking engine applies an ordered list of rules to text before the page is written. Each rule matches a regular expression. A rule replaces a match in one of three ways: a black-box fill that removes the text from the content stream, an asterisk run of the same character count, or a fixed label such as [REDACTED]. The engine removes the underlying text objects for the black-box mode as tested. Detection depends on the rules you configure.

The PII surface is a detection tool. It extracts the text layer, then applies built-in patterns for email addresses, phone numbers, United States Social Security numbers, and credit-card numbers. It returns a masked view of the text and a count of matches. It does not overwrite the rendered glyphs in the page image. A scanned page with no text layer yields no matches. Treat the result as pattern-matched detection of the configured types.

The signing surface adds remote and asynchronous workflows on top of the Core signer. A session computes the document digest, builds the CMS signed attributes, and hands the signed-attributes bytes to a signing strategy. A strategy may be a cloud KMS, a deferred external signer, or an ingest path that wraps an existing CAdES or XAdES signature. The session then assembles the CMS SignedData and stores it DER-encoded in the signature dictionary Contents entry — ISO 32000-2 §12.8.1. The SignerInfo carries the content-type and message-digest signed attributes; the message digest calculation process is RFC 5652 §5.4. A verifier must not rely on originator-computed digests; it independently recomputes the content digest and compares it with the message-digest attribute, and the comparison must match for the signature to be valid — RFC 5652 §5.6 signature verification process.

NextPDF Core produces the PAdES B-B and B-T levels; NextPDF Pro produces the same levels and adds its signing workflows over them. For B-B the session assembles a CMS SignedData with the B-B signed-attribute set and applies no timestamp. For B-T the session adds exactly one RFC 3161 signature-time-stamp as a CMS unsigned attribute on the signature value: 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, and its MessageImprint is a hash of the SignerInfo signature field value, identified by the id-aa-timeStampToken OID — RFC 3161 Appendix A. The timestamp genTime is the UTC instant the token was created — RFC 3161 §2.4.2. Because the timestamp is an unsigned attribute, the B-B signed digest, the SignerInfo signature value, and the PDF /ByteRange are unchanged; only the CMS grows. The RFC 3161 token is obtained from a configured timestamp provider (the default Core RFC 3161 client, or a caller-supplied provider); B-T uses a SHA-256 message imprint on the default provider path. NextPDF Pro implements PAdES B-T signing support per ETSI EN 319 122-1 §5.3, RFC 3161, RFC 5652, and RFC 5816; this is fixture-verified. B-LT and B-LTA add a Document Security Store and document timestamps for long-term archival validation — ETSI EN 319 142-2 §5.5; those levels are an Enterprise capability (nextpdf/enterprise) and are not produced by Pro. See Enterprise boundary below.

Why it works this way

The signing surface hands the signed-attributes bytes to a SigningStrategy rather than holding a private key. That one decision is load-bearing. A cloud KMS, a deferred external signer, or a CAdES/XAdES-ingest path all satisfy the same contract, so calling code stays identical and the key material never enters NextPDF. Splitting the session into RemoteSigningSession::prepare() and RemoteSigningSession::complete() lets the signature return asynchronously, because the digest is fixed before the key is ever reached. The timestamp is attached as a CMS unsigned attribute, so B-T stays additive: the B-B signed digest, the SignerInfo signature value, and the /ByteRange are untouched. Every seam is fail-closed, since a signing path that silently degrades is worse than one that stops. Design background: Signing at scale, without compromise.

API surface

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	stable	1.9.0
`SequentialSigner`	class	Multi-party sequential signing with DocMDP support	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	stable	2.1.0
`GenerationTimeMasker`	class	Rule-driven masking applied before the page is written	stable	1.9.0
`MaskingConfig` / `MaskingRule` / `MaskingMode`	types	Masking configuration, rule, and replacement mode	stable	1.9.0

RemoteSigningConfig carries a PAdES level field whose enum is the Core SignatureLevel. The Pro signing path produces the B-B baseline and the B-T level: configure RemoteSigningConfig::default()->withLevel(SignatureLevel::PAdES_B_T) (or use SequentialSigner::withTimestamping()) and supply a timestamp provider, and the session adds the RFC 3161 signature-time-stamp unsigned attribute. The B-T reserved /Contents space is raised automatically so the token fits; an undersized configured space fails closed with a typed configuration error rather than truncating. A level above B-T carried in the config (B-LT or B-LTA) is a forward-declared value that Pro does not act on; that long-term producer resolves at runtime through the Core contract and ships in the nextpdf/enterprise package.

Code sample — Quick start

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Pro\Security\Signing\RemoteSigningSession;
use NextPDF\Pro\Security\Signing\SigningStrategy;

/**
 * Produce a signed PDF using any signing strategy.
 *
 * @param string          $pdfWithPlaceholder PDF bytes with a signature placeholder.
 * @param SigningStrategy  $strategy           A cloud-KMS, deferred, or ingest strategy.
 *
 * @return string The signed PDF bytes.
 */
function signWithStrategy(string $pdfWithPlaceholder, SigningStrategy $strategy): string
{
    $session = RemoteSigningSession::create($pdfWithPlaceholder);

    $session->prepare(
        certDer: $strategy->getCertificateDer(),
        chainDer: $strategy->getCertificateChainDer(),
        algorithmOid: $strategy->getSignatureAlgorithmOid(),
        digestAlgorithm: $strategy->getDigestAlgorithm(),
        contentsHexStart: 0,
        contentsHexEnd: 0,
    );

    return $session->complete($strategy);
}

The caller depends on the SigningStrategy contract. A cloud-KMS strategy and a CAdES-ingest strategy both satisfy it, so this code does not change between strategies.

Code sample — Production

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Pro\Security\Signing\SequentialSigner;
use NextPDF\Pro\Security\Signing\SigningStrategy;
use Psr\Log\LoggerInterface;

final readonly class ApprovalWorkflow
{
    public function __construct(private LoggerInterface $logger) {}

    /**
     * Sign a PDF with two parties in sequence.
     *
     * @param string          $pdfData   The PDF bytes to sign.
     * @param SigningStrategy  $approver  The first-party strategy.
     * @param SigningStrategy  $reviewer  The second-party strategy.
     *
     * @return string The signed PDF bytes.
     */
    public function run(string $pdfData, SigningStrategy $approver, SigningStrategy $reviewer): string
    {
        try {
            $result = SequentialSigner::create($pdfData)
                ->addSigner($approver, 'Approver', reason: 'Approved')
                ->addSigner($reviewer, 'Reviewer', reason: 'Reviewed')
                ->sign();

            $this->logger->info('Sequential signing complete', [
                'signatures' => $result->signatureCount,
            ]);

            return $result->pdfData;
        } catch (\Throwable $e) {
            $this->logger->error('Sequential signing failed', ['error' => $e->getMessage()]);

            throw $e;
        }
    }
}

Each signer is a separate incremental revision. The catch block logs and rethrows; it does not swallow the failure, which keeps the signing path fail-closed.

Edge cases & gotchas

A produced signature is not a verified signature. Path validation runs at the verifier with that verifier’s trust anchors — RFC 5280 §6.1. The producer cannot assert the result.
Masking detection depends on the configured rules. A rule set that does not match a value does not mask it.
PII detection is text-layer only. A scanned page with no text layer yields no matches. The tool does not overwrite the rendered page glyphs.
The CMS structure must fit the reserved Contents space. The B-B SignedData with a full certificate chain has a size; size the reserved space accordingly, or the session raises an overflow error.
A cloud-KMS strategy depends on network reachability and provider availability. A network or provider error raises a typed exception; the session does not silently produce an unsigned document.
OCSP unknown is not good. Treat unknown as a non-determination — RFC 6960 §2.2.

Performance

A software signature is single-digit milliseconds. A cloud-KMS signature adds one network round trip to the provider. A B-T signature adds one round trip to the configured timestamp provider on top of the signing operation. The 1500 ms wall budget covers a single B-B signature with a remote provider on a warm connection. Masking cost scales with the rule count and the text length. The reproducibility profile is structural: the B-B signed attributes embed the signing instant and a B-T signature additionally embeds a timestamp token, so two runs differ in the signing-time and timestamp bytes while the signed structure is identical.

Security notes

This is a cryptographic boundary, so the threat model is explicit. The byte range is computed by the engine and is never accepted from the caller. The signing path is fail-closed: a primitive failure or a capability gap raises a typed exception and never silently downgrades to a weaker algorithm. A cloud-KMS strategy is an integration point, not a key store. Key protection depends on key handling, the configured KMS, and the deployment; NextPDF Pro does not hold the private key for a KMS strategy. Pro operates in a FIPS-compatible mode when configured against a FIPS-validated KMS or HSM; NextPDF Pro is not itself a FIPS-validated cryptographic module. This page concerns cryptographic signing; every normative source is paraphrased and none is reproduced.

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 the structural fields shown in the production sample, not the document bytes.

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. NextPDF Pro itself performs structural assembly and digest computation.

Enterprise boundary

NextPDF Pro produces the B-B baseline and the B-T level. B-T adds one RFC 3161 signature-time-stamp as a CMS unsigned attribute on the signature value, 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; 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 timestamps for long-term archival validation — ETSI EN 319 142-2 §5.5. A configuration that requests a Document Security Store or the long-term archival loop resolves that producer at runtime through the Core contract; that producer ships in the nextpdf/enterprise package. In a Pro-only deployment, requesting B-LT or B-LTA fails closed with a message that names the missing Enterprise component. Pro produces no Document Security Store, 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.

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

Behavior contract

Masking applies configured rules before the page is written and removes the underlying text objects for the black-box mode as tested.
PII detection extracts the text layer, applies the configured patterns, and returns a masked view and a match count. It does not overwrite rendered glyphs.
Remote signing is two-phase: prepare computes the digest and builds signed attributes; complete assembles the CMS and embeds it.
Pro produces the B-B baseline and the B-T level. For B-T, the session adds one RFC 3161 signature-time-stamp as a CMS unsigned attribute on the signature value; the B-B signed digest and the /ByteRange are unchanged. A B-T request without a timestamp provider, or with an undersized configured Contents space, fails closed with a typed configuration error. A request for B-LT or B-LTA without the Enterprise package fails closed with a named error.
A cloud-KMS strategy receives the signed-attributes digest, not the document, and returns the raw signature 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
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 `id-aa-timeStampToken` token’s `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
A B-T timestamp token carries a UTC genTime that is the instant the token was created.	RFC 3161	§2.4.2
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
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

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.

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.