Signing with KeyLocker Cloud HSM
This article will teach you how to sign using the cloud and KeyLocker HSM. The guide is relevant for all platforms and various signing tools – from signtool to jarsigner. The provided information also serves as a foundation for signing using the Software Trust Manager from DigiCert ONE; thus, the signing principle applies to both mentioned services.
KeyLocker Compatibility
Before trying out KeyLocker, you might wonder whether it can be used in your workflow and if it will work for you. KeyLocker and related libraries support third-party signature tools (as does the Software Trust Manager in DC1). On the DigiCert website, you can find a complete overview of file formats you can sign using compatible tools with KeyLocker in the article Signing tool integration.
Here, I will only mention the most widespread SignTool in 32-bit and 64-bit versions:
- 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
Guide in KeyLocker
After logging into KeyLocker, you will see the Setup Guide, which helps you download the DigiCert ONE Clients application. It will allow you to log into the KeyLocker account on your computer, install the necessary libraries, including SMCTL, and set system variables for authentication. This is a significant simplification compared to the previous procedure.
In the first step of the KeyLocker guide, download, install, and run the DigiCert ONE Clients app. Log in the same way as you set up for the KeyLocker web interface.
In the next step, install SMCTL in the desktop application, which is the main tool for signing itself.
After installation, you will see a choice of three possible ways to store the KeyLocker variable in the system. We recommend keeping the default option "Store my credentials". This will save the data to the system, and you won't have to log in to the account before each signing.
When you choose the option to store in the system, credentials will be in the Credential Manager on Windows systems.
After setting up system credentials, which the DigiCert ONE Clients app performs automatically, proceed to the third step of the guide. Now, it will want you to run the SMCTL healthcheck command in your system, which tests the communication of the local environment with KeyLocker and proper authentication. Everything should run smoothly, so confirm "I have run the healthcheck command in SMCTL" and click the Check Status button.
You will see a green confirmation You're ready to start signing with SMCTL, indicating everything is set up correctly, communication works, and you can start signing.
Select the correct platform you use for signing from four options, and then see an example (guide) for signing with KeyLocker.
Signing Files
We primarily recommend using the SMCTL utility for signing, which operates in the command line (CLI). The second option is the DigiCert® Click-to-sign utility (see the last paragraph).
Guides for signing files for major platforms (Authenticode, Docker, Java...) can be found directly in the KeyLocker web interface. After finishing the guide (title "Setup complete!"), you can click on one of the offered platforms, and the interface will show you a prepared command using the selected certificate. Just copy it into CLI and specify the file to sign. It can't get any simpler!
Signing Files with SMCTL (Recommended)
The SMCTL utility comes from DigiCert and can also be used for simplified file signing with third-party tools (you still need at least signtool). SMCTL cooperates with the most widespread tools – Signtool, Apksigner, Jarsigner, Mage, Nuget. The tool is found in the folder C:/Program Files/DigiCert/DigiCert Keylocker Tools/smctl.exe
In the last step of the guide, click on Authenticode and in the next dialog, choose the certificate available in KeyLocker. You will get a complete signing command, where you will specify the target and run it locally in your CLI. You will immediately receive confirmation of successful file signing.
You can find the complete SMCTL documentation on the DigiCert website.
Signing Files with Signtool
The following guide concerns the Signtool tool from the Windows SDK package. It is the most widespread tool for signing on the Windows platform.
The Signtool command needs to specify which file I want to sign, which certificate to use, and possibly related parameters. There are several ways to refer to a signing certificate: You can let Signtool choose the certificate automatically based on the store, or you can make a specific choice using a stored certificate file (of course, only the public part without the private key), or you can use the SHA-1 hash of the certificate.
Here is an example of signing using the 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 using 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 a signature with the command: signtool verify /v file.exe The signature properties can also be found in the signed file through Explorer and Properties (right-click).
Signing Files with Jarsigner
You can use Jarsigner with KeyLocker via the PKCS11 library; you can sign more quickly using SMCTL or directly using Jarsigner and the PKCS11 library.
An 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 a signature using the command:
jarsigner -verify
You can find documentation for Jarsigner on the DigiCert website.
Signing with DigiCert® Click-to-sign
This utility offers a graphical interface for simplifying file signing. The result and principle of signing don't differ from command-line tools; on the contrary, they allow more detailed signature parameter settings. DigiCert® Click-to-sign only offers simplified options, which, however, may suffice for most users.
DigiCert® Click-to-sign has one significant advantage – setting it requires going through the guide for setting KeyLocker access (Secrets). The guide will not only test the connection to the cloud easily but, primarily, set these variables in the system! So, you won't have to set them 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 either sign right away or confirm the signature settings.
You can find documentation for Click-to-sign on the DigiCert website.
Note: If Click-to-sign doesn't work, set the PATH variable to include paths to the Click-to-sign itself and the signing application (Signtool) separated by semicolons. 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
The main advantage of KeyLocker is the ability to automate signing through integration into the CI/CD workflow. DigiCert has prepared several scripts and plugins for the most widespread development tools and platforms. Plugins are available for Azure DevOps, GitHub, and Jenkins. They offer even more integration scripts for the PKCS11 library.
You can find complete information in the article CI/CD integrations.
Documentation and Additional 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
