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

Signature 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 entièrement compatible avec ces opérations, car la bibliothèque et les HSM standard utilisent souvent PKCS#11 comme API commune. À des fins de démonstration concernant la fonctionnalité d'IronPDF avec les HSM, ce guide utilisera un HSM simulé au lieu d'un HSM physique.

Dans un environnement de production ou de test en direct, vous ne devez pas utiliser cette simulation. Vous devez plutôt utiliser votre HSM réel.

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, veuillez consulter leur dépôt GitHub public.

Nous allons commencer 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, nous spécifions le chemin de sortie, qui dans ce cas est output.pdf.

De plus, nous définissons trois chaînes : 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, nous initialisons l'objet UsbPkcs11HsmSigner en passant comme paramètres le chemin de la bibliothèque SoftHSM, le code PIN, l'étiquette du jeton et l'étiquette de la clé.

Nous créons en outre une PdfSignatureImage pour ajouter une représentation visuelle de la signature sur le document. Enfin, nous appelons SignAndSave , qui utilise le hsmSigner que nous avons configuré pour signer le document et l'enregistrer dans le chemin de sortie spécifié.

: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);

IRON VB CONVERTER ERROR developers@ironsoftware.com

Sortie

Voici le résultat généré. Comme vous pouvez le constater, le champ de signature s'affiche et confirme que la signature est effectuée avec le certificat que nous avons généré.

Dépannage

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. 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.

Modification de la cible de la plateforme

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 SoftHSM 64 bits (softhsm2-x64.dll). Dans les propriétés de votre projet Visual Studio, modifiez la plateforme cible de " Any CPU " ou " x86 " à " x64 " pour garantir la compatibilité.

Définition de la variable d'environnement

Une autre cause d'erreur 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 ensuite de redémarrer Visual Studio après avoir effectué les modifications.

De plus, 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")}");

IRON VB CONVERTER ERROR developers@ironsoftware.com

$vbLabelText   $csharpLabel

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