1. IronPDF
  2. Guides pratiques
  3. Signature de PDF avec HSM

Comment signer numériquement des PDF avec C## ; en utilisant HSM

Curtis Chau
Curtis Chau
Mis à jour:
This article was translated from English: Does it need improvement?
Translated
View the article in English

IronPDF permet la signature sécurisée de PDF à l'aide de modules de sécurité matériels (HSM) via l'API PKCS#11, où les clés privées ne quittent jamais le dispositif physique, offrant une sécurité de niveau bancaire pour les applications critiques nécessitant des signatures numériques infalsifiables.

Démarrage rapide : signer un PDF avec HSM en C#

  1. Installez IronPDF via NuGet : Install-Package IronPdf
  2. Configurez votre dispositif HSM (ou utilisez SoftHSM pour les tests)
  3. Créez un UsbPkcs11HsmSigner avec vos informations d'identification HSM :

    Nuget IconCommencez dès maintenant à créer des PDF avec NuGet :

    1. Installez IronPDF avec le gestionnaire de packages NuGet

      PM > Install-Package IronPdf

    2. Copiez et exécutez cet extrait de code.

      var hsmSigner = new UsbPkcs11HsmSigner(libraryPath, pin, tokenLabel, keyLabel);

    3. Déployez pour tester sur votre environnement de production.

      Commencez à utiliser IronPDF dans votre projet dès aujourd'hui grâce à un essai gratuit.
      arrow pointer
  4. Générez votre PDF et signez-le : 
    var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>");
pdf.SignAndSave("signed.pdf", hsmSigner);
    var pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>");
pdf.SignAndSave("signed.pdf", hsmSigner);
    Dim pdf = renderer.RenderHtmlAsPdf("<h1>Document</h1>")
pdf.SignAndSave("signed.pdf", hsmSigner)
    $vbLabelText   $csharpLabel
  5. Vérifiez la signature dans votre visionneuse PDF

L'ajout d'une signature à un document PDF est une exigence courante dans de nombreuses applications. Cependant, les applications critiques exigent une sécurité accrue, où la clé ne peut pas être modifiée. Une opération de signature normale avec un fichier .pfx, c'est comme avoir un passe-partout chez soi. L'application charge la clé en mémoire pour signer le document. Si l'ordinateur est compromis, la clé peut être volée.

Une alternative plus sûre consiste à utiliser un module de sécurité matériel (HSM). Avec un HSM (comme une clé USB), la clé privée est générée à l'intérieur de l'appareil et ne peut pas le quitter.

Ce processus revient à apporter le document à une banque. L'application fournit un code PIN et le HSM introduit le document dans la chambre forte, l'estampille avec la clé et renvoie le document estampillé. La clé ne quitte jamais le coffre. Cette solution offre une sécurité supplémentaire, car la clé ne peut être ni copiée ni volée.

## Comment signer numériquement des PDF avec HSM
  1. Téléchargez la bibliothèque IronPDF C# pour signer les PDF avec HSM
  2. Importez votre HSM existant ou simulez-le avec d'autres bibliothèques
  3. Créez un nouvel objet UsbPkcs11HsmSigner
  4. Signez et enregistrez le PDF avec SignAndSave
  5. Vérifiez la sortie et le certificat PDF à l'aide d'une visionneuse PDF

Comment signer des PDF avec un HSM?

La signature avec un HSM nécessite généralement un périphérique physique, tel qu'un jeton USB, avec lequel l'application interagit. IronPDF est compatible avec ces opérations, car la bibliothèque et les HSM standard utilisent PKCS#11 comme API commune. À des fins de démonstration, ce guide utilise un HSM simulé au lieu d'un HSM physique.

Cette simulation ne doit pas être utilisée dans des environnements de production ou de test en direct. Utilisez plutôt votre véritable HSM. Pour les environnements de production, envisagez de mettre en œuvre des fonctions de sécurité PDF supplémentaires telles que la protection par mot de passe et les autorisations parallèlement à la signature IronPDF pour une protection complète des documents.

Pour exécuter cette simulation, vous devez d'abord installer SoftHSM , OpenSSL et OpenSC afin de générer la clé et le jeton nécessaires. Pour plus d'informations sur l'utilisation de SoftHSM, consultez leur dépôt public GitHub.

Avant de mettre en œuvre la signature HSM, assurez-vous d'avoir correctement installé IronPDF et configuré votre clé de licence pour une utilisation en production.

Commencez par créer un PDF à partir d'une chaîne HTML. Dans l'exemple ci-dessous, nous définissons les chemins d'accès et les informations d'identification de notre SoftHSM simulé. Cela inclut de fournir le chemin d'accès absolu au fichier de bibliothèque SoftHSM .dll et au fichier de certificat .crt que vous avez créé.

Ensuite, indiquez le chemin de sortie, qui dans ce cas est output.pdf.

Définissez trois chaînes de caractères : hsmTokenLabel, hsmPin et hsmKeyLabel. Ces chaînes de caractères sont sensibles à la casse et doivent correspondre exactement aux informations d'identification que vous avez créées lors de la génération du jeton et du certificat avec SoftHSM. Ensuite, initialisez l'objet UsbPkcs11HsmSigner, en transmettant le chemin d'accès à la bibliothèque SoftHSM, le PIN, l'étiquette du jeton et l'étiquette de la clé en tant que paramètres.

En outre, créez une PdfSignatureImage pour ajouter une représentation visuelle de la signature sur le document. Enfin, appelez SignAndSave, qui utilise le hsmSigner pour signer le document et l'enregistrer dans le chemin de sortie spécifié.

À quoi ressemble le code de signature HSM?

:path=/static-assets/pdf/content-code-examples/how-to/signing-with-hsm.cs
using IronPdf;
using IronPdf.Signing;
using IronSoftware.Pdfium.Signing;
using System.Drawing;

ChromePdfRenderer renderer = new ChromePdfRenderer();
PdfDocument pdf = renderer.RenderHtmlAsPdf("<h1>Testing</h1>");

// Define Paths and Credentials
string softhsmLibraryPath = @"D:\SoftHSM2\lib\softhsm2-x64.dll";
// These MUST match what you created
string hsmTokenLabel = "MyTestToken";
string hsmPin = "123456";
string hsmKeyLabel = "my-key"; // The label for the key *inside* the token

// Create the HsmSigner object.
UsbPkcs11HsmSigner hsmSigner = new UsbPkcs11HsmSigner(
    softhsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel
);

// Create the Signature Image
string signatureImagePath = "IronSoftware.png";
PdfSignatureImage sigImage = new PdfSignatureImage(signatureImagePath, 0, new Rectangle(50, 50, 150, 150));

// Sign PDF with HSM
pdf.SignAndSave("signedWithHSM.pdf", hsmSigner);
Imports IronPdf
Imports IronPdf.Signing
Imports IronSoftware.Pdfium.Signing
Imports System.Drawing

Dim renderer As New ChromePdfRenderer()
Dim pdf As PdfDocument = renderer.RenderHtmlAsPdf("<h1>Testing</h1>")

' Define Paths and Credentials
Dim softhsmLibraryPath As String = "D:\SoftHSM2\lib\softhsm2-x64.dll"
' These MUST match what you created
Dim hsmTokenLabel As String = "MyTestToken"
Dim hsmPin As String = "123456"
Dim hsmKeyLabel As String = "my-key" ' The label for the key *inside* the token

' Create the HsmSigner object.
Dim hsmSigner As New UsbPkcs11HsmSigner(softhsmLibraryPath, hsmPin, hsmTokenLabel, hsmKeyLabel)

' Create the Signature Image
Dim signatureImagePath As String = "IronSoftware.png"
Dim sigImage As New PdfSignatureImage(signatureImagePath, 0, New Rectangle(50, 50, 150, 150))

' Sign PDF with HSM
pdf.SignAndSave("signedWithHSM.pdf", hsmSigner)
$vbLabelText   $csharpLabel

Le UsbPkcs11HsmSigner prend en outre deux paramètres facultatifs : digestAlgorithm et signingAlgorithm. Par défaut, ils sont configurés sur SHA256 et RSA .

Travailler avec différentes configurations HSM

Différents dispositifs HSM peuvent nécessiter des configurations spécifiques. Voici un exemple montrant comment configurer le signataire avec des algorithmes personnalisés et gérer des signatures multiples :

// Configure with custom algorithms
var customHsmSigner = new UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm: IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm: IronPdf.Signing.SigningAlgorithm.RSA
);

// Apply signature with custom location and reason
var signatureOptions = new SignatureOptions
{
    SignerName = "Corporate Signing Authority",
    Location = "Company Headquarters",
    Reason = "Contract Approval"
};

// Load existing PDF for signing
var existingPdf = PdfDocument.FromFile("contract.pdf");
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions);
// Configure with custom algorithms
var customHsmSigner = new UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm: IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm: IronPdf.Signing.SigningAlgorithm.RSA
);

// Apply signature with custom location and reason
var signatureOptions = new SignatureOptions
{
    SignerName = "Corporate Signing Authority",
    Location = "Company Headquarters",
    Reason = "Contract Approval"
};

// Load existing PDF for signing
var existingPdf = PdfDocument.FromFile("contract.pdf");
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions);
Imports IronPdf

' Configure with custom algorithms
Dim customHsmSigner As New UsbPkcs11HsmSigner(
    hsmLibraryPath,
    hsmPin,
    hsmTokenLabel,
    hsmKeyLabel,
    digestAlgorithm:=IronPdf.Signing.DigestAlgorithm.SHA512,
    signingAlgorithm:=IronPdf.Signing.SigningAlgorithm.RSA
)

' Apply signature with custom location and reason
Dim signatureOptions As New SignatureOptions With {
    .SignerName = "Corporate Signing Authority",
    .Location = "Company Headquarters",
    .Reason = "Contract Approval"
}

' Load existing PDF for signing
Dim existingPdf As PdfDocument = PdfDocument.FromFile("contract.pdf")
existingPdf.SignAndSave("contract-signed.pdf", customHsmSigner, signatureOptions)
$vbLabelText   $csharpLabel

Cette approche est particulièrement utile lorsque vous travaillez avec des exemples de signatures numériques qui nécessitent des normes de conformité spécifiques ou lorsque vous devez ajouter des métadonnées pour suivre les détails de la signature.

Quels sont les problèmes courants de configuration du HSM ?

Si vous rencontrez l'erreur affichée ci-dessous lors de l'exécution de l'exemple de code, suivez ces étapes de dépannage pour déboguer et vérifier votre configuration. Pour obtenir une aide supplémentaire sur les questions relatives aux signatures numériques, consultez notre guide de dépannage des signatures numériques.

Cette erreur CKR_GENERAL_ERROR se produit généralement lorsque le programme ne trouve pas le fichier de configuration SoftHSM ou lorsque l'application .NET s'exécute en tant que processus 32 bits alors que la bibliothèque SoftHSM est en 64 bits.

Erreur d'initialisation PKCS#11 HSM affichant CHR_GENERAL_ERROR dans la sortie de la console avec trace de pile complète

Changer la plateforme cible

Une cause fréquente de cette erreur est une incompatibilité d'architecture. Votre application C# doit s'exécuter en tant que processus 64 bits pour correspondre à la bibliothèque 64 bits de SoftHSM (softhsm2-x64.dll). Dans les propriétés de votre projet Visual Studio, modifiez la cible Plateforme de "Toute unité centrale" ou "x86" à x64 pour assurer la compatibilité.

Configuration de construction de Visual Studio montrant que la cible de la plate-forme est définie sur l'architecture x64 avec des symboles de compilation conditionnelle

Configuration de la variable d'environnement

Une autre cause fréquente est que le programme ne trouve pas le fichier .conf dans SoftHSM. Vous devez indiquer à la bibliothèque où chercher en définissant une variable d'environnement système. Créez une nouvelle variable nommée SOFTHSM2_CONF et définissez sa valeur sur le chemin complet de votre fichier de configuration (par exemple, D:\SoftHSM2\etc\softhsm2.conf). N'oubliez pas de redémarrer Visual Studio après avoir effectué les modifications.

Boîte de dialogue Windows System Variables avec la variable d'environnement SOFTISM2_CONF en surbrillance montrant le chemin de configuration du HSM

En outre, vous pouvez vérifier si la variable est trouvée en ajoutant cette ligne :

Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");
Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable("SOFTHSM2_CONF")}");
Console.WriteLine($"Verifying variable: {Environment.GetEnvironmentVariable(""SOFTHSM2_CONF"")}")
$vbLabelText   $csharpLabel

Si la sortie de la console est vide, c'est que le programme ne trouve pas la variable d'environnement. Vous devez le configurer, redémarrer Visual Studio ou votre ordinateur, puis réessayer.

Bonnes pratiques pour le déploiement d'un HSM de production

Lorsque vous déployez des PDF signés HSM dans des environnements de production, tenez compte de ces mesures de sécurité supplémentaires :

  1. Audit Logging : mettre en place une journalisation complète pour toutes les opérations HSM afin de maintenir la conformité et de suivre l'accès
  2. Gestion des certificats : Mettez régulièrement à jour et faites pivoter les certificats conformément aux politiques de sécurité de votre organisation
  3. Procédures de sauvegarde : établir des procédures de sauvegarde et de récupération appropriées pour les configurations HSM
  4. Optimisation des performances : Contrôle des performances de signature et mise en œuvre de stratégies de mise en cache pour les certificats fréquemment consultés

Ces pratiques complètent le flux de travail standard de signature des PDF et garantissent que votre infrastructure de sécurité des documents reste robuste et conforme aux normes du secteur.

Questions Fréquemment Posées

Qu'est-ce que la signature HSM et en quoi diffère-t-elle de la signature PDF classique ?

La signature HSM (Hardware Security Module) avec IronPDF offre une sécurité de niveau bancaire où les clés privées ne quittent jamais l'appareil physique. Contrairement à la signature de fichiers .pfx ordinaires où les clés sont chargées dans la mémoire et peuvent être compromises en cas d'attaque de l'ordinateur, la signature HSM maintient la clé privée enfermée dans le dispositif matériel, ce qui la rend impossible à copier ou à voler.

Comment configurer la signature HSM en C# pour les PDF ?

Pour configurer la signature HSM avec IronPDF, installez d'abord la bibliothèque via NuGet avec " Install-Package IronPdf ", puis créez un objet UsbPkcs11HsmSigner avec vos informations d'identification HSM, notamment le chemin d'accès à la bibliothèque, le code PIN, l'étiquette du jeton et l'étiquette de la clé. Enfin, utilisez la méthode SignAndSave pour signer votre document PDF.

Quels sont les avantages en termes de sécurité de l'utilisation du HSM pour les signatures PDF ?

L'utilisation de HSM avec IronPDF permet d'obtenir des signatures numériques infalsifiables, idéales pour les applications critiques. Le processus est comparable à celui d'un dépôt de documents dans un coffre-fort de banque - l'application fournit un code PIN, le HSM signe le document en interne et renvoie le document signé sans jamais exposer la clé privée, ce qui garantit qu'elle ne peut être ni copiée ni volée.

Puis-je tester la signature du HSM sans dispositif physique ?

Oui, IronPDF vous permet de simuler la signature HSM à l'aide de bibliothèques telles que SoftHSM à des fins de développement et de test. Cependant, pour les environnements de production, vous devez utiliser un véritable dispositif HSM physique pour garantir une sécurité adéquate.

Quelle norme API IronPDF utilise-t-elle pour la communication HSM ?

IronPDF utilise la norme API PKCS#11 pour la communication HSM, ce qui garantit la compatibilité avec les dispositifs HSM standard. Cette API commune permet à IronPDF d'interagir de manière transparente avec divers tokens matériels HSM et modules de sécurité.

Comment puis-je vérifier que mon PDF a été signé avec succès avec HSM ?

Après avoir signé un PDF avec la fonctionnalité HSM d'IronPDF, vous pouvez vérifier la signature en ouvrant le PDF signé dans n'importe quelle visionneuse PDF standard. Ce dernier affichera les informations relatives à la signature numérique et confirmera l'authenticité et l'intégrité du document.

Curtis Chau
Curtis Chau
  Discutez maintenant avec l'équipe d'ingénierie
Rédacteur technique

Curtis Chau détient un baccalauréat en informatique (Université de Carleton) et se spécialise dans le développement front-end avec expertise en Node.js, TypeScript, JavaScript et React. Passionné par la création d'interfaces utilisateur intuitives et esthétiquement plaisantes, Curtis aime travailler avec des frameworks modernes ...

Lire la suite
Prêt à commencer?
Nuget Téléchargements 17,386,124 | Version : 2026.2 vient de sortir