Signature appuyée sur un HSM

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

En bref

Un module matériel de sécurité (HSM) déplace la clé de signature hors de ton processus, derrière un périphérique qui signe à la demande sans jamais restituer la clé. Cette page explique le joint PKCS#11 par lequel NextPDF signe, l’emplacement exact de la frontière de la clé, et les parties du résultat qui relèvent du moteur plutôt que du périphérique ou de ta responsabilité.

Pourquoi c’est important

Une clé de signature présente dans la mémoire d’un processus peut être lue par tout ce qui peut lire ce processus : un vidage de tas, un débogueur, une erreur de journalisation, une dépendance vulnérable. Une fois qu’une clé privée est copiée, toutes les signatures qu’elle a déjà produites deviennent suspectes, et tu ne peux pas effacer la fuite. L’intérêt d’un HSM, c’est qu’il n’y a aucune copie à dérober.

Se tromper sur la frontière coûte cher, et souvent sans bruit. Un flux qui semble adossé au matériel mais qui charge la clé en mémoire pour signer a le coût opérationnel d’un HSM et le profil de risque d’une clé logicielle. La distinction n’est pas visible dans le PDF final ; elle doit donc être conçue et vérifiée, pas présumée.

La version courte

La norme PKCS#11 définit un objet clé marqué comme sensible et non extractible. Sa valeur privée ne peut pas être révélée en clair hors du jeton. Spec: PKCS#11, v3.1 §10.9
NextPDF construit la structure de signature PDF et le conteneur CMS. Il transmet les octets à signer au travers du joint PKCS#11 et reçoit la signature en retour. La clé ne franchit jamais ce joint.
Le joint est un contrat stable. Ce même contrat est satisfait par un jeton à carte à puce, un HSM USB, un HSM réseau et un KMS cloud. Le code du moteur ne change pas de l’un à l’autre.
NextPDF est un moteur logiciel de signature. L’assurance matérielle du périphérique, son statut de validation, la politique de code PIN et le déploiement ne sont pas des éléments que le moteur certifie. Il utilise le périphérique ; il ne se porte pas garant de lui.

Comment NextPDF l’aborde

Le joint, précisément

NextPDF sépare l’assemblage d’une signature du calcul de la valeur de signature. L’assemblage est le rôle du moteur : placer le champ de signature, réserver de l’espace dans le fichier, calculer la plage d’octets et construire le SignedData CMS avec ses attributs signés. Spec: ISO 32000-2, §12.8

Le calcul de la valeur de signature est délégué. Le moteur définit un petit contrat de fournisseur de signature : il reçoit une chaîne d’octets opaque (en pratique, les attributs signés encodés en DER) et renvoie les octets bruts de la signature. Ce contrat est le joint. D’un côté se trouvent la connaissance du PDF et de CMS ; de l’autre, une clé. Un fournisseur peut détenir cette clé en mémoire pour une clé logicielle locale, dans un KMS cloud, ou sur un jeton matériel au travers de PKCS#11. Le code du moteur au-dessus du joint est identique dans tous les cas. Seul le fournisseur situé derrière diffère.

Où se situe réellement la frontière

PKCS#11 — l’interface OASIS pour jetons cryptographiques, historiquement « Cryptoki » — est l’interface C standard vers les jetons matériels. Le chemin matériel de NextPDF parle PKCS#11 (directement, ou via un pont en ligne de commande OpenSSL pour les déploiements de moteur ou de fournisseur où la liaison intra-processus ne peut pas charger de jeton).

L’objet clé présent sur le jeton est créé avec deux attributs qui définissent la frontière. Lorsque la clé est marquée sensible, ou marquée non extractible, certains attributs privés ne peuvent pas être révélés en clair hors du jeton. Spec: PKCS#11, v3.1 §10.9 L’opération de signature elle-même est un appel unique au jeton — C_SignInit puis C_Sign — réalisé par le périphérique. Spec: PKCS#11, v3.1 §5.10 Le texte en clair qui entre dans NextPDF correspond aux octets à signer. Ce qui revient, c’est la signature et le certificat. La clé privée n’est sur aucun de ces chemins. C’est cela, la frontière : elle est imposée par le jeton, pas par la bibliothèque.

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)

Là où une signature PDF appuyée sur le matériel prend appui, dans l'ordre : le porteur PDF (ISO 32000-2 §12.8), le conteneur CMS qu'il contient, l'interface de jeton au travers de laquelle signe NextPDF (PKCS#11), et les normes d'assurance de module qui décrivent — mais ne garantissent pas à elles seules — le périphérique qui se trouve derrière.

Un PIN, une ré-authentification

PKCS#11 permet à une clé d’exiger une ré-authentification à chaque usage : lorsque l’ attribut CKA_ALWAYS_AUTHENTICATE est défini, l’utilisateur doit présenter le PIN de nouveau pour chaque opération cryptographique, et non une fois par session. Spec: PKCS#11, v3.1 §10.9 Le chemin PKCS#11 de NextPDF est écrit pour cela. Le PIN est un paramètre sensible. Il n’est ni journalisé ni sérialisé. Lorsqu’une session signale une connexion existante, NextPDF la ramène à un état propre afin que la signature suivante déclenche une nouvelle vérification du PIN. Cela compte pour les jetons de type PIV dont la politique exige un PIN par signature. C’est un comportement du moteur qui respecte la politique du périphérique ; il ne l’assouplit pas.

Ce que dit la preuve

Evidence: Standard-backed La propriété de clé non extractible n’est pas une affirmation de NextPDF. C’est le modèle PKCS#11 : un objet clé dont CKA_SENSITIVE est vrai ou CKA_EXTRACTABLE est faux ne livre pas sa valeur privée en clair hors du jeton. Spec: PKCS#11, v3.1 §10.9 La contribution de NextPDF est de n’avoir jamais besoin de cette valeur : il signe au travers de l’ opération C_Sign du jeton plutôt que de demander le matériel de clé.

Evidence: Standard-backed Le côté PDF est ancré dans Spec: ISO 32000-2, §12.8 . Le condensé de plage d’octets est calculé sur le fichier, à l’exclusion de la valeur de signature. La valeur de signature placée dans l’entrée Contents est un objet CMS SignedData encodé en DER pour les signatures à clé publique. Le HSM ne produit que les octets de signature les plus internes. NextPDF construit tout autour d’eux et les écrit dans la structure que définit la norme.

Evidence: Standard-backed L’assurance du périphérique est décrite par Spec: FIPS 140-3 et sa norme de base ISO/IEC 19790, qui définissent quatre niveaux de sécurité qualitatifs croissants répartis sur onze domaines d’exigences — de la spécification d’algorithme à la preuve physique d’altération. Ces normes décrivent ce qu’un module doit satisfaire pour revendiquer un niveau. Elles sont une propriété du périphérique et de sa validation, non de NextPDF, et — selon les termes mêmes d’ISO/IEC 19790 — la conformité n’est pas à elle seule suffisante pour garantir qu’un module est sûr dans un déploiement donné.

Exemple concret

La forme ci-dessous est illustrative. Elle montre le joint, pas un déploiement à copier-coller. L’essentiel est que le moteur reçoit un signataire et ne voit jamais de clé : le sign() du signataire est un appel vers le périphérique.

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

Deux remarques honnêtes au sujet de cette forme. La liaison PKCS#11 intra-processus est une extension PHP distincte que les versions standard de PHP **n’**incluent pas. Un déploiement matériel l’installe et la vérifie (ou utilise le pont en ligne de commande OpenSSL) comme élément de la plateforme, pas après coup. Et l’algorithme demandé au périphérique doit être un algorithme que la clé peut réellement exécuter. Le moteur refuse tôt lorsque l’algorithme configuré n’a aucune correspondance pour le fournisseur choisi, plutôt que d’échouer tout au fond d’un appel au jeton.

Idée fausse fréquente

« Utiliser un HSM signifie que la signature est validée FIPS. »

Ce n’est pas le cas, et confondre les deux est le piège. Un HSM est l’endroit où vit la clé et où s’exécute l’opération. La validation FIPS 140-3 / ISO/IEC 19790 est une propriété que le périphérique (ou une configuration de module spécifique) peut détenir, établie par un programme de validation — et non quelque chose qu’une bibliothèque appelante confère, ni quelque chose que NextPDF affirme au nom d’un périphérique. NextPDF est compatible avec la signature au travers d’un périphérique PKCS#11, et son chemin de signature a été testé avec des jetons représentatifs de chaque catégorie. Le fait qu’un déploiement donné soit validé au niveau module FIPS dépend entièrement du matériel, de son certificat et de la manière dont il est configuré et exploité. Emploie le mot précis pour ce que tu détiens réellement.

Limites et frontières

Cette page décrit le joint et les normes sur lesquelles il repose. Ce n’est pas une garantie de déploiement, et la limite mérite d’être énoncée clairement :

Responsabilité du moteur. Construire le champ de signature, réserver de l’espace, calculer la plage d’octets, assembler le SignedData CMS, appeler le fournisseur de signature et écrire une signature structurellement correcte conformément à Spec: ISO 32000-2, §12.8 . Le chemin matériel de NextPDF est conforme à l’interface de signature PKCS#11 à cette fin.
Responsabilité du périphérique et de l’opérateur. La résistance à l’altération du matériel, son statut de validation FIPS 140-3 / ISO/IEC 19790, la génération et la conservation des clés, la politique de code PIN, la configuration des emplacements, le micrologiciel et la sécurité physique. Rien de tout cela n’est certifié par le moteur.
Testé-avec n’est pas certifié. Le fait que NextPDF dispose d’un chemin vérifié face à des catégories de jetons représentatives — formats carte à puce, USB, réseau et KMS cloud atteints au travers du même contrat PKCS#11 — est une déclaration de compatibilité. Ce n’est pas une certification, un décompte de modules validés, ni une affirmation sur ton périphérique précis. Les catégories de matériel ci-dessous sont des formes d’intégration au travers d’une interface standard unique. Considère-les comme « là où le joint a été éprouvé », jamais comme une garantie pour un modèle que tu n’as pas testé toi-même.
La signature post-quantique est expérimentale. Lorsque le moteur expose la signature post-quantique au travers d’un jeton, elle est optionnelle, sous contrôle d’accès et validée face à des simulacres plutôt qu’à un micrologiciel de HSM post-quantique. Les catalogues de suites cryptographiques PAdES et AdES ne reconnaissent pas encore ces suites pour l’archivage à long terme. Ne la considère pas comme prête pour la production.

HSM-backed signing via PKCS#11 — edition availability
Edition	Availability
Core	Pas dans cette édition. Le cœur fournit le moteur de signature et le joint de fournisseur de signature, avec un fournisseur local de clé logicielle.
Pro	La gestion des clés dans le cloud — la signature au travers de clés KMS gérées — est une capacité Pro, décrite uniquement au niveau du comportement.
Enterprise	Disponible. La signature par jeton matériel au travers de l’interface PKCS#11 (et d’un pont en ligne de commande OpenSSL pour les déploiements engine/provider) est une capacité Enterprise. Cette disponibilité est une déclaration de capacité, non une certification d’un quelconque périphérique ou déploiement.

Formes d’intégration au travers d’une interface unique

Ce sont des formes face auxquelles le joint PKCS#11 a été éprouvé. La colonne indique « à quoi ressemble l’intégration », et non « une liste de périphériques validés, certifiés ou dénombrés ».

Forme d’intégration	Comment on l’atteint	Frontière de la clé	L’assurance est une propriété de
Carte à puce / jeton PIV	Module PKCS#11 ; PIN par usage courant	Sur la carte ; non extractible	La carte et son opérateur
HSM USB	Module PKCS#11	Sur le périphérique ; non extractible	Le périphérique et son opérateur
HSM réseau / appliance	Module PKCS#11 vers un périphérique réseau	Sur l’appliance ; non extractible	L’appliance, sa configuration, l’opérateur
KMS cloud	Fournisseur de clés gérées (Pro)	Dans le service cloud ; jamais restituée	Le fournisseur cloud et ses attestations
Pont fournisseur OpenSSL	PKCS#11 via un pont OpenSSL	Sur le jeton ; non extractible	Le jeton et son opérateur

Mini-FAQ

La clé entre-t-elle un jour dans le processus PHP ? Non. Pour une clé PKCS#11 non extractible, la valeur privée ne peut pas être révélée en clair hors du jeton. NextPDF signe au travers de l’opération du jeton et ne voit jamais que les octets à signer et la signature renvoyée.

Une signature appuyée sur un HSM est-elle différente à l’intérieur du PDF ? Non. La structure de signature est le même SignedData CMS dans la même entrée Contents sur la même plage d’octets. Le HSM change là où se produit la signature, pas sa forme sur le disque.

Puis-je revendiquer la conformité FIPS parce que j’ai utilisé un HSM au travers de NextPDF ? Seulement avec prudence. NextPDF n’affirme rien quant au statut FIPS d’un périphérique. Toute revendication de ce type doit provenir de la propre validation du périphérique et de la manière dont il est déployé, et non du fait que NextPDF l’a appelé.

Que se passe-t-il si la liaison PKCS#11 intra-processus est indisponible ? Le moteur signale que la signature matérielle est indisponible plutôt que de se rabattre silencieusement sur une clé logicielle. Un chemin via le pont en ligne de commande OpenSSL existe pour les déploiements où la liaison intra-processus ne peut pas charger de jeton.

Documents liés

Signatures qualifiées, expliquées — ce pour quoi une clé matérielle est nécessaire mais non suffisante, et les rôles que NextPDF n’occupe pas.
Comment les signatures s’inscrivent dans un PDF — le mécanisme de plage d’octets et de dictionnaire de signature dans lequel le résultat du HSM est écrit.
Exploiter NextPDF en production — la surface opérationnelle qu’assume un déploiement de signature matérielle.

Glossaire

HSM (module matériel de sécurité) — un périphérique durci qui détient les clés et réalise les opérations cryptographiques de sorte que le matériel de clé ne le quitte jamais.
PKCS#11 — la norme OASIS d’interface pour jetons cryptographiques (historiquement « Cryptoki ») ; l’interface C que NextPDF utilise pour dialoguer avec les jetons matériels.
Clé non extractible — un objet clé PKCS#11 dont la valeur privée ne peut pas être révélée en clair hors du jeton (CKA_SENSITIVE vrai ou CKA_EXTRACTABLE faux).
Le joint — la frontière du fournisseur de signature dans NextPDF : octets opaques en entrée, octets de signature en sortie. La connaissance du PDF et de CMS se trouve au-dessus ; la clé se trouve derrière.
SignedData CMS — la structure Cryptographic Message Syntax (RFC 5652) qui porte la signature et les certificats à l’intérieur du PDF.
FIPS 140-3 / ISO/IEC 19790 — normes de sécurité des modules cryptographiques définissant quatre niveaux qualitatifs ; une propriété d’un périphérique et de sa validation, non d’une bibliothèque appelante.