How to Automate EV Code Signing With SignTool.exe or Certutil.exe Using eSigner CKA (Cloud Key Adapter)

This guide shows how to install eSigner CKA and use it for automated and manual code signing on SignTool. 

eSigner CKA (Cloud Key Adapter) is a Windows based application that uses the CNG interface (KSP Key Service Provider) to allow tools such as certutil.exe and signtool.exe to use the eSigner Cloud Signature Consortium (CSC)-compliant API for enterprise code signing operations. It acts like a virtual USB token and loads the code signing certs to the certificate store.

eSigner CKA allows for flexible options to automate signings in CI/CD processes that do not exist with a physical USB token. For guidance on how to use eSigner CKA for automated code signing in CI/CD tools including CircleCI, GitHub Actions, Gitlab CI, and Travis CI, please visit this page: How to Integrate eSigner CKA with CI/CD Tools for Automated Code Signing.

NOTE 

This instructional material requires the following: 

1. Issued EV Code Signing certificate. 
2. EV Code Signing certificate must be currently enrolled on eSigner. If this is not the case, please refer to this guide article. 
3. An Installed authenticator app on your mobile phone like Google authenticator app.

Formulate the Command 

Components of the Command 

For both manual and automated code signing, you will need to type in the command on SignTool. The command contains:

1. The location of SignTool (command-line tool that is responsible for digitally signing a file and verifies the signature), enclosed in double quotation marks: “C:\Program Files (x86)\Windows Kits\10\bin\10.0.22000.0\x86\signtool.exe”
2. The /fd sha256 option which specifies the Hash Algorithm
3. The /tr http://ts.ssl.com option which specifies the timestamp server address
4. /td sha256 option which specifies the timestamp digest algorithm
5. The /sha1 option which specifies the thumbprint that SignTool uses to find the appropriate code signing certificate from the key store
6. The actual certificate thumbprint
7. The path of the file that will be signed, enclosed in double quotation marks: “SIGNABLE FILE PATH”

Over-all the command should look like the following: 

“C:\Program Files (x86)\Windows Kits\10\bin\10.0.22000.0\x86\signtool.exe” sign /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 certificate thumbprint “SIGNABLE FILE PATH”. 

Locating your Certificate Thumbprint

Later, upon installing eSigner CKA and adding your EV Code Signing certificate to the User Certificate store, you will be able to check your EV Code Signing certificate thumbprint by pressing Windows key + R and then type in certmgr.msc to access the User Certificate store. When the certificate manager window pops up, click the Personal folder on the left panel and then select the Certificates subfolder on the right to locate your EV Code Signing certificate.

Double click the certificate. Select the Details tab and then scroll down to reveal the Thumbprint. Copy the Thumbprint and include it into your command line when you are signing code.

Go to top

Manual Code Signing

Install eSigner CKA

When choosing Installation mode, select Manual Code Signing and then click the OK button.

Login to eSigner CKA program

Upon installation of eSigner CKA, open the program and login using your SSL.com account username and password.

Upon successful login, you will be able to see the name of the entity to which the EV code signing certificate was issued, the serial number, expiry date, and the EVCS (Extended Validation Code Signing) acronym.

Write the Command Line on the Text Editor

To recall, the command line for code signing looks like the following: 

“C:\Program Files (x86)\Windows Kits\10\bin\10.0.22000.0\x86\signtool.exe” sign /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 certificate thumbprint “SIGNABLE FILE PATH”

Upon writing the command line on your text editor and pressing Enter, you will see the message Done Adding Additional Store. A window will then pop-up requiring you to place your SSL.com account username and password.

Enter the One Time Password (OTP) 

A One Time Password (OTP) for your eSigner-enrolled EV Code Signing Certificate will be sent to your Authenticator app. Upon successful input, Command Prompt will indicate that your file has been successfully signed.

Check the Digital Signature on the File

After successful code signing, you can now check the details of the digital signature on the file. Right-click the signed file, click Properties, followed by the Digital Signatures Tab. Here you will see the name of the Signer, the digest algorithm used, and the timestamp of the signature. Click the Details button to get more information about the signed code.

Upon clicking Details, you will be able to read the information stating This digital signature is OK. Proceed to click the View Certificate button.

After clicking the View Certificate button, you will read information indicating that the Digital Certificate issued for the signed file ensures that it came from the publisher and protects it from alteration after publication.

Go to top

Automated Code Signing

Install eSigner CKA

When choosing Installation mode, select Automated Code Signing and then click the OK button.

Save the Master Key File

A note will show up explaining the importance of securing the Master Key File. Please read it and then click the OK button.

A window will then pop-up allowing you to choose where you will save the Master Key File.

Type in your SSL.com account username and password

Input your SSL.com account username and password.

Type in your eSigner Time-based One-Time Password (TOTP)

Then place your Time-based One-Time Password (TOTP). You can find your TOTP included in the EV Code Signing certificate order details on your SSL.com account. Type in the 4-digit PIN that you have previously set when you enrolled your order for eSigner and then click the Show QR Code button to reveal the TOTP.

Your TOTP will be shown on a box labeled secret code. Copy the TOTP, paste it on the TOTP Secret field of eSigner CKA window and then click the OK button to save it. 

After putting in your SSL.com account credentials and TOTP, you will be able to view the details of your EV Code Signing certificate. In case you decide to update your TOTP, paste the new TOTP on the allotted field and then click Save.

Write the Command Line on the Text Editor

To recall, the command line for code signing looks like the following: 

C:\Program Files (x86)\Windows Kits\10\bin\10.0.22000.0\x86\signtool.exe” sign /fd sha256 /tr http://ts.ssl.com /td sha256 /sha1 certificate thumbprint “SIGNABLE FILE PATH”

Open Command Prompt and place the command line. After pressing enter, you will see the notice saying Done Adding Additional Store.

After a few seconds, you will see the notice Successfully signed. This indicates that your file has been signed in an automated manner, without the additional need for OTPs. 

Check the presence of the digital signature on your file

Open the folder location of your signed file. Right-click it and then click Properties. Click on the tab Digital Signatures and here you will see the secure hash algorithm used has 256 bits. Click the immediate space showing the name of the signer, digest algorithm, and Timestamp. After it gets highlighted, proceed to click the Details button.

A pop-up window will then show stating that the digital signature on the file is valid as well as indicating the specific time when it was signed. Click the View Certificate button to see more information about the EV Code Signing digital certificate that was issued. 

You will see information about the EV Code Signing certificate stating that it validates you as the creator of the executable and protects your file from being tampered with. 

Go to top

How to test eSigner CKA with your sandbox account

Install eSigner CKA

Choose whether to install it in Manual or Automated mode. 

****Take note that if you have chosen one mode, you have to re-install the program before you can test it in the other mode.*****

Open the Roaming subdirectory of Appdata

 In order to test eSigner CKA using your SSL.com sandbox account, you have to modify the application’s settings on the Roaming subdirectory of the AppData folder. Enter %Appdata% on Windows search bar to take you directly to the roaming subdirectory of AppData.

Open eSigner DATA file with your text editor

Open the eSignerCKA folder, locate the file esignerapp.data, right-click it and choose the option to edit the file using your text  editor, in this case Notepad++. 

Upon opening the text editor, you will see the value sets below.

You can separate the value sets into succeeding rows so that they can be easier to edit. 

Manual mode test signing

For test signing in Manual mode, the following values should be present:

1. The client ID should be: qOUeZCCzSqgA93acB3LYq6lBNjgZdiOxQc-KayC3UMw
2. Add -try on the api_url
   Before: “api_url”:”https://cs.ssl.com/csc/v0/
   After: “api_url”:”https://cs-try.ssl.com/csc/v0/”
3. Replace login with oauth-sandbox on the auth_url
   Before: “auth_url”:”https://login.ssl.com/oauth2/token”
   After: “auth_url”:”https://oauth-sandbox.ssl.com/oauth2/token”
4. “cred_mode”: 0
5. “master_key”: null

Automated mode test signing

For test signing in Automated mode, the following values should be present:

1. The client ID should be: qOUeZCCzSqgA93acB3LYq6lBNjgZdiOxQc-KayC3UMw
2. Add -try on the api_url
   Before: “api_url”:”https://cs.ssl.com/csc/v0/
   After: “api_url”:”https://cs-try.ssl.com/csc/v0/”
3. Replace login with oauth-sandbox on the auth_url
   Before: “auth_url”:”https://login.ssl.com/oauth2/token”
   After: “auth_url”:”https://oauth-sandbox.ssl.com/oauth2/token”
4. “cred_mode”: 1
5. Replace null on master_key with the exact file path of your master key file.
   When installing eSigner CKA in automated mode for the purpose of testing, you have to provide your sandbox account login credentials. The reason is because in automated code signing, login credentials are encrypted using the Master key. If you enter production login credentials on installation and later change the values on the esignerapp.data file following an automated testing format, you will not be able to conduct tests because the username and password you have given are not present in the sandbox test environment.

Login to eSigner CKA using your SSL.com sandbox account credentials

After changing the values on esignerapp.data, you can now test your EV code signing certificate from your sandbox following the same steps outlined earlier for a live certificate.

How to Sign a Hardware Lab Kit (HLK) file using eSigner CKA and HLKSigntool

Hardware Lab Kit is a tool to test and prepare a kernel mode driver  for submission to Microsoft. Currently eSigner CKA also requires the HLKSigntool to be installed in order to be used within Microsoft’s HLK software 

eSigner CKA must first be installed and configured (user logged-in, and TOTP secret set) before running HLKSignTool.exe. 

Step 1. Install and configure eSigner CKA

Step 2. Use HLKSignTool with the command line below

Command Line
HLKSignTool.exe certificate_serial “path_to_file”

Example:

HLKSignTool.exe 3364de1e9ed1882e963a89ff7a958e9d "A:\teet.hlkx"

How to sign VBA Macros using eSigner CKA

Download and install using this link Microsoft Office Subject Interface Packages for Digitally Signing VBA Projects using this link: https://www.microsoft.com/en-us/download/details.aspx?id=56617

Once installed, perform the following steps:

1. Open an administrator command prompt and type the following, the path will be where you just installed the files:

   regsvr32.exe <complete path to example.dll>

   regsvr32.exe <complete path to example.dll>

   For more information on how to register OLE controls, visit Microsoft’s website.

   If successful, you will see a message: “DIIRegister Server in <complete file path> succeeded.”

2. Install the following: download.microsoft.com/download/C/6/D/C6D0FD4E-9E53-4897-9B91-836EBA2AACD3/vcredist_x86.exe
3. Install eSigner CKA
4. Run SignTool command to sign macros: https://www.ssl.com/how-to/automate-ev-code-signing-with-signtool-or-certutil-esigner/#components-of-the-command-line

How to Sign .app files using eSigner CKA

1. Download Dynamics.365.BC.55195.US.DVD.zip at https://www.microsoft.com/en-US/download/details.aspx?id=105113 
   Note: If you attempt to sign a .app file using eSigner CKA without first installing Microsoft Dynamics 365 Business Central application, you will get this SignTool error: This file format cannot be signed because it is not recognized.
2. Open the Dynamics.365.BC.55195.US.DVD.zip and extract the contents to your preferred location.
3. Open setup.exe for Microsoft Dynamics 365 Business Central and click the Next > button.
4. Read the Microsoft Software License Terms and then click the I accept > button.
5. Choose Advanced installation options
6. Click Choose an installation option.
7. Choose the Server installation option.
8. Click the Apply buton.
9. Wait for the installation to be completed. Upon successful installation, click the Close button.
10. Sign your .app file on SignTool: https://www.ssl.com/how-to/automate-ev-code-signing-with-signtool-or-certutil-esigner/#components-of-the-command-line

How to Sign vsix files using eSigner CKA

1. Download Dotnet Core SDK: https://dotnet.microsoft.com/en-us/download/dotnet/7.0
2. Install OpenVsixSignTool
   dotnet tool install -g OpenVsixSignTool
3. Use this sign command:
   OpenVsixSignTool sign --sha1 CERTIFICATE THUMBPRINT --timestamp http://ts.ssl.com -ta sha256 -fd sha256 "SIGNABLE FILE PATH"
   

How to Use Malware Scan on eSigner CKA

Instructions:

1. Login to your SSL.com account. Click the orders tab followed by the download link of your certificate to display its details. Scroll down to the SIGNING CREDENTIALS section and locate the part showing your eSigner certificate credentials. Make sure that the radio buttons that say signing credential enabled and malware blocker enabled are chosen.
2. Install eSigner Cloud Key Adapter.
3. Install eSigner CodeSignTool. Click here to download eSigner CodeSignTool.
4. Scan the code on CodeSignTool using the following command: scan_code [-hV] -input_file_path=<inputFilePath> -password=<PASSWORD> [-program_name=<programName>] -username=<USERNAME>
5. Use Sign Tool to sign the code with eSigner CKA using the following command: scan_code -username=<USERNAME> -password=<PASSWORD> -credential_id=<eSigner Credential ID> -input_file_path=<inputFilePath>

Parameters:

• -input_file_path=<PATH>: Path of code object to be signed.
• -username=<USERNAME>: SSL.com account username
• -password=<PASSWORD>: SSL.com account password.
• -program_name=<PROGRAM_NAME>: Name of program
• -credential_id=<CREDENTIAL_ID>: Credential ID for signing certificate. Your eSigner Credential ID is located in your SSL.com certificate order page.