HSM-backed signing

Spec: ISO 32000-2, §12.8 Spec: FIPS 140-3 Evidence: Standard-backed

In een oogopslag

Een hardware security module (HSM) verplaatst de ondertekeningssleutel uit het proces naar een apparaat dat op verzoek ondertekent maar de sleutel nooit teruggeeft. Deze pagina legt uit via welk PKCS#11-raakvlak NextPDF ondertekent, waar de sleutelgrens precies ligt en voor welke onderdelen van het resultaat de engine verantwoordelijk is, in plaats van het apparaat of jijzelf.

Waarom dit van belang is

Een ondertekeningssleutel in het procesgeheugen wordt blootgesteld aan alles wat het proces kan lezen: een heap dump, een debugger, een logging-fout of een afhankelijkheid met een kwetsbaarheid. Zodra een private sleutel is gekopieerd, staat elke handtekening die ermee is gezet ter discussie, en je kunt hem niet opnieuw geheim maken. Het hele punt van een HSM is dat er geen kopie te maken valt.

De grens verkeerd leggen kost ongemerkt veel. Een workflow die er hardwarematig ondersteund uitziet maar de sleutel naar het geheugen haalt om te ondertekenen, heeft de operationele kosten van een HSM en het risicoprofiel van een softwaresleutel. Het onderscheid is niet zichtbaar in de uiteindelijke PDF, dus het moet worden ingebouwd en geverifieerd, niet verondersteld.

De korte versie

De PKCS#11-standaard definieert een sleutelobject dat als gevoelig en niet-extraheerbaar is gemarkeerd. De private waarde ervan kan niet in platte tekst buiten de token worden onthuld. Spec: PKCS#11, v3.1 §10.9
NextPDF bouwt de PDF-handtekeningstructuur en de CMS-container op. De engine geeft de te ondertekenen bytes door via het PKCS#11-raakvlak en ontvangt de handtekening terug. De sleutel passeert dat raakvlak nooit.
Het raakvlak is een stabiel contract. Hetzelfde contract wordt ingevuld door een smartcardtoken, een USB-HSM, een netwerk-HSM en een cloud-KMS. De engine-code verandert daartussen niet.
NextPDF is ondertekeningsengine-software. De hardwareborging van het apparaat, de validatiestatus ervan, het pinbeleid en de implementatie zijn geen zaken die de engine certificeert. De engine gebruikt het apparaat; hij staat er niet voor in.

Hoe NextPDF het aanpakt

Het raakvlak, precies

NextPDF scheidt het samenstellen van een handtekening van het berekenen van de handtekeningwaarde. Het samenstellen is de taak van de engine: het handtekeningveld plaatsen, ruimte in het bestand reserveren, het bytebereik berekenen en de CMS SignedData bouwen met de bijbehorende ondertekende attributen. Spec: ISO 32000-2, §12.8

Het berekenen van de handtekeningwaarde wordt gedelegeerd. De engine definieert een klein contract voor de ondertekeningsprovider: de provider ontvangt een ondoorzichtige bytereeks (in de praktijk de DER-gecodeerde ondertekende attributen) en geeft de ruwe handtekening-octetten terug. Dat contract is het raakvlak. PDF- en CMS-kennis blijven aan de ene kant; de sleutel blijft aan de andere kant. Een provider kan die sleutel in het proces bewaren voor een lokale softwaresleutel, in een cloud-KMS, of op een hardwaretoken via PKCS#11. De engine-code boven het raakvlak is in elk geval identiek. Alleen de provider erachter verschilt.

Waar de grens daadwerkelijk ligt

PKCS#11 — de OASIS Cryptographic Token Interface, vroeger “Cryptoki” — is de standaard C-interface naar hardwaretokens. Het hardwarepad van NextPDF spreekt PKCS#11 (rechtstreeks of via een OpenSSL-opdrachtregelbrug voor engine- of provider-implementaties waar de in-procesbinding geen token kan laden).

Het sleutelobject op de token wordt aangemaakt met twee attributen die de grens bepalen. Wanneer de sleutel als gevoelig of als niet-extraheerbaar is gemarkeerd, kunnen bepaalde private attributen niet in platte tekst buiten de token worden onthuld. Spec: PKCS#11, v3.1 §10.9 De ondertekeningsbewerking zelf is één enkele tokenaanroep — C_SignInit gevolgd door C_Sign — uitgevoerd door het apparaat. Spec: PKCS#11, v3.1 §5.10 De platte tekst die NextPDF voor de ondertekeningsbewerking verwerkt, bestaat uit de te ondertekenen bytes. Wat terugkomt zijn de handtekening en het certificaat. De private sleutel bevindt zich op geen van beide paden. Dat is de grens, en de token dwingt die af, niet de bibliotheek.

Step 1 of 4: ISO 32000-2 §12.8 — signature dictionary, ByteRange, Contents
Step 2 of 4: RFC 5652 CMS SignedData — the signature container
Step 4 of 4: FIPS 140-3 / ISO/IEC 19790 cryptographic module assurance (device-level, deployment-dependent)

Waar een hardwarematig ondersteunde PDF-handtekening op rust, in volgorde: de PDF-drager (ISO 32000-2 §12.8), de CMS-container die hij bevat, de tokeninterface waardoor NextPDF ondertekent (PKCS#11), en de standaarden voor moduleborging die het apparaat erachter beschrijven — maar dat op zichzelf niet garanderen.

Één pin, één herauthenticatie

PKCS#11 kan voor elk gebruik van een sleutel herauthenticatie vereisen: wanneer het CKA_ALWAYS_AUTHENTICATE-attribuut is ingesteld, moet de gebruiker de pin opnieuw aanbieden voor elke cryptografische bewerking, niet één keer per sessie. Spec: PKCS#11, v3.1 §10.9 Het PKCS#11-pad van NextPDF is hiervoor geschreven. De pin is een gevoelige parameter. Hij wordt niet gelogd of geserialiseerd. Wanneer een sessie een bestaande aanmelding meldt, zet NextPDF die terug naar een schone staat, zodat de volgende handtekening een nieuwe pincontrole krijgt. Dat is van belang voor PIV-achtige tokens waarvan het beleid een pin per handtekening eist. Het is engine- gedrag dat het beleid van het apparaat respecteert; het versoepelt het niet.

Wat het bewijs zegt

Evidence: Standard-backed De eigenschap van een niet-extraheerbare sleutel is geen claim van NextPDF. Het is het PKCS#11-model: een sleutelobject waarvan CKA_SENSITIVE waar is of CKA_EXTRACTABLE onwaar is, geeft zijn private waarde niet in platte tekst buiten de token vrij. Spec: PKCS#11, v3.1 §10.9 NextPDF zorgt ervoor dat die waarde nooit nodig is: de engine ondertekent via de C_Sign-bewerking van de token in plaats van om sleutelmateriaal te vragen.

Evidence: Standard-backed De PDF-kant is verankerd in Spec: ISO 32000-2, §12.8 . Het bytebereik-digest wordt berekend over het bestand exclusief de handtekeningwaarde. De handtekeningwaarde die in het Contents-item wordt geplaatst, is een DER-gecodeerd CMS SignedData-object voor handtekeningen met openbare sleutel. De HSM produceert alleen de binnenste handtekening-octetten. NextPDF bouwt alles eromheen en schrijft het in de structuur die de standaard definieert.

Evidence: Standard-backed Apparaatborging wordt beschreven door Spec: FIPS 140-3 en de onderliggende standaard ISO/IEC 19790, die vier oplopende kwalitatieve beveiligingsniveaus definiëren in elf vereistegebieden — van algoritmespecificatie tot detectie van fysieke manipulatie. Deze standaarden beschrijven waaraan een module moet voldoen om een niveau te claimen. Ze zijn een eigenschap van het apparaat en de validatie ervan, niet van NextPDF, en — in de woorden van ISO/IEC 19790 zelf — is conformiteit op zichzelf niet voldoende om te waarborgen dat een module veilig is in een bepaalde implementatie.

Praktisch voorbeeld

De onderstaande vorm is illustratief. Ze toont het raakvlak, geen kant-en-klare implementatie. Het punt is dat de engine een ondertekenaar aangereikt krijgt en nooit een sleutel ziet: de sign() van de ondertekenaar is een aanroep naar het apparaat.

<?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,
    );
}

Twee eerlijke opmerkingen over deze vorm. De in-proces PKCS#11-binding is een aparte PHP-extensie die standaard-PHP-builds niet bevatten. Een hardware-implementatie installeert en verifieert die (of gebruikt de OpenSSL-opdrachtregelbrug) als onderdeel van het platform, niet als een bijzaak. En het algoritme dat aan het apparaat wordt gevraagd, moet een algoritme zijn dat de sleutel daadwerkelijk kan uitvoeren. De engine weigert vroegtijdig wanneer het geconfigureerde algoritme geen toewijzing heeft voor de gekozen provider, in plaats van diep in een tokenaanroep te falen.

Veelvoorkomend misverstand

„Een HSM gebruiken betekent dat de ondertekening FIPS-gevalideerd is.”

Nee. Die twee door elkaar halen is de valkuil. Een HSM is de plek waar de sleutel leeft en de bewerking draait. FIPS 140-3 / ISO/IEC 19790-validatie is een eigenschap die het apparaat (of een specifieke moduleconfiguratie) kan bezitten, vastgesteld door een validatieprogramma — niet iets wat een aanroepende bibliotheek verleent en niet iets wat NextPDF namens een apparaat beweert. NextPDF is compatibel met ondertekenen via een PKCS#11-apparaat en het ondertekeningspad ervan is getest met categorie-representatieve tokens. Of een gegeven implementatie op FIPS-moduleniveau is gevalideerd, hangt volledig af van de hardware, het certificaat ervan, en hoe die wordt geconfigureerd en bediend. Gebruik de precieze term voor wat je daadwerkelijk hebt.

Beperkingen en grenzen

Deze pagina beschrijft het raakvlak en de standaarden waarop het rust. Het is geen implementatiegarantie, en het is de moeite waard om die scheidslijn expliciet te maken:

Verantwoordelijkheid van de engine. Het handtekeningveld bouwen, ruimte reserveren, het bytebereik berekenen, CMS SignedData samenstellen, de ondertekeningsprovider aanroepen en een structureel correcte handtekening schrijven conform Spec: ISO 32000-2, §12.8 . Het hardwarepad van NextPDF is voor dit doel conform de PKCS#11-ondertekeningsinterface.
Verantwoordelijkheid van apparaat en operator. De manipulatiebestendigheid van de hardware, de validatiestatus ervan voor FIPS 140-3 / ISO/IEC 19790, sleutelgeneratie en -bewaring, pinbeleid, slotconfiguratie, firmware en fysieke beveiliging. Geen van deze zaken certificeert de engine.
Getest-met is niet gecertificeerd. Dat NextPDF een geverifieerd pad heeft voor representatieve tokencategorieën — smartcard-, USB-, netwerk- en cloud-KMS-vormen die via hetzelfde PKCS#11-contract worden bereikt — is een compatibiliteitsverklaring. Het is geen certificering, geen telling van gevalideerde modules en geen claim over je specifieke apparaat. De onderstaande hardwarecategorieën zijn integratie-vormen via één standaardinterface. Behandel ze als “waar het raakvlak is beproefd”, nooit als garantie voor een model dat je zelf niet hebt getest.
Post-quantumondertekening is experimenteel. Waar de engine post-quantumondertekening via een token beschikbaar stelt, is dit opt-in, gated, en gevalideerd tegen mocks in plaats van post-quantum-HSM-firmware. De cryptografische-suitecatalogi van PAdES en AdES erkennen die suites nog niet voor langetermijnarchivering. Behandel het niet als productieklaar.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Niet beschikbaar in deze editie. Core biedt de ondertekeningsengine en het raakvlak voor de ondertekeningsprovider, met een lokale softwaresleutelprovider.
Pro	Cloudsleutelbeheer — ondertekenen via beheerde KMS-sleutels — is een Pro- capaciteit en wordt alleen op gedragsniveau beschreven.
Enterprise	Beschikbaar. Hardwaretoken-ondertekening via de PKCS#11-interface (en een OpenSSL-opdrachtregelbrug voor engine/provider-implementaties) is een Enterprise-capaciteit. Beschikbaarheid is een capaciteitsverklaring, geen certificering van enig apparaat of enige implementatie.

Integratievormen via één interface

Dit zijn vormen waartegen het PKCS#11-raakvlak is beproefd. De kolom beschrijft “hoe de integratie eruitziet”, niet “een gevalideerde, gecertificeerde of getelde apparaatlijst”.

Integratievorm	Hoe deze wordt bereikt	Sleutelgrens	Borging is een eigenschap van
Smartcard / PIV-token	PKCS#11-module; pin per gebruik is gangbaar	Op de kaart; niet-extraheerbaar	De kaart en de operator ervan
USB-HSM	PKCS#11-module	Op het apparaat; niet-extraheerbaar	Het apparaat en de operator ervan
Netwerk- / appliance-HSM	PKCS#11-module naar een netwerkapparaat	Op de appliance; niet-extraheerbaar	De appliance, de configuratie ervan, de operator
Cloud-KMS	Beheerde-sleutelprovider (Pro)	In de clouddienst; nooit teruggegeven	De cloudprovider en de attestaties ervan
OpenSSL-providerbrug	PKCS#11 via een OpenSSL-brug	Op de token; niet-extraheerbaar	De token en de operator ervan

Mini-FAQ

Komt de sleutel ooit in het PHP-proces? Nee. Voor een niet-extraheerbare PKCS#11-sleutel kan de private waarde niet in platte tekst buiten de token worden onthuld. NextPDF ondertekent via de bewerking van de token en ziet alleen de te ondertekenen bytes en de teruggegeven handtekening.

Is een hardwarematig ondersteunde handtekening anders in de PDF? Nee. De handtekeningstructuur is dezelfde CMS SignedData in hetzelfde Contents-item over hetzelfde bytebereik. De HSM verandert waar de ondertekening plaatsvindt, niet de vorm op schijf.

Kan ik FIPS-conformiteit claimen omdat ik een HSM via NextPDF heb gebruikt? Alleen met zorg. NextPDF beweert niets over de FIPS-status van een apparaat. Elke dergelijke claim moet voortkomen uit de eigen validatie van het apparaat en hoe het wordt ingezet, niet uit het feit dat NextPDF het heeft aangeroepen.

Wat als de in-proces PKCS#11-binding niet beschikbaar is? De engine meldt dat hardware-ondertekening niet beschikbaar is, in plaats van stilletjes terug te vallen op een softwaresleutel. Er bestaat een pad via een OpenSSL-opdrachtregelbrug voor implementaties waar de in-procesbinding geen token kan laden.

Gerelateerde documentatie

Gekwalificeerde handtekeningen, uitgelegd — waarvoor een hardwaresleutel noodzakelijk maar niet voldoende is, en welke rollen NextPDF niet vervult.
Hoe handtekeningen in een PDF zitten — het mechanisme voor bytebereik en handtekeningwoordenboek waarin het HSM-resultaat wordt geschreven.
NextPDF in productie gebruiken — het operationele oppervlak dat een hardware-ondertekeningsimplementatie met zich meebrengt.

Woordenlijst

HSM (hardware security module) — een gehard apparaat dat sleutels bewaart en cryptografische bewerkingen uitvoert, zodat het sleutelmateriaal het apparaat nooit verlaat.
PKCS#11 — de OASIS Cryptographic Token Interface-standaard (vroeger “Cryptoki”); de C-interface die NextPDF gebruikt om met hardwaretokens te communiceren.
Niet-extraheerbare sleutel — een PKCS#11-sleutelobject waarvan de private waarde niet in platte tekst buiten de token kan worden onthuld (CKA_SENSITIVE waar of CKA_EXTRACTABLE onwaar).
Het raakvlak — de grens van de ondertekeningsprovider in NextPDF: ondoorzichtige bytes erin, handtekening-octetten eruit. PDF- en CMS-kennis zitten erboven; de sleutel zit erachter.
CMS SignedData — de Cryptographic Message Syntax-structuur (RFC 5652) die de handtekening en certificaten in de PDF draagt.
FIPS 140-3 / ISO/IEC 19790 — beveiligingsstandaarden voor cryptografische modules die vier kwalitatieve niveaus definiëren; een eigenschap van een apparaat en de validatie ervan, niet van een aanroepende bibliotheek.