Security — HSM, PKCS#11 and FIPS-mode

At a glance

NextPDF Enterprise adds a PKCS#11 hardware-token signing path and a FIPS-mode cryptographic policy on top of the Core and Pro security surface. This page states behavior, boundaries, and the explicit FIPS-certification and key-custody stance.

Availability & licensing

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

Conceptual overview

The Enterprise security surface has three parts: a hardware-token signer, a FIPS-mode crypto policy, and a power-on self-test guard.

The hardware-token signer adapts a PKCS#11 token — a smart card, a USB device, or a network-attached HSM. The signer locates the certificate and the private key on the token by label. It then asks the token to compute the signature. The private key does not leave the token boundary; the operation runs inside the token. The token sign operation, the session, and the user login follow PKCS#11 v3.1 §5. The HSM path needs the ext-pkcs11 PHP extension. That extension is not part of standard PHP. Install it separately. Use the availability check before you construct the signer.

The FIPS-mode crypto policy restricts cryptographic choices to an approved set. It has two presets. The strict preset allows SHA-256, SHA-384, and SHA-512 hashes; RSA and ECDSA signature OIDs with those hashes; AES-256-CBC encryption; and minimum key sizes of RSA 2048 and EC 256. The standard preset is the same but also allows AES-128-CBC for older interoperability. A runtime guard wraps the policy. The guard checks each hash, signature OID, encryption algorithm, and key strength before the operation runs. A disallowed choice raises a typed violation and stops the operation. The path is fail-closed: the policy never relaxes itself and never substitutes a weaker algorithm. The minimum RSA key length follows NIST SP 800-131A Rev.2 §3. 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 once at process start. The battery covers the approved hash, MAC, encryption, signature, and random-bit functions. If any test fails, the Enterprise FIPS guard enters an error state and refuses cryptographic services until reset. The result is cached for the process lifetime; an on-demand re-run is available. The self-test category and the conditional-test trigger follow ISO/IEC 19790:2025 §7.10 and §7.10.3.

Why it works this way

The load-bearing decision is to keep the private key inside the token boundary and make the crypto policy fail-closed. A signer that could export a key, or silently fall back to a weaker algorithm, would defeat the assurance an HSM exists to provide. So the signer asks the token to compute the signature in place, and the FIPS-mode guard rejects any hash, OID, or key strength outside the approved preset before the operation runs. The power-on self-test extends the same posture to startup: an unverified module refuses service rather than signing on untested primitives. The result is a boundary you can reason about, where key custody is owned by the operator and the token, not by this software.

Design background: HSM-backed signing.

API surface

Public surface	Type	Purpose	Stability	Since
PKCS#11 token signer	class (implements the Core HsmSignerInterface)	Sign with a PKCS#11 token; the key stays on the token	stable	1.0.0
FIPS crypto-policy	class (implements the Core CryptoPolicyInterface)	An allowed-algorithm and key-strength preset	stable	1.9.0
FIPS-mode guard	class	Assert a hash, signature OID, encryption algorithm, or key strength is allowed	stable	1.9.0
FIPS boot guard	class	Run and cache the power-on self-test; assert the module is operational	stable	3.2.0
OpenSSL CLI / engine signer	class (implements HsmSignerInterface)	Sign through an OpenSSL engine or the OpenSSL CLI for engine-backed tokens	stable	1.0.0

The token signer constructor takes the PKCS#11 library path, the slot number, the token PIN, the certificate label, and an optional separate key label. The PIN parameter is marked sensitive; it is not logged and not serialized. The signer also exposes the signer certificate and the certificate chain in DER form. The authoritative parameter and type contract is the published API reference for the nextpdf/enterprise package; treat that reference — not this page — as the contract.

Code sample — Quick start

composer require nextpdf/core
composer require nextpdf/enterprise:^3

Construct a FIPS-mode guard and assert a hash is allowed

use NextPDF\Enterprise\Security\Fips\FipsCryptoPolicy;
use NextPDF\Enterprise\Security\Fips\FipsModeGuard;

$guard = new FipsModeGuard(FipsCryptoPolicy::strict());

// Throws a typed FIPS violation if the algorithm is not approved.
$guard->assertHashAllowed('sha256');
$guard->assertKeyStrengthAllowed('rsa', 2048);

Code sample — Production

Run the power-on self-test at container boot, then gate signing

use NextPDF\Enterprise\Security\Fips\FipsBootGuard;
use NextPDF\Enterprise\Security\Fips\FipsSelfTest;

// At application bootstrap (one self-test cycle per worker process):
$bootGuard = new FipsBootGuard(new FipsSelfTest());
$bootGuard->assertOperational(); // throws on a known-answer-test failure
$container->set(FipsBootGuard::class, $bootGuard);

// The PKCS#11 token signer is only available when ext-pkcs11 is loaded.
// Check availability before you construct the signer. The PIN is a secret;
// supply it from your secret manager, never from source or logs.

The full constructor argument list, exception types, and PKCS#11 token-signer construction are documented in the Enterprise security deep reference.

Edge cases & gotchas

• The PKCS#11 token signer constructor throws a typed operation exception when ext-pkcs11 is not loaded. Check availability first.
• The token signer caches one PKCS#11 module per library path per process. This satisfies the “initialize once per module” rule of the token interface.
• ECDSA token mechanisms return a raw signature. The signer converts it to the DER-encoded form for PDF and OpenSSL interoperability.
• The FIPS guard denies an unknown key type by default. An unrecognized key type is not silently accepted.
• The post-quantum signing path is experimental, opt-in, and disabled by default. Standard PAdES long-term archival profiles do not yet recognize post-quantum suites. Do not enable it for production AdES signatures.

Performance

The FIPS guard checks are constant-time hash-map lookups. The power-on self-test runs once per process; its cost is amortized over the process lifetime, not per signing call. A PKCS#11 signing operation adds one round trip to the token. A network-attached HSM adds the network latency of that round trip.

Security notes

• The signing path is fail-closed. A primitive failure or a policy gap raises a typed exception. The path never silently downgrades to a weaker algorithm.
• The token PIN parameter is marked sensitive. It is not logged and not serialized.
• The private key for a PKCS#11 token stays on the token. The signing operation runs inside the token boundary.
• The power-on self-test puts the Enterprise FIPS guard into an error state on a known-answer-test mismatch and refuses cryptographic services until reset.
• AES-GCM use requires a unique initialization vector per key, per NIST SP 800-38D §5.

Data Residency & PII Mitigations

The signing and FIPS-policy code runs in-process. No document content leaves the host for the FIPS-policy check or the power-on self-test. A PKCS#11 token receives the data to sign, not unrelated document content. A network-attached HSM receives that data over the network channel you configure. The key material stays inside the token or HSM boundary.

Safe Telemetry & Log Scrubbing

The token PIN is a sensitive constructor parameter and is excluded from logs and serialization. Do not add the PIN, the token label, or key material to your own application logs. Treat all token credentials as secrets in your logging and tracing policy.

Threat model

This is a cryptographic boundary, so the threat model is explicit. The data to sign is handed to the token; the token holds the key. A token or HSM error raises a typed exception; the signer does not produce an unsigned or partly signed result. Key protection depends on the token or HSM, the deployment, and the operator — not on this software alone. See the deployment boundary.

Conformance

• The power-on and conditional self-test model aligns with ISO/IEC 19790:2025 §7.10 and §7.10.3.
• The minimum RSA signature key length aligns with NIST SP 800-131A Rev.2 §3.
• The approved ECDSA curve and hash pairing aligns with FIPS 186-5 §6.1.1.
• The PKCS#11 token sign operation and session login align with PKCS#11 v3.1 §5.
• Key-protection responsibility aligns with NIST SP 800-57 Part 1 Rev.5 §5.5.2.
• AES-GCM initialization-vector uniqueness aligns with NIST SP 800-38D §5.

Every normative source is paraphrased. No normative text is reproduced on this page. This page concerns cryptographic signing.

FIPS-mode behavior

The FIPS-mode policy restricts cryptographic choices to the approved set described above. When configured against a FIPS-validated OpenSSL provider, the underlying primitive runs in that validated boundary. NextPDF Enterprise itself performs structural assembly, digest computation, and policy enforcement.

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.

Edition boundary

NextPDF Core ships the software signer, RFC 3161 timestamp consumption, RFC 5280 path validation, and OCSP and CRL revocation checking. Core produces the PAdES B-B and B-T levels. NextPDF Pro adds masking, text-layer PII detection, multi-party sequential signing, and remote and cloud-KMS signing strategies (AWS KMS, GCP Cloud KMS, Azure Key Vault). NextPDF Pro does not provide a PKCS#11 hardware-token path and does not provide a FIPS-mode crypto-policy profile. The PKCS#11 hardware-token signer, the FIPS-mode crypto-policy profile, the power-on self-test guard, and the PAdES B-LT and B-LTA producer ship in the nextpdf/enterprise package only. A deployment without the Enterprise entitlement does not load the Enterprise classes.

Pro fallback

In a Pro-only deployment, the supported hardware-backed and cloud-backed signing path is the Pro cloud-KMS strategy: a cloud KMS or HSM-backed KMS holds the key, and Pro sends the signed-attributes digest, not the document, to the provider. Pro provides KMS integration, not the Enterprise PKCS#11 token factory or the FIPS-mode profile. A configuration that requests B-LT, B-LTA, a PKCS#11 token, or the FIPS-mode profile in a Pro-only deployment fails closed with a message that names the missing Enterprise component. See Security — NextPDF Pro for the Pro signing surface.

Core fallback

In a Core-only deployment, the software signer produces PAdES B-B and B-T with a local key or a key supplied through the Core signing-strategy contract. Core has no hardware-token path and no FIPS-mode profile. See Security — NextPDF Core.

Enterprise boundary note

The PKCS#11 token integration, its mechanism mapping, and its session handling are described at the behavior level only. The internal mechanism-mapping table, the internal session-recovery logic, and the post-quantum migration material are out of scope for the public surface and are not reproduced here.

Deployment boundary

NextPDF Enterprise integrates with a PKCS#11 token, an HSM, or a KMS. It does not itself 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 is responsible for token provisioning, PIN handling, slot configuration, network protection of a network-attached HSM, and the trust configuration. Key-protection responsibility follows NIST SP 800-57 Part 1 Rev.5 §5.5.2. NextPDF Enterprise does not expose token PIN handling, slot configuration internals, or vendor credential material in this documentation.

Legal-compliance boundary

It concerns cryptographic signing and hardware-security-module integration. The FIPS-mode policy is a compliance-assistance feature. Consult your own compliance and legal advisers for your regulatory obligations.

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.

Behavior contract

• The FIPS guard asserts each hash, signature OID, encryption algorithm, and key strength against the active preset and raises a typed violation on a disallowed choice.
• The power-on self-test runs once per process and refuses cryptographic services on a known-answer-test failure until reset.
• The PKCS#11 token signer requires ext-pkcs11; it raises a typed operation exception when the extension is absent.
• The signing path is fail-closed and never substitutes a weaker algorithm.

See also

• Security — NextPDF Enterprise (deep reference)
• Security — NextPDF Pro
• Signature — NextPDF Enterprise
• Accelerator — NextPDF Enterprise
• Security — NextPDF Core
• PAdES · HSM · PKCS#11 · FIPS mode · KMS — glossary terms.