1. Home
  2. Help
  3. Code Signing certificates
  4. Troubleshooting Guide for KeyLocker
{"copy":"Copy","expand":"Expand","collapse":"Collapse","copy_success":"Copied!","copy_error":"Copying failed!"}

Troubleshooting Guide for KeyLocker

KeyLocker is a powerful tool for code signing that allows you to store your Code Signing certificate in the cloud and securely sign its hash remotely. However, the initial setup has some pitfalls that this article will help with.

Article Content

Variable Check

An essential step for the operation of KeyLocker on your system is the correct setting of variables. They not only define the path to the signing tools but mainly contain authentication data. You can set them for a single session or permanently.

There are various ways to set variables on the system. You can store them in a standalone file and variables or save them to the Windows Credential Manager. If you want to sign using a GUI, you can set them in the Click-to-sign utility found in the KeyLocker account (however, the variables will not work at the system level).

Setting a variable in Windows is easy via the command line. Launch cmd and type setx VARIABLE=value Note - setx works with user variables, not system variables.

For KeyLocker to function correctly, you need to set variables for client authentication + the location of signing tools and libraries from DigiCert.

Authentication Setup

  • SM_CLIENT_CERT_FILE - path to the authentication certificate with the p12 extension that you downloaded from the DigiCert ONE guide
  • SM_HOST - DigiCert ONE host address, which is https://clientauth.one.digicert.com

These two variables are not secret because the certificate is password protected. You can safely set them to the system. The following two variables are secret, and it is recommended not to set them to the system if it is accessed by multiple users. It is better to store them in Windows' password manager. For more information on setting up variables for Windows, see the article Credential setup for Windows.

  • SM_API_KEY - API key that you generated in the DigiCert ONE interface
  • SM_CLIENT_CERT_PASSWORD - password for the authentication certificate in P12 that was displayed to you one-time in the DC1 guide

Path Setup for Signing Tools

Adding a value to the PATH variable is done with the command setx PATH "path;%PATH%" This command adds a new value to the existing user values of the PATH variable and saves it permanently. For KeyLocker to function correctly, you must set at least two:

  • Path to Windows SDK and signtool
  • Path to DigiCert Keylocker Tools

Find the valid path to Windows SDK (the path uses the version number you have installed). You will also need DigiCert Keylocker Tools, which you downloaded and installed from DigiCert ONE; you will find them in C:\Program Files\DigiCert\DigiCert Keylocker Tools.

We will add both variables at once via CMD, otherwise they will overwrite each other: setx PATH "C:\Program Files\DigiCert\DigiCert Keylocker Tools\;C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\;%PATH%"

You can set system variables via the Windows GUI; cmd is faster, but values are overwritten with multiple entries. PowerShell can also be used.

How to Manually Edit PATH Variable in Windows

If you want to ensure that values are preserved, you can manually edit the PATH:

  1. Open Control Panel → System → Advanced system settings.
  2. Click on Environment Variables.
  3. Find PATH (in System variables or User variables).
  4. Click Edit, add individual paths, and save.
Adding variables via Windows GUI
Adding variables via Windows GUI

How to Add PATH Variable Using PowerShell

If you want to permanently add a path to the PATH variable using PowerShell, proceed as follows:

  1. Open PowerShell as admin (right-click Start → Windows PowerShell (Admin)).
  2. First, find out the current value of the "PATH" variable:
    3. [System.Environment]::GetEnvironmentVariable("Path", "User")
  3. Then add a new path to the existing values:
    4. 
$path = [System.Environment]::GetEnvironmentVariable("Path", "User")
$newPath = $path + ";C:\Program Files\DigiCert\DigiCert Keylocker Tools\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  4. If you need to add another path, repeat the process:
    5. 
$newPath = $newPath + ";C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\"
[System.Environment]::SetEnvironmentVariable("Path", $newPath, "User")
  5. After executing the commands, restart the command line or computer to apply the changes.

Note: If you want to change the system "PATH" variable (valid for all users), replace "User" with "Machine" in the command.

Checking the variable value in cmd: echo %VARIABLE% For example, "echo %PATH%". Cmd will then display its value.

Configuration Check

KeyLocker tools contain the smctl utility that you can use to sign, but it also serves for basic diagnostics. The following command checks whether everything is set up correctly and whether smctl can connect to the DigiCert cloud:

smctl healthcheck

In the output, you will see confirmation whether you have connected with KeyLocker (authentication works) and whether smctl detects the presence of signing tools, such as signtool. Example:

smctl healthcheck
--------- Account Settings ---------
Teams: Disabled
Threat detection: Enabled
        Static Binary Analysis: Enabled
        Software Composition Analysis: Disabled

--------- User credentials ---------
Status: Connected

Username: XXXX-keylocker
Accounts: XXXX-1699076
Authentication: 2FA
Environment: Prod
Credentials:
        Host: https://clientauth.one.digicert.com
        API key: 010897bf735bbc57d48270cd3d_50dxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxe4 (Pulled from environment variable)
        Client certificate file path: C:\Users\xy\Documents\keylocker\Certificate_pkcs12.p12
        Client certificate password: ytf_xxxxxx0F (Pulled from environment variable)
API keys:
        Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)

Client certificates:
        Name: xy (expires on Mon, 31 Dec 2029 23:59:59 UTC)

Privileges:
        Can sign: Yes
        Can approve offline release: No
        Can revoke certificate: Yes
        Can scan: No

Permissions:
Account Manager:
        MANAGE_AM_PERMISSION
        MANAGE_AM_ROLE
        MANAGE_AM_ACCOUNT_USER
        VIEW_AM_ROLE
        VIEW_AM_ACCOUNT
        VIEW_AM_USER
        VIEW_AM_ORGANIZATION
        VIEW_AM_AUDIT_LOG

Keypairs:
        SIGN_SM_HASH
        VIEW_SM_KEYPAIR
        MANAGE_SM_KEYPAIR

Certificates:
        VIEW_SM_CERTIFICATE
        REVOKE_SM_CERTIFICATE

Other permissions:
        VIEW_SM_LICENSE
        MANAGE_SM_CC_API_KEY

--------- Signing tools ---------
Signtool 32 bit:
        Mapped: No
Signtool:
        Mapped: Yes
        Path: C:\Program Files (x86)\Windows Kits\10\bin\10.0.26100.0\x86\signtool.exe
Mage:
        Mapped: No
Nuget:
        Mapped: No
Jarsigner:
        Mapped: No
Apksigner:
        Mapped: No

If there is an authentication issue, check whether you have set the correct values obtained from the KeyLocker guide in the DigiCert ONE interface. If you are in doubt, you can reset the guide and create new credentials.

You may also encounter that smctl does not detect signtool or other signing tools. This means that it is necessary to add their locations to the user or system PATH variable. See the section on variables above.

MMC and Certificate Presence Check

If you are working on Windows, check the certificate manager, which you launch with the certmgr.msc command. If the synchronization with KeyLocker is successful, you will see a certificate with a private key flag in the certificate store. However, this does not mean that it is actually with the private key there - the certificate with the private key is still stored in the cloud.

If the certificate is not there, run the synchronization. smctl windows certsync Upon successful synchronization, you will see confirmation: 

Syncing certificate for alias: key_1236506290, ID: ac793b6d-cac4-4be4-b145-003d4d1d63db and SHA1 Fingerprint: 54d0c7a2d93ae4d5fccb41d97c51a8ab3581c72c

Signing Issues

If you are experiencing signing issues, try to go from the most general to the more complex. The easiest way is to sign using the DigiCert smctl utility, which can serve as an overlay with signing tools like signtool or jarsigner. This is the least conflicting way and requires no parameters. For troubleshooting, do not use timestamp or other options.

You can sign with smctl easily: smctl sign --keypair-alias=key_1234567890 --input C:\Users\John.Doe\Desktop\file_to_sign.exe

You can reference the certificate with the "keypair-alias" or "fingerprint" parameter, which you can find with the smctl windows certsync command, for example.

After signing, you can verify the signature: smctl sign verify --input

Help for signing can be found in the article Sign binaries with SMCTL.

After successful signing with smctl, you can sign with another tool, like signtool. It should work too. Let the certificate selection happen automatically and gradually add other parameters.

Once it works successfully according to your expectations, you can try signing using Visual Studio or another development environment.

Where to Find Logs

If all the above fails and signing does not work, I recommend checking the logs of smctl and other tools from DigiCert. If you use logs when resolving an issue with our support, you will definitely expedite the resolution of the issue.

The smctl utility log is located in the smctl.log file, which will be placed in the /.signingmanager/logs folder in the user profile. Try writing into cmd echo %USERPROFILE%/.signingmanager/logs and you will see the complete folder location.

Additional Resources and Information

Has this article been useful?