Security — Deep Reference (Gated)
Gated content notice. This page is part of the gated reference surface. Distribution restricted by NDA. Do not mirror to public channels.
At a glance
This deep reference describes the PKCS#11 hardware-token signing path, the FIPS-mode crypto-policy presets, and the power-on self-test guard at the public API level. It states behavior and boundaries. It does not reproduce internal mechanism tables, session-recovery internals, or migration material.
Edition gate
Requires NextPDF Enterprise. Get a license.
License feature flag
The enterprise tier gates this surface. Install the Enterprise package next to the Core package. The signing and validation producers resolve at runtime through the Core contract.
Conceptual overview
The Enterprise security surface has three public parts.
The PKCS#11 token signer implements the Core hardware-signer interface. It opens the PKCS#11 library, logs into the configured slot with the configured PIN, and locates the certificate and the private key by label. The certificate label and the private-key label may differ; the constructor accepts an optional separate key label for tokens that use distinct labels. The signer asks the token to compute the signature with a mechanism mapped from the requested algorithm. RSA PKCS#1 v1.5, RSA-PSS with SHA-256/384/512, and ECDSA with SHA-256/384/512 are supported. For RSA-PSS, the salt length equals the digest length, per PKCS#11 v3.1 §5. ECDSA token mechanisms return a raw signature; the signer converts it to the DER-encoded form for PDF and OpenSSL interoperability. The token sign operation, the session, and the user login follow PKCS#11 v3.1 §5. ECDSA signature generation follows FIPS 186-5 §6.3.2.
The FIPS crypto-policy has a strict preset and a standard preset. The strict preset corresponds to a FIPS 140-3 era profile: SHA-256/384/512 hashes; RSA and ECDSA signature OIDs with those hashes; RSA-PSS; AES-256-CBC; minimum RSA 2048 and EC 256. The standard preset adds AES-128-CBC for older interoperability. A guard wraps the policy and asserts each hash, signature OID, encryption algorithm, and key strength before the cryptographic operation. A disallowed choice raises a typed FIPS violation. The minimum RSA key length follows NIST SP 800-131A Rev.2 §3; the transition status follows the same clause. The ECDSA curve and hash pairing follows FIPS 186-5 §6.1.1.
The power-on self-test guard runs a known-answer-test battery at process start and caches the result for the process lifetime. The battery covers the approved hash, MAC, encryption, signature, and random-bit functions. A test failure puts the module in an error state; cryptographic services are refused until reset. An on-demand re-run is available, for example wired to an admin-only endpoint or a maintenance command. The self-test category, the documentation requirement, the conditional-test trigger, and the disjoint-set property follow ISO/IEC 19790:2025 §7.10, §7.10.2, §7.10.3, and §7.10.3.p3.
Public API surface
composer require nextpdf/enterprise:^3| Public surface | Type | Notes |
|---|---|---|
| PKCS#11 token signer | class implementing the Core HsmSignerInterface | Constructor: library path, slot id, sensitive PIN, certificate label, optional key label, optional chain, optional experimental post-quantum opt-in. Exposes sign, isAvailable, signer-certificate and chain accessors. |
| FIPS crypto-policy | class implementing the Core CryptoPolicyInterface | strict and standard factory presets; allowed-hash, allowed-signature-OID, allowed-encryption, and key-strength predicates. |
| FIPS-mode guard | class | Assert-style methods for hash, signature OID, encryption algorithm, and key strength; raises a typed violation. |
| FIPS boot guard | class | report, rerun, assertOperational, status over the self-test. |
| OpenSSL CLI / engine signer | classes implementing HsmSignerInterface | Engine-backed or CLI-backed signing for tokens exposed through an OpenSSL engine. |
Class names above are the public, supported integration surface. Internal helper classes, internal traits, internal namespace paths, and internal mechanism-mapping tables are out of scope and are not listed.
Edge cases & FIPS-mode behavior
FIPS-mode behavior
The FIPS-mode policy restricts cryptographic choices to the approved set. FIPS-allowed in strict mode: SHA-256/384/512; RSA PKCS#1 v1.5 and RSA-PSS with those hashes; ECDSA P-256/384/521 with those hashes; AES-256-CBC; RSA ≥ 2048, EC ≥ 256. FIPS-rejected in strict mode: weaker or legacy hashes, non-approved signature OIDs, AES-128 (allowed only in the standard preset for legacy interoperability), and any key below the minimum strength. The guard rejects an unknown key type by default. The path is fail-closed and never substitutes a weaker algorithm. AES-GCM use requires a unique initialization vector per key, per NIST SP 800-38D §5.
NextPDF Enterprise is not a FIPS-validated cryptographic module and makes no FIPS certification claim. NextPDF Enterprise operates in a FIPS-compatible mode only when it is configured with a FIPS-validated cryptographic provider — for example a FIPS-validated OpenSSL provider — or a FIPS-validated HSM. The FIPS-mode policy assists compliance; it is not a certification. No FIPS certification artifact exists in this repository.
Export-control posture
This module is flagged export_control_class: legal-review-required. Legal sign-off is required before the publish flag is set.
Post-quantum status
A post-quantum signing path exists behind an opt-in constructor flag. It is experimental and disabled by default. The standard PAdES profile family and the AdES cryptographic-suites catalogue do not yet recognize post-quantum suites for long-term archival. Many PDF viewers reject post-quantum signatures at validation time. Do not enable the post-quantum path for production AdES signatures. Hardware round-trip validation of this path is not yet complete; the present state is mock-tested readiness only.
Deployment boundary
NextPDF Enterprise integrates with a PKCS#11 token, an HSM, or a KMS. It does not store, generate, or guarantee the security of the signing key. Key security depends on the token, HSM, or KMS, on the deployment, and on the operator — not on NextPDF Enterprise alone. The operator owns token provisioning, PIN handling, slot configuration, network protection of a network-attached HSM, and trust configuration. Key-protection responsibility follows NIST SP 800-57 Part 1 Rev.5 §5.5.2. This page does not expose token PIN handling, slot or PIN-policy internals, or vendor credential material.
Legal-compliance boundary
This page is marked export_control_class: legal-review-required. The FIPS-mode policy is a compliance-assistance feature, not a legal opinion and not a certification. Consult your own compliance and legal advisers.
NDA scan status
This gated page references public API class names only. It contains no internal namespace paths, no internal trait names, no internal mechanism-mapping tables, no runbook filenames, and no internal ticket prefixes. Attested in the co-located NDA checklist.