Signing with KeyLocker cloud HSM

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 that will help you download the DigiCert ONE Clients application. Using it, you'll sign in to your KeyLocker account on your computer, the required libraries including SMCTL will be installed, and the system authentication variables will be configured. Compared to the previous procedure, this is a significant simplification.

In the first step of the KeyLocker wizard, download the DigiCert ONE Clients app, install it and launch it. The login is the same as the one you set up for the KeyLocker web interface.

In the next step, in the desktop application install SMCTL, which is the main tool for the signing itself.

After the installation, you'll see the choice of three possible ways to store KeyLocker variables in the system. We recommend keeping the default "Store my credentials" option. The data will be saved to the system and you won't need to sign in to your account before each signing.

When you choose the option to save to the system, on Windows the credentials will be in the Credential Manager.

After the login credentials are set up in the system, which the DigiCert ONE Clients application does automatically, proceed to the third step of the wizard. It will now ask you to run the SMCTL healthcheck command in your system, which will test the communication of the local environment with KeyLocker and correct authentication. Everything should go smoothly, so confirm "I have run the healthcheck command in SMCTL" and click the Check Status button.

You'll see the green confirmation You're ready to start signing with SMCTL, which means everything is set up correctly, communication works and you can start signing.

Choose the correct platform you use for signing from the four options, and you'll then see an example (guide) for signing using KeyLocker.

Signing files

For signing we primarily recommend using the SMCTL utility, which works in the command line (CLI). The second option is the DigiCert Click-to-sign utility (see the last paragraph).

You can find signing guides for files for the main platforms (Authenticode, Docker, Java...) directly in the KeyLocker web interface. After finishing the wizard (heading "Setup complete!"), you can click on one of the offered platforms and the interface will show you the prepared command using the selected certificate. Just copy it into the CLI and specify the file to sign. It cannot get any simpler!

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

In the last step of the wizard, click on Authenticode and in the next dialog choose the certificate available in KeyLocker. You'll get the complete signing command, into which you'll fill in the target and run it locally in your CLI. You'll immediately receive confirmation of the successful signing of the file.

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.

Click-to-sign documentation can be found on the 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:

• SignTool documentation, available at https://learn.microsoft.com/cs-cz/dotnet/framework/tools/signtool-exe
• KeyLocker documentation, available at https://docs.digicert.com/en/digicert-keylocker.html

Do you have questions?

Don't hesitate to contact our customer support, which will advise and help you.