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

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 CSC for signing operations. It acts like a virtual USB token and loads the code signing certs to the certificate store.

This feature helps make your eSigner cert more flexible with options to automate signings in CI/CD processes that do not exist with a physical USB token.

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 Line

Components of the Command Line

For both manual and automated code signing, you will need to type in the command line on your text editor, such as Command Prompt. The command line contains:

1. The location of SignTool (command-line tool that is responsible for digitally signing a file and verifies the signature), enclosed in parenthesis: “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 parenthesis: “SIGNABLE FILE PATH”

Over-all the command line 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 EVCS certificate to the User Certificate store, you will be able to check your EVCS 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 EVCS 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.

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 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.

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 credentials

Input your SSL.com account username and password.

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 EVCS 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, paste the command line for the file to be signed. 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 EVCS digital certificate that was issued. 

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

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.