1. Home
  2. Help
  3. Code Signing certificates
  4. Signing with KeyLocker cloud HSM

Signing with KeyLocker cloud HSM

This article will teach you how to sign using the cloud and KeyLocker HSM. The instructions are relevant for all platforms and various signing tools - from signtool to jarsigner. The given information is also the basis for signing using the Software Trust Manager from DigiCert ONE; the signing principle applies to both services.

KeyLocker compatibility

Before you try KeyLocker, you will certainly ask yourself whether it will be possible to use it in your workflow and whether it will work for you. KeyLocker and related libraries support (as does Software Trust Managet in DC1) third-party signing tools. On the DigiCert website, see the article Signing tool integration for a complete overview of file formats that you can sign with compatible tools using KeyLocker.

I will only mention the most widespread Signtool in 32b and 64b version here:

  • SignTool (32-bit): .doc, .docm, .dot, .dotm, .msi, .cab, .exe, .dll, .mpp, .mpt, .pot, .potm, .ppa, .ppam, .pps, .ppsm, .ppt, .pptm, .pub, .vdw*, .vdx*, .vsd*, .vsdm, .vss*, .vssm, .vst*, .vstm, .vsx*, .vtx*, .wiz*, .xla, .xlam, .xls, .xlsb, .xlsm, .xlt, .xltm
  • SignTool (64-bit): .appx, .appxbundle, .arx, .cab, .cat, .cbx, .cpl, .crx, .dbx, .deploy, .dll, .drx, .efi, .exe, .js, .msi, .msix, .msixbundle, .msm, .msp, .ocx, .psi, .psm1, .stl, .sys, .vbs, .vsix, .wsf, .xsn

KeyLocker quickstart guide

After signing in to KeyLocker, you'll see a setup wizard to help you create the authentication tools you'll need.

Save the authentication data carefully, because you cannot sign without them. Save the authentication certificate on the computer where you will be signing. You will store the password for this certificate (PFX) in a system variable or enter it in the wizard.

You can get the authentication data in the guide

Setting up the signing environment

Before signing, you need to set variables and authentication in your system. You can do this manually in the system settings, or use the guide from DigiCert, which is part of the Click-to-sign application (see the last paragraph). You can find the Click-to-sign installer in the same folder as smctl, typically C:/Program Files/DigiCert/DigiCert Keylocker Tools/

The following data must be set in the system variables (manually or using the wizard):

  • Host - URL to connect to, typically https://clientauth.one.digicert.com
  • API key - your API token from KeyLocker
  • Client authentication certificate - your authentication certificate and its password
  • Client authentication certificate password - password to the above certificate
  • Pkcs11 configuration file - optional for signtool; configuration file for the PKCS11 library used by smctl, jarsigner and others. How to create it, see here

Setting variables in DigiCert® Click-to-sign

If you don't know how to set Windows variables manually, check out this video tutorial.

Either the wizard (Credentials saved) will show you the correctness of the settings, or you can verify them using the SMCTL utility with the command smctl healthcheck This command checks the connection and authentication against KeyLocker, but also checks that at least one signing tool is accessible. If so, the given tool will show Mapped: Yes and the path to it on the computer.

If you do not see signtool in the test result (Signtool: Mapped: No), it means that signtool is either not installed or the path to it is not set in the system variables (see Set PATH environment variable for settings). For help with the healthcheck tool, see the Healthcheck commands article in the DigiCert documentation.

We recommend setting the variables to the system permanently, in the case of Windows in a secure way to the Windows Credential Manager (in the system variables, they are accessible to anyone who has access to the given computer). If you only set the variables in the command line, you will have to set them every session. See documentation for Session-based environment variables.

Certificate synchronization

After setting up the connection to KeyLocker (previous paragraph), you need to synchronize the certificates to your system.

C:/Program Files/DigiCert/DigiCert Keylocker Tools>smctl windows certsync --keypair-alias=key_558469087
Syncing certificate for alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135 and SHA1 Fingerprint: ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263

You can also use the smksp_cert_sync utility:

C:/>smksp_cert_sync
Syncing certificate for alias: key_558469087, ID: 2a47112c-4b5d-4ce0-8e70-d67437e58135

Now the public part of the certificate is stored locally in the Windows certificate store, but the private key remains in the cloud storage.

Signing files

Below you will find help on signing files with various tools to help you get started with Code Signing certificates.

The mentioned programs are used in the command line (CLI), with the exception of the DigiCert® Click-to-sign utility (see the last paragraph).

Signing files with SMCTL (recommended)

The SMCTL utility comes from DigiCert and can also be used for simplified file signing using third-party tools (you still need at least signtool). SMCTL works with the most widespread tools - Signtool, Apsigner, Jarsigner, Mage, Nuget. You can find the tool in the folder C:/Program Files/DigiCert/DigiCert Keylocker Tools/smctl.exe

To select a certificate, you can use either a key alias (recommended - you can find it in KeyLocker, among others), or a certificate fingerprint (SHA-1 hash).

smctl sign --keypair-alias=key_558469087 -d=SHA256 --verbose --config-file "C:/Program Files/DigiCert/DigiCert Keylocker Tools/pkcs11properties.cfg" --input "C:/Users/User/HelloSign.exe" smctl sign --fingerprint --input

You can verify the validity of the signature with a command smctl sign verify --input

SMCTL documentation can be found on the DigiCert website

Signing files with Signtool

The following instructions are for Signtool from the Windows SDK. It is the most widely used signing tool on the Windows platform.

The signtool command needs to specify which file you want to sign, with which certificate, and possibly related parameters. You can refer to a signing certificate in a number of ways - you can let Signtool automatically choose a certificate based on the repository; you can make a specific choice of certificate either by referring to the file with the stored certificate (of course only the public part without the private key), or you can use the SHA-1 hash of the given certificate.

Here is an example of signing with a certificate hash:

C:/>signtool.exe sign /sha1 ecb0f10ab1XXXXXXXXXX1681fb70a31e32288263 /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe

And here is an example of signing with KeyLocker and a certificate file:

C:/Users/User>signtool.exe sign /csp "DigiCert Signing Manager KSP" /kc key_558469087 /f C:/Users/User/Documents/cert_558469087.crt /tr http://timestamp.digicert.com /td SHA256 /fd SHA256 C:/Users/User/Documents/HelloSign.exe
Done Adding Additional Store
Successfully signed: C:/Users/User/Documents/HelloSign.exe

You can verify the validity of the signature with a command signtool verify /v file.exe You can also find the signature properties for the signed file through the explorer and Properties (right mouse button).

Signing files with Jarsigner

You can use Jarsigner together with KeyLocker thanks to the PKCS11 library; you can sign simply using SMCTL, or directly using Jarsigner and the PKCS11 library.

Example of signing with Jarsigner: jarsigner -keystore NONE -storepass NONE -storetype PKCS11 -sigalg SHA256withRSA -providerClass sun.security.pkcs11.SunPKCS11 -providerArg pkcs11properties2.cfg -signedjar C:/Users/Name/Desktop/signed/signedjar.jar C:/Users/Name/Desktop/ToSign/jartosign.jar key3 -tsa "http://timestamp.digicert.com"

You can verify the correctness of the signature with the command: jarsigner -verify -certs -verbose

Jarsigner documentation can be found on the DigiCert website.

Signing with DigiCert® Click-to-sign

This utility offers a graphical interface to facilitate file signing. However, the result and principle of signing is no different from command-line tools; on the contrary, they allow more detailed settings of the signature parameters. DigiCert® Click-to-sign only has simplified options, but may be sufficient for most users.

DigiCert® Click-to-sign has one huge advantage - to set it up, you need to go through the wizard for setting up access data (secrets) to KeyLocker. The wizard will simply test your connection to the cloud, but especially set these variables to the system! You will not have to set them up manually.

Signing with this tool is extremely simple - right-click on the file to be signed and select Click to Sign from the menu. Then you can sign directly or with confirmation of the signature settings.

Review before signing in DigiCert® Click-to-sign

Click-to-sign documentation can be found on the DigiCert website DigiCert website.

Note: If Click-to-sign does not work for you, set the paths to Click-to-sign itself and to the signing application (signtool) separated by semicolons in the PATH variable. So for example:
Path: C:/Program Files/DigiCert/DigiCert Keylocker Tools;C:/Program Files (x86)/Windows Kits/10/bin/10.0.22621.0x64;

Integration into CI/CD

KeyLocker's main advantage is the possibility of automating signatures thanks to integration into the CI/CD workflow. DigiCert has prepared a number of scripts and plugins for the most common development tools and platforms. Plugins are available for Azure DevOps, GitHub and Jenkins. It offers even more integration scripts for the PKCS11 library.

You can find complete information in the CI/CD integrations article.

Documentation and other resources: