Importing Certificates From an HSM

Requirements: SecureBlackbox, Secure PDF

Introduction

Customers often ask whether our components can be used to access an HSM driver that contains a certificate. The good news is that this functionality is fully supported using the appropriate components: CertificateStorage in SecureBlackBox and CertMgr in Secure PDF. This article aims to guide the user through configuring these components, ensuring secure and compliant digital signing workflows.

Importing with SecureBlackbox
Importing with Secure PDF

Importing with SecureBlackbox

The following snippet shows how to extract the certificates from the driver using CertificateStorage and signing a PDF document using PDFSigner.


PDFSigner signer = new PDFSigner();
CertificateStorage storage = new CertificateStorage();

// opening the storage
storage.Open("pkcs11://user:password@localhost/path/to/driver.dll");

Certificate cert = null;

// list the certificates
for (int i = 0; i < storage.Certificates.Count; i++)
{
  Console.WriteLine("Certificate " + (i + 1).ToString() + ": " + storage.Certificates[i].SubjectRDN);

// using the first certificate with a private key to do the signing
  if ((cert == null) && (storage.Certificates[i].PrivateKeyExists))
  {
    cert = storage.Certificates[i];
    Console.WriteLine("(using the above certificate for signing)");
  }
}

// signing a PDF document
signer.InputFile = "sample.pdf";
signer.OutputFile = "signed.pdf";

signer.SigningCertificate = cert;

signer.Sign();

Console.WriteLine("Signing completed!");

storage.Close(false);

To access the certificates stored on the hardware device, we open it by providing the PKCS#11 URI as a parameter to the Open() method. This URI includes the token's credentials (user:password) and the path to the PKCS#11 driver library.

If the storage is opened successfully, the Certificates collection of the Certificate Storage component will be populated with the certificates from the driver.

Importing with Secure PDF

The following snippet shows how to use CertMgr to open an HSM driver storage and use the certificates to sign a PDF document with PDFSign.


CertMgr certmgr = new CertMgr();
PDFSign signer = new PDFSign();

// open the storage
certmgr.CertStoreType = CertStoreTypes.cstPKCS11;
certmgr.CertStore = @"C:/path/to/driver.dll";
certmgr.CertStorePassword = "12345"; // driver's PIN

string secKeyBlob = null;

certmgr.OnCertList += (s, e) =>
{
secKeyBlob = e.CertEncoded;
};
certmgr.ListStoreCertificates();

// signing the file
signer.InputFile = "sample.pdf";
signer.OutputFile = "signed.pdf";

signer.SigningCert = new Certificate(CertStoreTypes.cstPKCS11, secKeyBlob, "test", "*");

signer.Sign();

When using CertMgr, the type of storage (CertStoreType) should be set, which in this case is PKCS#11. CertStore specifies the path to the driver's dll. CertStorePassword provides the driver's PIN. When calling ListStoreCertificates(), the event OnCertList fires for each cert in the store.

We appreciate your feedback. If you have any questions, comments, or suggestions about this article please contact our support team at kb@nsoftware.com.