Enterprise editie

Ondertekening met hardware security module (PKCS#11)

In het kort

NextPDF Enterprise ondertekent een PDF met een sleutel die binnen een hardware security module (HSM) wordt bewaard. Je richt de signer op een PKCS#11-token — een smartcard, een Universal Serial Bus (USB)-token of een netwerkgekoppelde HSM — en de ondertekeningsbewerking draait op het apparaat. De privésleutel verlaat nooit de tokengrens. Deze pagina is op gedragsniveau: ze beschrijft wat de signer doet, wat je aanlevert en waar sleutelbewaring ophoudt de verantwoordelijkheid van NextPDF te zijn.

De HSM-signer wordt opgelost via het Core-signer-contract, zodat je applicatie afhangt van het contract, niet van het concrete Enterprise-type. Hij verlengt hetzelfde Cryptographic Message Syntax (CMS)-ondertekeningspad dat Core gebruikt, behalve dat de cryptografische bewerking aan het token wordt gedelegeerd.

Vereisten staan in de frontmatter en worden herhaald onder Vereisten, zodat je niet middenin de taak verrast wordt.

Beschikbaarheid en licentiëring

Deze mogelijkheid wordt geleverd in NextPDF Enterprise (nextpdf/enterprise) en activeert met een Enterprise-tier-license-envelope. Een deployment zonder die entitlement laadt de classes van de mogelijkheid niet. Vergelijk edities en verkrijg een licentie.

NextPDF Core levert een software-CMS-signer die de sleutel in-process bewaart of er een accepteert via het Core-ondertekeningsstrategie-contract; NextPDF Pro voegt remote en cloud key-management-service (KMS)-ondertekeningsstrategieën toe. Hardware-sleutelbewaring via PKCS#11 is een Enterprise-mogelijkheid en wordt niet geleverd door Core of Pro.

Wat deze mogelijkheid doet

Een PKCS#11-token stelt cryptografische objecten — certificaten en privésleutels — beschikbaar achter een vendor shared library. De Enterprise-signer adapteert die bibliotheek:

Hij opent de shared library van het token één keer per proces en cachet de module-handle, omdat PKCS#11 vereist dat de module exact één keer per proces wordt geïnitialiseerd.
Hij opent een sessie op het geconfigureerde slot en logt in met de aangeleverde PIN. De login authenticeert de gebruiker vóór elke privésleutelbewerking, conform PKCS#11 v3.1 §5.6.8.
Hij lokaliseert het ondertekeningscertificaat op het token op label, leest het certificaat in Distinguished Encoding Rules (DER)-vorm en detecteert het publieke-sleutelalgoritme.
Op ondertekeningsmoment lokaliseert hij de privésleutel op label — die op sommige tokens kan verschillen van het certificaatlabel — en vraagt hij het token de handtekening te berekenen. De te ondertekenen gegevens worden doorgegeven; de sleutel blijft op het apparaat.

De signer ondersteunt RSA met PKCS#1 v1.5-padding (SHA-256, SHA-384, SHA-512), RSA met Probabilistic Signature Scheme (PSS)-padding waarbij de saltlengte gelijk is aan de digestlengte, en Elliptic Curve Digital Signature Algorithm (ECDSA) met SHA-256, SHA-384 en SHA-512. De ECDSA-curve en -digest worden conventioneel gekoppeld — P-256 met SHA-256, P-384 met SHA-384, P-521 met SHA-512 — volgens de aanbevolen koppeling in RFC 5480. Een token retourneert een ECDSA-handtekening als een ruwe concatenatie van de twee integers; de signer converteert die naar de DER-gecodeerde vorm die PDF en OpenSSL verwachten.

Voor handtekeninggeneratie zijn een RSA-sleutel van minstens 2048 bits en een ECDSA-curve-order van minstens 224 bits de acceptabele minima conform NIST SP 800-131A Rev.2 §3. Provision je tokensleutel op of boven die groottes.

Er bestaat een alternatief OpenSSL-engine-pad voor engine-backed tokens. Op OpenSSL 3.x stelt de PHP OpenSSL-extensie de engine application programming interface (API) niet beschikbaar, dus de engine-class is gedeprecieerd; de ondersteunde engine-backed route draait de OpenSSL-command-line-binary. Geef de voorkeur aan het directe PKCS#11-pad waar je token een PKCS#11-bibliotheek heeft.

Waarom het zo werkt

De doorslaggevende beslissing is dat de privésleutel het token nooit verlaat. Daarom delegeert de signer de cryptografische bewerking aan het apparaat en verplaatst hij alleen de te ondertekenen gegevens over de PKCS#11-naad. Hij leest of reconstrueert nooit sleutelmateriaal in het PHP-geheugen. Hij wordt opgelost via het Core HsmSignerInterface-contract in plaats van een concreet Enterprise-type, zodat ondertekeningscode identiek is of de sleutel nu in software, een cloud-KMS of een hardware-token leeft. Hij cachet de module-handle één keer per proces omdat PKCS#11 elke module exact één keer per proces initialiseert, en converteert vervolgens de ruwe ECDSA-uitvoer van het token naar DER zodat validators de codering zien die ze verwachten. Bewaring, niet gemak, bepaalt de vorm: de vertrouwensgrens blijft aan de apparaatrand.

Ontwerpachtergrond: Ondertekenen met HSM-ondersteuning.

Vereisten

Voordat je met een HSM ondertekent, bevestig elk item:

Installeer NextPDF Core en het Enterprise-pakket: composer require nextpdf/core:^3 en composer require nextpdf/enterprise.
Houd een actieve NextPDF Enterprise-licentie; los het pakket op tegen je licentiereferenties op Private Packagist.
Installeer de PKCS#11 shared library van de tokenvendor op de host (bijvoorbeeld een .so op Linux of een .dll op Windows) en noteer het absolute pad, het slotnummer en de objectlabels.
Laad de ext-pkcs11 PHP-extensie. Ze is niet gebundeld met standaard-PHP en moet apart worden geïnstalleerd. De signer-constructor werpt een getypeerde operatiefout wanneer de extensie afwezig is.

Configuratie

Lever deze invoer aan de signer:

Bibliotheekpad — het absolute pad naar de PKCS#11 shared library van de vendor.
Slot-identificator — het tokenslotnummer, doorgaans 0.
PIN — de token-PIN. Behandel die als een geheim: lever die vanuit je secret manager, nooit vanuit broncode of logs. De signer markeert de PIN-parameter als gevoelig zodat die wordt uitgesloten van stack traces en serialisatie.
Certificaatlabel — het label van het certificaatobject op het token.
Sleutellabel — het label van het privésleutelobject, wanneer het verschilt van het certificaatlabel.
Chain — optionele tussenliggende certificaten in DER-vorm, wanneer het token deze niet bevat.

Controleer tokenbeschikbaarheid voordat je de signer construeert. Constructie leest het certificaat van het token, dus een verkeerd geconfigureerd slot of label faalt snel met een getypeerde fout in plaats van op ondertekeningsmoment.

Stap voor stap

Bevestig dat de runtime PKCS#11 ondersteunt door extensiebeschikbaarheid te controleren. Construeer de signer niet wanneer de extensie afwezig is.
Lees de PIN uit je secret manager in een variabele die nooit wordt gelogd.
Construeer de HSM-signer met het bibliotheekpad, slot, PIN en labels. Constructie logt in en leest het certificaat.
Geef de signer door aan de Core-ondertekeningsorchestrator via HsmSignerInterface. De orchestrator berekent de byte range, bouwt de CMS-signed-attributes, geeft de gegevens aan het token en assembleert de ondertekende PDF.
Vang de meest specifieke fout, log een structureel bericht zonder de PIN, en gooi opnieuw.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\HsmSignerInterface;

/**
 * Build a hardware-token signer only when the runtime supports it.
 *
 * The concrete PKCS#11 signer is resolved through the Core contract so the
 * caller depends on the interface, not the Enterprise implementation type.
 * The PIN arrives from a secret resolver; it is never written to source.
 *
 * @param callable(): bool                $pkcs11Available Reports ext-pkcs11 availability.
 * @param callable(): HsmSignerInterface  $signerFactory   Builds the configured token signer.
 *
 * @throws \RuntimeException When the PKCS#11 extension is not loaded.
 *
 * @return HsmSignerInterface The token signer, ready for the Core orchestrator.
 */
function resolveHsmSigner(callable $pkcs11Available, callable $signerFactory): HsmSignerInterface
{
    if ($pkcs11Available() !== true) {
        throw new \RuntimeException(
            'PKCS#11 signing requires the ext-pkcs11 extension; install it before signing.',
        );
    }

    return $signerFactory();
}

De productiebedrading — de exacte lijst van constructorargumenten en de getypeerde exceptietypen — is gedocumenteerd in de HSM-diepe referentie.

<?php

declare(strict_types=1);

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

use NextPDF\Contracts\HsmSignerInterface;
use NextPDF\Exception\NextPdfException;
use Psr\Log\LoggerInterface;

final readonly class HsmSigningService
{
    public function __construct(
        private HsmSignerInterface $signer,
        private LoggerInterface $logger,
    ) {}

    /**
     * Sign data on the token through the Core HSM contract.
     *
     * The byte range is computed by the engine, never accepted from the
     * caller. The token performs the signing operation; the private key
     * does not leave the device.
     *
     * @param string $data      The bytes the orchestrator hands to the token.
     * @param string $algorithm The OpenSSL-style signing algorithm identifier.
     *
     * @throws NextPdfException When the token operation fails.
     *
     * @return string The raw signature bytes returned by the token.
     */
    public function sign(string $data, string $algorithm): string
    {
        try {
            return $this->signer->sign($data, $algorithm);
        } catch (NextPdfException $e) {
            // Structural message only — never the PIN or key material.
            $this->logger->error('HSM signing failed', ['reason' => $e->getMessage()]);

            throw $e;
        }
    }
}

Verificatie

Bevestig het resultaat zoals een verifier dat zou doen:

Lees het signer-certificaat en de chain in DER-vorm terug van de signer en bevestig dat ze overeenkomen met het op het token geprovisioneerde certificaat.
Open de ondertekende PDF in een validator die is geconfigureerd met je trust anchors en bevestig dat de handtekening wordt gerapporteerd als cryptografisch intact. Een geproduceerde handtekening is geen geverifieerde handtekening; de vertrouwensbeslissing behoort toe aan de verifier en zijn trust anchors, niet aan de producent.
Bevestig voor een ECDSA-handtekening dat de ingebedde handtekening DER-gecodeerd is — de signer converteert de ruwe uitvoer van het token voor je, dus een validator die de ruwe geconcateneerde vorm afwijst, zou de ingebedde handtekening alsnog moeten accepteren.
Bevestig dat geen PIN, tokenlabel of sleutelmateriaal in je applicatielogs verschijnt.

Beveiliging en compliance

De sleutel blijft op het token. De te ondertekenen gegevens worden aan het token gegeven; de ondertekeningsbewerking draait binnen de tokengrens. De privésleutel wordt nooit in het PHP-geheugen geladen.
De PIN is een geheim. Het is een gevoelige constructorparameter, uitgesloten van logs en serialisatie. Lever die vanuit een secret manager. Herhaalde mislukte herauthenticatie kan de PIN op het token vergrendelen; het token, niet NextPDF, dwingt dat beleid af.
Fail-closed. Een token- of HSM-fout werpt een getypeerde exceptie. De signer produceert geen ongetekend of deels ondertekend resultaat en vervangt nooit door een zwakker algoritme.
Algoritmesterkte. Provision RSA-sleutels van minstens 2048 bits en ECDSA-curves van minstens 224-bit order, de acceptabele minima voor handtekeninggeneratie conform NIST SP 800-131A Rev.2 §3.
Post-quantum-ondertekening is experimenteel en standaard uit. Er bestaat een post-quantum-pad achter een expliciete opt-in-vlag. Standaard PDF Advanced Electronic Signatures (PAdES)-langetermijnarchiefprofielen herkennen nog geen post-quantum-suites, en de meeste viewers wijzen ze af bij validatie. Schakel het niet in voor productie-PAdES-handtekeningen.

Deze pagina betreft cryptografische ondertekening en hardware-security-module-integratie. Elke normatieve bron is geparafraseerd; er wordt geen normatieve tekst gereproduceerd. ### Sleutelbewaringsgrens

NextPDF Enterprise integreert met een PKCS#11-token of HSM. Het slaat de ondertekeningssleutel niet op, genereert die niet en garandeert de beveiliging ervan niet. Sleutelbeveiliging hangt af van het token of de HSM, de implementatie en de operator — niet van NextPDF Enterprise alleen. Je bent verantwoordelijk voor tokenprovisioning, PIN-afhandeling, slotconfiguratie en netwerkbescherming van een netwerkgekoppelde HSM.

Foutafhandeling

Extensie afwezig. Het construeren van de PKCS#11-signer werpt een getypeerde operatie-exceptie wanneer ext-pkcs11 niet is geladen. Controleer eerst de beschikbaarheid.
Certificaat of sleutel niet gevonden op label. Constructie of ondertekening werpt een getypeerde exceptie die het ontbrekende object benoemt. Bevestig het label en slot.
Al ingelogd. Wanneer meerdere signer-instances een gecachede module voor hetzelfde slot delen, logt de signer uit en weer in om een verse PIN-verificatie te leveren — vereist door personal-identity-verification-tokens met een “PIN every time”-beleid.
Niet-ondersteund algoritme. Het aanvragen van een algoritme dat de signer niet mapt, werpt een argumentfout in plaats van te ondertekenen met een vervanging.
Netwerk-HSM onbereikbaar. Een netwerk- of apparaatfout werpt een getypeerde exceptie; de signer produceert nooit stilzwijgend een ongetekend document.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-classes, mechanismetabellen, runbook-bestandsnamen en ticketprefixen vallen buiten de scope.

Zie ook

HSM signing — reference — de diepe referentie voor de PKCS#11-signer.
Security — NextPDF Enterprise — het gecombineerde Enterprise-beveiligingsoppervlak.
Signature — NextPDF Enterprise — PAdES B-LT- en B-LTA-langetermijnproducer.
FIPS 140 cryptografisch beleid — het FIPS-modusbeleid en de zelftest-guard.
Cloud KMS signing — NextPDF Pro — AWS-, Azure- en GCP-key-management-service-strategieën.
Security / Signing (Core) — de Core-CMS-signer en het ondertekeningsstrategie-contract.
HSM · PKCS#11 · CMS · ECDSA — woordenlijsttermen.