eSigner CodeSignTool Command Guide

CodeSignTool is a secure, privacy-oriented multi-platform Java command line utility for remotely signing Microsoft Authenticode and Java code objects with eSigner EV code signing certificates. Hashes of the files are sent to SSL.com for signing so that the code itself is not sent. This is ideal where sensitive files need to be signed, but should not be sent over the wire for signing. CodeSignTool is also ideal for automated batch processes for high volume signings or integration into existing CI/CD pipeline workflows.

If you’d like to try CodeSignTool with a demo account and certificate, please read eSigner Demo Credentials and Certificates for credentials and configuration information.

To know all the file types that CodeSignTool is able to sign, please refer to this article: eSigner Supported File Types

Note: In version v1.3.2 of CodeSignTool, mscab file signing is performed using in memory processing rather than using a tmp directory.

For instructions on how to automate EV Code Signing using signtool.exe or certutil.exe please review this how-to.

If you are looking to use esigner to sign documents instead, please refer to this DocSignTool guide.

CodeSignTool Installation

To install the current version of CodeSignTool, simply download and unzip the correct file for your OS:

Note that the Windows download includes Java runtime, but the Linux/macOS version requires Java runtime to be installed on your computer. The Windows version of the command is a batch file (CodeSignTool.bat) and the Linux/macOS version is a shell script (CodeSignTool.sh).

CodeSignTool Usage Overview

Usage: CodeSignTool [-hV] [COMMAND] [PARAMETERS]

Options:

  • -h, --help: Display help message and exit.
  • -V, --version: Display version information and exit.

Commands:

  • get_credential_ids: Output the list of eSigner credential IDs associated with a particular user.
  • credential_info: Output key and certificate information related to a credential ID.
  • sign: Sign and timestamp code object.
  • batch_sign: Sign and timestamp multiple code objects with one OTP.
  • hash: Pre-compute hash(es) for later use with batch_hash_sign command.
  • batch_sign_hash: Sign hash(es) pre-computed with hash command.

Parameters:

  • -access_token=<TOKEN>: OAuth access token.
  • -credential_id=<CREDENTIAL_ID>: Credential ID for signing certificate.
  • -input_dir_path=<PATH>: Input directory for code objects to be signed, have hashes computed, or pick unsigned files and corresponding hashes for signing.
  • -input_file_path=<PATH>: Path of code object to be signed.
  • -otp=<OTP>: OAuth OTP value from authentication app.
  • -output_dir_path=<PATH>: Directory where signed code object(s) will be written.
  • -password=<PASSWORD>: SSL.com account password.
  • -program_name=<PROGRAM_NAME>: Name of program (for MSI installers only).
  • -totp_secret=<TOTP_SECRET>: OAuth TOTP secret
  • -username=<USERNAME>: SSL.com account username
  • -override="true": Overwrites the signed file
If your password includes special characters, enclose it in quotes (e.g. -password="P!@^^ssword12").

CodeSignTool Commands

get_credential_ids

Output the list of eSigner credential IDs associated with a particular user. Parameters -username and -password are required.

Usage: CodeSignTool [-hV] get_credential_ids -username=<USERNAME> -password=<PASSWORD>

Example:

CodeSignTool get_credential_ids -username=john.doe@example.com -password="P0z9@lxo41"
Credential ID(s):
- fe537ace-e132-52a9-c2e7-egcd2ac3f1e6

Entering CodeSignTool get_credential_ids without the required parameters will display usage information for the command.

credential_info

Output key and certificate information related to a credential ID. Parameters -credential_id, -username, and -password are required.

Usage: CodeSignTool [-hV] credential_info -credential_id=<CREDENTIAL_ID> -username=<USERNAME> -password=<PASSWORD>

Example:

CodeSignTool credential_info -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -username=john.doe@example.com -password="P0z9@lxo41"
EVCS Certificate Subject Information:
- Subject DN: OID.1.3.6.1.4.1.311.60.2.1.3=US, OID.1.3.6.1.4.1.311.60.2.1.2=Nevada, OID.2.5.4.15=Private Organization, CN=SSL Corp, SERIALNUMBER=NV20081614243, O=SSL Corp, L=Houston, ST=Texas, C=US
- Certificate Expiry: Mon Feb 26 21:21:37 EST 2024
- Issuer DN: CN=SSL.com EV Code Signing Intermediate CA RSA R3, O=SSL Corp, L=Houston, ST=Texas, C=US

Entering CodeSignTool credential_info without the required parameters will display usage information for the command.

scan_code

Enables pre-signing malware scan. This scans your file for any possible malware in order to avoid code compromise and prevents signing of code if malware is detected.

Usage: CodeSignTool scan_code [-hV] -credential_id=<credentialId> -input_file_path=<inputFilePath> -password=<password> [-program_name=<programName>] -username=<username>

For more detailed information on the security benefits of SSL.com’s Malware Scan service, you can visit our dedicated page.

sign

Sign and timestamp code object. Parameters -username, -password, and -input_file_path are required. -credential_id is required only for users with more than one eSigner code signing certificate. -output_dir_path, -program_name, and -totp_secret are optional.

Usage: CodeSignTool sign [-hV] [-credential_id=<CREDENTIAL_ID>] -username=<USERNAME> -password=<PASSWORD> -input_file_path=<PATH> [-output_dir_path=<PATH>] [-program_name=<PROGRAM_NAME>] [-totp_secret=<TOTP_SECRET>]

Optional parameters:

  • If -credential_id is omitted and the user has only one eSigner code signing certificate, CodeSignTool will default to that. If the user has more than one code signing certificate, this parameter is mandatory.
  • If -output_dir_path is omitted, the file specified in -input_file_path will be overwritten with the signed file. CodeSignTool will prompt the user before overwriting the file.
  • If -program_name is present when signing an MSI installer, the value will be displayed in the confirmation dialog as the program name.
  • If -totp_secret is present, CodeSignTool will calculate a time-based OTP for signing, allowing automated use of the tool. If this parameter is not present, the user will be prompted for manual OTP entry.
For information on enrolling an EV code signing certificate in eSigner and setting up two-factor authentication, please read Remote EV Code Signing with eSigner. For information on the TOTP secret value, please refer to Automate eSigner EV Code Signing.

Examples:

Manual OTP Entry:

CodeSignTool sign -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -username=john.doe@example.com -password="P0z9@lxo41" -output_dir_path=signed -input_file_path=test.exe
Enter the OTP - Press enter to continue: 884646
Code signed successfully: C:\Users\John Doe\Desktop\CodeSignTool-v1.0-windows\signed\test.exe

Automated OTP Generation:

CodeSignTool sign -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -username=john.doe@example.com -password="P0z9@lxo41" -totp_secret=ii5gVvZ9G+WkxB3FauAnoL/z14AXSMistcE0jZMWWNSjQDlql2kt2D6Z+l8= -output_dir_path=signed -input_file_path=test.exe
Code signed successfully: C:\Users\John Doe\Desktop\CodeSignTool-v1.0-windows\signed\test.exe

Entering CodeSignTool sign without the required parameters will display usage information for the command.

If you get the error message, Error: invalid otp when attempting to sign a file, it could be caused by one or more of these issues:

  • The QR code you scanned into your authentication app doesn’t match the username, password, and/or credential ID from your command. This could happen if:
    • You have multiple accounts configured for 2FA on your device and chose the wrong one.
    • You are attempting to use your login credentials for a shared certificate, but scanned a QR code shared by a teammate from their account.
  • The OTP you entered has already expired.
  • Your command includes an invalid TOTP secret.
Some eSigner users have reported problems with invalid signatures when signing MSI installers built with Microsoft Visual Studio. As a workaround, we suggest building your MSI files with WiX Toolset. For the convenience of Visual Studio users, a WiX Toolset VS extension is available.

batch_sign

Note: 100 is the maximum number of code files allowed to be signed per batch.

Sign and timestamp up to 100 code files with one OTP. Parameters -username, -password, and -input_dir_path are required. -credential_id is required only for users with more than one eSigner code signing certificate. -output_dir_path, -program_name, and -totp_secret are optional.

Usage: CodeSignTool [-hV] batch_sign [-credential_id=<CREDENTIAL_ID>] -username=<USERNAME> -password=<PASSWORD> -input_dir_path=<PATH> [-output_dir_path=<PATH>] [-program_name=<PROGRAM_NAME>] [-totp_secret=<TOTP_SECRET>]

If a user wants to conduct batch sign with malware checking, each code object in the batch must first be scanned with the scan_code command and then afterwards, the batch_sign command can be ran.

Optional parameters:

  • If -credential_id is omitted and the user has only one eSigner code signing certificate, CodeSignTool will default to that. If the user has more than one code signing certificate, this parameter is mandatory.
  • If -output_dir_path is omitted, the files specified in -input_dir_path will be overwritten with the signed files. CodeSignTool will prompt the user before overwriting the file.
  • If -program_name is present when signing an MSI installer, the value will be displayed in the confirmation dialog as the program name.
  • If -totp_secret is present, CodeSignTool will calculate a time-based OTP for signing, allowing automated use of the tool. If this parameter is not present, the user will be prompted for manual OTP entry.

Example:

CodeSignTool batch_sign -username=john.doe@example.com -password="P0z9@lxo41" -credential_id=fe537ace-e132-52a9-c2e7-egcd2ac3f1e6 -input_dir_path=input -output_dir_path=output
Enter the OTP - Press enter to continue: 455145
Batch sign command executed successfully. Output directory for signed files: output

Entering CodeSignTool batch_sign without the required parameters will display usage information for the command.

hash

Pre-compute hash(es) for later use with batch_hash_sign command. Parameter -input_dir_path is required. -program_name is optional

Usage: CodeSignTool [-hV] hash -input_dir_path=<PATH> [-program_name=<PROGRAM_NAME>]

Optional parameters:

  • If -program_name is present when signing an MSI installer, the value will be displayed in the confirmation dialog as the program name.

Example:

CodeSignTool hash -input_dir_path=input
Hash command executed successfully. Hash files created at: input

Entering CodeSignTool hash without the required parameters will display usage information for the command.

batch_sign_hash

Sign hash(es) pre-computed with hash command. Parameters -access_token, input_dir_path, -otp, and output_dir_path are required. -credential_id is required only for users with more than one eSigner code signing certificate.

Usage: CodeSignTool [-hV] batch_sign_hash -access_token=<ACCESS_TOKEN> [-credential_id=<CREDENTIAL_ID>] -input_dir_path=<PATH> -output_dir_path=<PATH> -otp=<OTP>

Optional parameters:

  • If -credential_id is omitted and the user has only one eSigner code signing certificate, CodeSignTool will default to that. If the user has more than one code signing certificate, this parameter is mandatory.

Example:

CodeSignTool batch_sign_hash -access_token=eyJraWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0IiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJTU
0wuY29tIEF1dGhlbnRpY2F0aW9uIFNlcnZpY2UiLCJleHAiOjE2MTQ4OTcxNDIsImlhdCI6MTYxNDg5MzU0MiwianRpIjoiZmI2OTZlNDUtMTIzOS00ZGE4LW
I1MmYtODNkZDE2MTY3ZTM3IiwidXNlciI6eyJ1c2VyX2lkIjoxMzIyODU4LCJ1c2VyX2VtYWlsIjoiYWFyb24uZS5ydXNzZWxsQGdtYWlsLmNvbSIsInNzbF9
hY2NvdW50X2lkIjo0NzQzMDJ9LCJjbGllbnQiOnsiaWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0In19.fCKDs1igjsI
UDG2sUN_2OTb90Jw1nKNPHcD1MyEUR6sHCv_aJmcvcaFRne_eKLHzeQ9WtT5y3Fb2ppc50kMnjPG6JgX5gnFMptMn-ySsI277CtKbkSn3u-WSDSovn51jPm82
4wTeJmuXEzdv9clRjTwp6VoM9eqHCIaDAd3MP2xpMaa35cZbDaaAFKQ7jxWo9dUuTZY7DsKK0p1LloUEnmNxtNimQ3GDwkj_M600WB1zYrhDL9_3oZKaXcUx9
qzHcBCLzGgeaZ0xdpZtADxmXDUCcmkZi20yQ53bxqVL2w00sJ73efKB7JGeGWVehO-ZlGs3PUQwooox1JgEgcsA -credential_id=fe537ace-e132-52a9
-c2e7-egcd2ac3f1e6 -input_dir_path=input -output_dir_path=output -otp=142392
Batch sign hash command executed successfully. Output directory for signed files: output

Entering CodeSignTool batch_sign_hash without the required parameters will display usage information for the command.

Video: Cloud EV Code Signing with eSigner and CodeSignTool

https://youtu.be/Br25mZIlKdU
Thank you for choosing SSL.com! If you have any questions, please contact us by email at Support@SSL.com, call 1-877-SSL-SECURE, or just click the chat link at the bottom right of this page. You can also find answers to many common support questions in our knowledgebase.
Twitter
Facebook
LinkedIn
Reddit
Email

Stay Informed and Secure

SSL.com is a global leader in cybersecurity, PKI and digital certificates. Sign up to receive the latest industry news, tips, and product announcements from SSL.com.

We’d love your feedback

Take our survey and let us know your thoughts on your recent purchase.