HSM-backed signing

Spec PKCS#11 v3.1 Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 Spec Spec: FIPS 140-3 FIPS 140-3 Evidence § Standard-backed Evidence: Standard-backed

At a glance

A hardware security module (HSM) moves the signing key out of your process and behind a device that signs on request but never hands the key back. This page explains the PKCS#11 seam NextPDF signs through, exactly where the key boundary sits, and which parts of the result are the engine’s responsibility rather than the device’s or yours.

Why this matters

A signing key in process memory is exposed to anything that can read the process: a heap dump, a debugger, a logging mistake, or a dependency with a vulnerability. Once a private key is copied, every signature it ever made is in question, and you cannot make it secret again. The point of an HSM is that there is no copy to take.

Getting the boundary wrong is quietly expensive. A workflow that looks hardware-backed but pulls the key into memory to sign has the operational cost of an HSM and the risk profile of a software key. The distinction is not visible in the finished PDF, so it has to be designed in and verified, not assumed.

The short version

• The PKCS#11 standard defines a key object that is marked sensitive and non-extractable. Its private value cannot be revealed in plaintext outside the token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9
• NextPDF builds the PDF signature structure and the CMS container. It hands the bytes to be signed across the PKCS#11 seam and receives the signature back. The key never crosses that seam.
• The seam is a stable contract. The same contract is satisfied by a smart-card token, a USB HSM, a network HSM, and a cloud KMS. The engine code does not change between them.
• NextPDF is signing-engine software. The device’s hardware assurance, its validation status, the PIN policy, and the deployment are not things the engine certifies. It uses the device; it does not vouch for it.

How NextPDF approaches it

The seam, precisely

NextPDF separates assembling a signature from computing the signature value. Assembly is the engine’s job: place the signature field, reserve space in the file, compute the byte range, and build the CMS SignedData with its signed attributes. Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8

Computing the signature value is delegated. The engine defines a small signing-provider contract: it receives an opaque byte sequence (in practice the DER-encoded signed attributes), and it returns the raw signature octets. That contract is the seam. PDF and CMS knowledge stay on one side; the key stays on the other. A provider may hold that key in process for a local software key, in a cloud KMS, or on a hardware token through PKCS#11. The engine code above the seam is identical in every case. Only the provider behind it differs.

Where the boundary actually sits

PKCS#11 — the OASIS Cryptographic Token Interface, historically “Cryptoki” — is the standard C interface to hardware tokens. NextPDF’s hardware path talks PKCS#11 (directly, or through an OpenSSL command-line bridge for engine or provider deployments where the in-process binding cannot load a token).

The key object on the token is created with two attributes that define the boundary. When the key is marked sensitive, or marked non-extractable, certain private attributes cannot be revealed in plaintext outside the token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 The signing operation itself is a single token call — C_SignInit then C_Sign — performed by the device. Spec Spec: PKCS#11, v3.1 §5.10 PKCS#11 v3.1 §5.10 The plaintext NextPDF handles for the signing operation is the bytes to be signed. What comes back is the signature and the certificate. The private key is on neither path. That is the boundary, and the token enforces it, not the library.

1. Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
2. Step 2 of 4: RFC 5652 CMS SignedData — the signature container RFC 5652 CMS SignedData — the signature container
3. PKCS#11 v3.1 — token interface; sensitive, non-extractable key
4. Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent) FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Where a hardware-backed PDF signature is grounded, in order: the PDF carrier (ISO 32000-2 §12.8), the CMS container it holds, the token interface NextPDF signs through (PKCS#11), and the module-assurance standards that describe — but do not by themselves guarantee — the device behind it.

One PIN, one re-authentication

PKCS#11 lets a key require re-authentication for every use: when the CKA_ALWAYS_AUTHENTICATE attribute is set, the user must present the PIN again for each cryptographic operation, not once per session. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 NextPDF’s PKCS#11 path is written for this. The PIN is a sensitive parameter. It is not logged or serialized. When a session reports an existing login, NextPDF returns it to a clean state so the next signature gets a fresh PIN check. This matters for PIV-style tokens whose policy demands a PIN per signature. It is engine behavior that respects the device’s policy; it does not relax it.

What the evidence says

Evidence § Standard-backed Evidence: Standard-backed The non-extractable-key property is not a NextPDF claim. It is the PKCS#11 model: a key object whose CKA_SENSITIVE is true or CKA_EXTRACTABLE is false does not yield its private value in plaintext outside the token. Spec Spec: PKCS#11, v3.1 §10.9 PKCS#11 v3.1 §10.9 NextPDF’s contribution is to never need that value: it signs through the token’s C_Sign operation rather than asking for key material.

Evidence § Standard-backed Evidence: Standard-backed The PDF side is anchored in Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 . The byte-range digest is computed over the file excluding the signature value. The signature value placed in the Contents entry is a DER-encoded CMS SignedData object for public-key signatures. The HSM produces only the innermost signature octets. NextPDF builds everything around them and writes them into the structure the standard defines.

Evidence § Standard-backed Evidence: Standard-backed Device assurance is described by Spec Spec: FIPS 140-3 FIPS 140-3 and its base standard ISO/IEC 19790, which define four increasing qualitative security levels across eleven requirement areas — from algorithm specification to physical tamper evidence. These standards describe what a module must satisfy to claim a level. They are a property of the device and its validation, not of NextPDF, and — in the words of ISO/IEC 19790 itself — conformity is not by itself sufficient to ensure a module is secure in a given deployment.

Human-factors note: Human-factors note

This page deliberately states the boundary before the mechanism, and it puts the cost of getting it wrong near the top. In a safety-critical domain, the honest order is the warning first, then the how. A workflow that silently loads a key into memory fails in a way you do not see in the output, so the trap is named before the recipe. The badge row already tells you the page is standard-backed before you read a sentence of body text.

Practical example

The shape below is illustrative. It shows the seam, not a copy-and-paste deployment. The point is that the engine is handed a signer and never sees a key: the signer’s sign() is a call into the device.

<?php

declare(strict_types=1);

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Sign a PDF where the private key lives on a PKCS#11 token.
 *
 * `$hsm` is a hardware-backed signer. Its sign() delegates to the token;
 * the key never enters this process. Everything that makes the bytes a
 * valid PDF signature — field, byte range, CMS SignedData — is built by
 * the engine around the value the device returns.
 *
 * Token wiring (library path, slot, PIN, key label) is deployment
 * configuration and is intentionally out of scope here: those values are
 * operator-owned secrets, not library inputs to hardcode.
 */
function signWithToken(
    string $pdfPath,
    HsmSignerInterface $hsm,
): string {
    // The engine asks the signer only for: the certificate (to embed in
    // the CMS) and a signature over the bytes it computes. It never asks
    // for, and the contract never exposes, the private key.
    $certificateDer = $hsm->getCertificateDer();
    $chainDer       = $hsm->getCertificateChainDer();

    // Pseudocode for the engine's own assembly step: build the signature
    // dictionary + CMS SignedData, then hand the signed-attributes bytes
    // to $hsm->sign(...) and place the returned octets in /Contents.
    return nextpdf_sign_pdf(
        pdfPath: $pdfPath,
        signer: $hsm,
        certificateDer: $certificateDer,
        chainDer: $chainDer,
    );
}

Two honest notes about this shape. The in-process PKCS#11 binding is a separate PHP extension that standard PHP builds do not include. A hardware deployment installs and verifies it (or uses the OpenSSL command-line bridge) as part of the platform, not as an afterthought. And the algorithm the device is asked for must be one the key can actually perform. The engine refuses early when the configured algorithm has no mapping for the chosen provider rather than failing deep in a token call.

Common misconception

“Using an HSM means the signing is FIPS-validated.”

No. Confusing the two is the trap. An HSM is the place the key lives and the operation runs. FIPS 140-3 / ISO/IEC 19790 validation is a property the device (or a specific module configuration) may hold, established by a validation program — not something a calling library confers and not something NextPDF asserts on a device’s behalf. NextPDF is compatible with signing through a PKCS#11 device and its signing path has been tested with category-representative tokens. Whether a given deployment is FIPS-module-level validated depends entirely on the hardware, its certificate, and how it is configured and operated. Use the precise word for what you actually have.

Limits and boundaries

This page describes the seam and the standards it rests on. It is not a deployment guarantee, and the line is worth stating plainly:

• Engine responsibility. Build the signature field, reserve space, compute the byte range, assemble CMS SignedData, call the signing provider, and write a structurally correct signature per Spec Spec: ISO 32000-2, §12.8 ISO 32000-2 §12.8 . NextPDF’s hardware path is conformant to the PKCS#11 signing interface for this purpose.
• Device and operator responsibility. The hardware’s tamper resistance, its FIPS 140-3 / ISO/IEC 19790 validation status, key generation and custody, PIN policy, slot configuration, firmware, and physical security. None of these is something the engine certifies.
• Tested-with is not certified. That NextPDF has a verified path against representative token categories — smart-card, USB, network, and cloud-KMS shapes reached through the same PKCS#11 contract — is a compatibility statement. It is not a certification, a validated-module count, or a claim about your specific device. The hardware categories below are integration shapes through one standard interface. Treat them as “where the seam has been exercised”, never as a guarantee for a model you have not tested yourself.
• Post-quantum signing is experimental. Where the engine exposes post-quantum signing through a token it is opt-in, gated, and validated against mocks rather than post-quantum HSM firmware. The PAdES and AdES cryptographic-suite catalogues do not yet recognise those suites for long-term archival. Do not treat it as production-ready.

HSM-backed signing via PKCS#11 — edition availability

Edition	Availability
Core	○ Not in this edition. Core provides the signing engine and the signing-provider seam, with a local software-key provider.
Pro	○ Cloud key management — signing through managed KMS keys — is a Pro capability, described at the behaviour level only.
Enterprise	○ Available. Hardware-token signing through the PKCS#11 interface (and an OpenSSL command-line bridge for engine/provider deployments) is an Enterprise capability. Availability is a capability statement, not a certification of any device or deployment.

Integration shapes through one interface

These are shapes the PKCS#11 seam has been exercised against. The column is “what the integration looks like”, not “a validated, certified, or counted device list”.

Integration shape	How it is reached	Key boundary	Assurance is a property of
Smart-card / PIV token	PKCS#11 module; per-use PIN common	On the card; non-extractable	The card and its operator
USB HSM	PKCS#11 module	On the device; non-extractable	The device and its operator
Network / appliance HSM	PKCS#11 module to a network device	On the appliance; non-extractable	The appliance, its config, the operator
Cloud KMS	Managed-key provider (Pro)	In the cloud service; never returned	The cloud provider and its attestations
OpenSSL provider bridge	PKCS#11 via an OpenSSL bridge	On the token; non-extractable	The token and its operator

Mini-FAQ

Does the key ever enter the PHP process? No. For a non-extractable PKCS#11 key, the private value cannot be revealed in plaintext outside the token. NextPDF signs through the token’s operation and only ever sees the bytes to sign and the returned signature.

Is an HSM-backed signature different inside the PDF? No. The signature structure is the same CMS SignedData in the same Contents entry over the same byte range. The HSM changes where the signing happens, not the on-disk shape.

Can I claim FIPS compliance because I used an HSM through NextPDF? Only with care. NextPDF asserts nothing about a device’s FIPS status. Any such claim must come from the device’s own validation and how it is deployed, not from the fact that NextPDF called it.

What if the in-process PKCS#11 binding is unavailable? The engine reports that hardware signing is unavailable rather than silently falling back to a software key. An OpenSSL command-line bridge path exists for deployments where the in-process binding cannot load a token.

Related docs

• Qualified signatures, explained — what a hardware key is necessary but not sufficient for, and the roles NextPDF is not.
• How signatures sit in a PDF — the byte-range and signature-dictionary mechanism the HSM result is written into.
• Operating NextPDF in production — the operational surface a hardware-signing deployment takes on.

Glossary

• HSM (hardware security module) — a hardened device that holds keys and performs cryptographic operations so the key material never leaves it.
• PKCS#11 — the OASIS Cryptographic Token Interface standard (historically “Cryptoki”); the C interface NextPDF uses to talk to hardware tokens.
• Non-extractable key — a PKCS#11 key object whose private value cannot be revealed in plaintext outside the token (CKA_SENSITIVE true or CKA_EXTRACTABLE false).
• The seam — the signing-provider boundary in NextPDF: opaque bytes in, signature octets out. PDF and CMS knowledge sit above it; the key sits behind it.
• CMS SignedData — the Cryptographic Message Syntax structure (RFC 5652) that carries the signature and certificates inside the PDF.
• FIPS 140-3 / ISO/IEC 19790 — cryptographic-module security standards defining four qualitative levels; a property of a device and its validation, not of a calling library.