en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

en English
X

Select Language

Powered by Google TranslateTranslate

We hope you will find the Google translation service helpful, but we don’t promise that Google’s translation will be accurate or complete. You should not rely on Google’s translation. English is the official language of our site.

Remote EV Code Signing with eSigner

With SSL.com’s eSigner service, you can use your SSL.com user credentials to sign code from any internet-connected device. This guide will show you how to enroll an EV Code Signing certificate order in eSigner and sign code with the eSigner Express web app, or from the command line with CodeSignTool or SSL.com’s CSC-compliant code signing API.

eSigner can be used for Microsoft Authenticode and Java code signing, and can sign MSI installers and various types of scripts. A complete list of supported file types is available at the end of this guide.

Before getting started, you’ll need an EV Code Signing certificate from SSL.com. For information on ordering your certificate from SSL.com, please read this how-to. If you’d like to try eSigner with a demo account and certificate, please read eSigner Demo Credentials and Certificates for credentials and configuration information.

Enroll in eSigner

First, you’ll need to enroll an EV Code Signing certificate order with eSigner.

  1. Navigate to an issued EV Code Signing order in your SSL.com account. Note that the order is labeled eSigner Ready.
    eSigner-ready EV code signing order
  2. Click one of the download links.
    download links
  3. Create and confirm a 4-digit PIN and click the create PIN button.
If you need to reset your eSigner PIN, please read this how-to.
Create PIN
  • Your certificate will be generated, and after a few moments a QR code will appear above the certificate downloads table.
  • The next time you reload the page the QR code will not be visible. If you need to to view or reset your eSigner QR code, please read this how-to.
    QR Code
  • Scan the QR code into a 2-factor authentication app on your mobile device, such as Google Authenticator or Authy. The app will provide you with one-time passwords (OTPs) for use when signing. Each OTP is valid for 30 seconds.
    OTP in Authy
  • Tip: You can use eSigner to share EV code signing certificates between teammates. Please read Team Sharing for eSigner Document and EV Code Signing Certificates for instructions.

    Sign Code with eSigner Express

    eSigner express is a convenient web-based GUI tool for signing code and documents. Here’s how to use it to sign a code file.

    1. Navigate to https://express.esigner.com/ with your web browser.
      express.esigner.com
    2. Click the Login with SSL.com account button.
      Login with SSL.com account
    3. Enter your SSL.com username and password, then click the Member Login button.
      login window
    4. The main eSigner screen will appear. Drag a file to be signed into the drop area or click and navigate to the file. Do take note that if you plan to sign a file greater than 50MB, you will need to use CodeSignTool. Click here for instructions on how to use this tool.
      Upload PDF File
    5. Enter a 6-digit code from your two-factor authentication app.
      two-factor authentication
    6. You should see a notice that your file has successfully been signed. Click the Download file button and choose a location to save the file.
      Download file
    7. Check the file properties to confirm the digital signature.
      Digital signature
    Note: If you are signing code files that will be included in an installer (such as a Windows MSI file), you will need to sign these files before building the installer, then sign the installer file itself.
    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.

    Sign Code with CodeSignTool

    This section includes instructions for signing code with CodeSignTool, a command-line tool supplied by SSL.com. With CodeSignTool, you can sign a file with one command. (For a complete overview of all CodeSignTool options and parameters, please refer to the eSigner CodeSignTool Command Guide.)

    Install CodeSignTool

    First, download CodeSignTool, a command-line code signing utility for eSigner. Note that the Windows download has Java runtime embedded, but the Linux/macOS version requires Java runtime to be installed on your computer.

    To install, simply download CodeSignTool for your OS and unzip the file:

    Working with CodeSignTool

    You can use CodeSignTool to sign code, get a list of credential IDs associated with an SSL.com user account, or display EV certificate information bound to a credential ID and user.

    Sign Code

    1. When you’re ready to start signing open a terminal and navigate to the directory with CodeSignTool.bat (Windows) or CodeSignTool.sh (macOS/Linux).
    2. Enter the following command to sign a file. (Replace values in ALL-CAPS with your actual values):
      CodeSignTool sign -username=USERNAME -password=PASSWORD -input_file_path=PATH/TO/FILE -output_dir_path=PATH/TO/OUTPUT/DIRECTORY
      • If your password includes special characters, enclose it in quotes (e.g. -password="P!@^^ssword12").
      • If you have more than one eSigner-enrolled EV code signing certificates, you must specify the one to use with the -credential-id option. See below for information on retrieving a list of credential IDs.
    3. You will be prompted for an OTP. Get an OTP from your authentication app and enter it.
      Enter the OTP - Press enter to continue: 123456
      
    Generation of the OTP may be automated, enabling automated use of CodeSignTool in build scripts and CI/CD pipelines. Please read Automate eSigner EV Code Signing for more information.
  • You should receive a message that your file was signed successfully. Check the output file properties for the digital signature.
    Code signed successfully: C:\Users\Aaron Russell\Desktop\CodeSignTool-v1.0-windows\output\test.exe
    Digital signature

  • 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.
    • If using automation, your command includes an invalid TOTP secret.
    Note: If you are signing code files that will be included in an installer (such as a Windows MSI file), you will need to sign these files before building the installer, then sign the installer file itself.
    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.

    Get Credential IDs

    Use the following command to get credential IDs associated with an SSL.com account. (Replace values in ALL-CAPS with your actual values):

    CodeSignTool get_credential_ids -username=USERNAME -password=PASSWORD

    Get EV Code Signing Information

    Use the following command to EV code signing certificate information bound to a credential ID and user. (Replace values in ALL-CAPS with your actual values):

    CodeSignTool credential_info -username=USERNAME -password=PASSWORD -credential_id=CREDENTIAL-ID

    Sign Multiple Files

    Use the following command to batch sign up to 100 files. (Replace values in ALL-CAPS with your actual values):

    CodeSignTool batch_sign -username=USERNAME -password=PASSWORD -input_dir_path=/PATH/TO/CODE/FILES -output_dir_path=/PATH/TO/OUTPUT/DIRECTORY

    Pre-Compute Hashes

    Use the following command to pre-compute hashes for signing with the batch_sign_hash command. (Replace values in ALL-CAPS with your actual values):

    CodeSignTool hash -input_dir_path=/PATH/TO/CODE/FILES

    Batch Sign Hashes

    Use the following command to batch sign hashes computed with the hash command. Note that you will need an access token and OTP. (Replace values in ALL-CAPS with your actual values):

    CodeSignTool batch_sign_hash -access_token=ACCESS-TOKEN -input_dir_path=PATH/TO/HASHES -output_dir_path=PATH/TO/OUTPUT/DIRECTORY -otp=OTP

    Sign Code with Code Signing API

    You can also use API calls to integrate eSigner code signing into your applications and scripts. The example commands shown below use cURL, so you’ll need to make sure it’s available on your computer before getting started. You’ll also need your Client ID (also known as an Application ID. Please refer to this how-to for instructions on generating this credential). If your application is marked as confidential you will also need your Client Secret.

    Retrieve Access Token

    The first step is to retrieve an access token from SSL.com. You’ll need your Client ID (and possibly your Client Secret) available, as well as the username and password for your SSL.com account. Access tokens are valid for one hour after they are issued.

    1. Use the following command to request an access token. Replace the values shown in ALL-CAPS with your actual values:
      curl --location --request POST "https://login.ssl.com/oauth2/token" \
      --header "Content-Type: application/json" \
      --data-raw "{
        \"client_id\"      : \"YOUR-CLIENT-ID\",
        \"grant_type\"     : \"password\",
        \"username\"       : \"YOUR-USERNAME\",
        \"password\"       : \"YOUR-PASSWORD\"
      }"
    2. If your application is marked confidential, add your client secret as well:
      curl --location --request POST "https://login.ssl.com/oauth2/token" \ 
      --header "Content-Type: application/json" \ 
      --data-raw "{ 
        \"client_id\"      : \"YOUR-CLIENT-ID\", 
        \"client_secret\"   : \"YOUR-CLIENT-SECRET\", 
        \"grant_type\"     : \"password\", 
        \"username\"       : \"YOUR-USERNAME\", 
        \"password\"       : \"YOUR-PASSWORD\" 
      }"

       

    3. You should receive a JSON object containing an access token and a refresh token. Copy the access token value to paste into your API requests. You won’t need the refresh token for these examples.

      {"access_token":"eyJraWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0IiwiYWxnIjoiUlMyNTYifQ.eyJpc3MiOiJTU
      0wuY29tIEF1dGhlbnRpY2F0aW9uIFNlcnZpY2UiLCJleHAiOjE2MTQ4OTcxNDIsImlhdCI6MTYxNDg5MzU0MiwianRpIjoiZmI2OTZlNDUtMTIzOS00ZGE4LW
      I1MmYtODNkZDE2MTY3ZTM3IiwidXNlciI6eyJ1c2VyX2lkIjoxMzIyODU4LCJ1c2VyX2VtYWlsIjoiYWFyb24uZS5ydXNzZWxsQGdtYWlsLmNvbSIsInNzbF9
      hY2NvdW50X2lkIjo0NzQzMDJ9LCJjbGllbnQiOnsiaWQiOiJmUE1yYUdlbXVMWGUtcG9JWUtLem1CMEYwYXlFczktUEpiN29lTWFlY2I0In19.fCKDs1igjsI
      UDG2sUN_2OTb90Jw1nKNPHcD1MyEUR6sHCv_aJmcvcaFRne_eKLHzeQ9WtT5y3Fb2ppc50kMnjPG6JgX5gnFMptMn-ySsI277CtKbkSn3u-WSDSovn51jPm82
      4wTeJmuXEzdv9clRjTwp6VoM9eqHCIaDAd3MP2xpMaa35cZbDaaAFKQ7jxWo9dUuTZY7DsKK0p1LloUEnmNxtNimQ3GDwkj_M600WB1zYrhDL9_3oZKaXcUx9
      qzHcBCLzGgeaZ0xdpZtADxmXDUCcmkZi20yQ53bxqVL2w00sJ73efKB7JGeGWVehO-ZlGs3PUQwooox1JgEgcsA","token_type":"Bearer",
      "expires_in":3599,"refresh_token":"o-3V2YD1iIVCh3iJFwFonTohlq_LbGXaJcUvy37ciYA","created_at":1614893542}%

    Retrieve Credential ID

    Next, you’ll need to retrieve the credential ID associated with your eSigner-enrolled EV code signing certificate.

    1. Use the following command to retrieve your account’s list of EV code signing credential IDs. (Replace MY-ACCESS-TOKEN with your actual access token):
      curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/list" \
      --header "Content-Type: application/json" \
      --header "Authorization: Bearer MY-ACCESS-TOKEN" \
      --data-raw "{
          \"clientData\": \"EVCS\"
      }"
    2. You should receive a JSON object with a list of credential IDs associated with the user. Your list will probably contain one value. Copy and paste your credential ID into a text editor for use in later requests.
      {"credentialIDs":["e4763186-5006-48de-bb15-a977e0e84281"]}%

    Upload File

    The next step is to upload your file to be signed.

    1. Use the following command to upload a file for signing. (Replace the values shown in ALL-CAPS with your actual values):
      curl --location --request POST "https://cds.ssl.com/v1/code/upload" \
      --header "Credential-Id: MY-CREDENTIAL-ID" \
      --header "Content-Type: application/exe" \
      --header "Authorization: Bearer MY-ACCESS-TOKEN" \
      --data-binary "@/PATH/TO/FILE"
    2. You should receive a JSON object with an id value to use in the sign file request:
      {"id":"6035539b-4055-43f2-8749-3ad6e559b4cd"}%

    Sign File

    1. Now you can sign the file, using the file ID you got in the previous request and an OTP from your 2FA app. (Replace the values shown in ALL-CAPS with your actual values):
      curl --location --request POST "https://cds.ssl.com/v1/code/sign" \
      --output "PATH/TO/OUTPUT/FILE" \
      --header "Content-Transfer-Encoding: application/json" \
      --header "Content-Type: application/json" \
      --header "Authorization: Bearer MY-ACCESS-TOKEN" \
      --data-raw "{
          \"id\": \"MY-FILE-ID\",
          \"otp\":\"MY-OTP\"
      }"
    2. You should receive a signed file in the location you specified with --output in the command above. Check the file properties to confirm the digital signature.
      Digital signature
    Note: If you are signing code files that will be included in an installer (such as a Windows MSI file), you will need to sign these files before building the installer, then sign the installer file itself.
    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.

    Sign Hash with CSC API

    If you are developing your own apps for signing code (like SSL.com’s CodeSignTool) and want to avoid transferring code artifacts over the internet, you can use the Cloud Signature Consortium (CSC) API to create a digital signature from a file hash.

    Retrieve Access Token and Credential ID

    First, follow the steps shown in the previous section to retrieve an access token and credential ID.

    Retrieve Authorization

    1. Use the following command to retrieve authorization for signing a hash. Replace MY-ACCESS-TOKEN, MY-CREDENTIAL-ID, and MY-HASH with your actual information. Get a one-time password from your 2FA application and use is as the value for MY-OTP.
      curl --location --request POST "https://cs.ssl.com/csc/v0/credentials/authorize" \ 
      --header "Content-Type: application/json" \ 
      --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
      --data-raw "{ 
          \"credentialID\": \"MY-CREDENTIAL-ID\", 
          \"numSignatures\": 1, 
          \"hash\": [
              \"MY-HASH\"
          ],
          \"OTP\": \"MY-OTP\"
      }"
    2. You should receive a JSON object with your Signature Activation Data (SAD) .
      {"SAD":"eyJ1c2VyX2lkIjoxMzQ4MzQyLCJleHBpcmVzX2luIjoiMjAyMS0wNS0xMiAxODo1MDo1MiswMDAwIiwiaGFzaCI6WyJzVE9nd09tKzQ3NGdGajBxM
      HgxaVNOc3BLcWJjc2U0SWVpcWxEZ1wvSFd1ST0iXSwiY3JlZGVudGlhbF9pZCI6ImJjNzE1ZWRhLWQ4MjUtNDliNy1hOGQ1LWVmZGM2ZGI1ZTZkMiJ9.QncXA
      7B+fnUgOUl+SI0FA5tX7N+iKgOA1EyHKWUwUgTLs9Ft2+O4Gk6AVBcX49IEHPsoeq88A+5QPndbc6VtA+XgdExUbWu6E9X74I2EL7Eed+nzjnbR1tPbigcZI9
      DIZFTGwBC5X8af+93oWvmd6omnHSEQpnDbhQHvm3cEZm0fGK4yX9fvxk0Y9qGpKn3xK7PmYdJuAXbyPXFm24RTNIXi4rbwOWghBytt+3WC2ptubz44+X88b19
      gRzIBPKyGdayb99/Uj8xsYh90u2HcL/+J4nKn3J40VTRHckLvoD9r6x8mC/giFXYYN7Q0SKNtrRI9N7SnTX4klPVhNxolA=="}

    Sign Hash

    1. Enter the following command to sign the hash. Replace MY-ACCESS-TOKENMY-CREDENTIAL-ID, MY-SAD, and MY-HASH with your actual information:
      curl --location --request POST "https://cs.ssl.com/csc/v0/signatures/signHash" \ 
      --header "Content-Type: application/json" \ 
      --header "Authorization: Bearer MY-ACCESS-TOKEN" \ 
      --data-raw "{ 
          \"credentialID\": \"MY-CREDENTIAL-ID\", 
          \"SAD\": \"MY-SAD\", 
          \"hash\": [ \"MY-HASH\" ], 
          \"signAlgo\": \"1.2.840.113549.1.1.11\" 
      }"
    2. You should receive a JSON object containing your signature.
      {"signatures":["5CJUauF4WrLs6cc0c0xIVNpaWhjDZoQeRfsKEHhjDskHOrjPoxetOkaqg2wOsIVQiWzvN1fqbO1gG4UzZjU8IctsIPHUa9jU2KyZbWqLy
      bIuUl2k1Tondtp2wNszmwki1z/P5I/ff32TQDWkDiiF+RgPApC4vU8WifTfKMR+cG+2FwtYRuthtuvLoV1dgDSNob5T5tAYlnSjsgwPe9+q/L1v9grSGzre0+
      GgQQPBvN2f1KCkJ/bwJq7votwsncdxCshmPEHyXJTx2SaL9sUHOzwSB79WhOiO8R9nnCZuC90r45f3/6NNWpaUzy3/A9DZa8aHGsaKYsFsXTDQ3HUgxY=="]}

    Supported File Types for eSigner Code Signing

    Microsoft Authenticode File Types
    • acm
    • ax
    • bin
    • cab
    • cpl
    • dll
    • drv
    • efi
    • exe
    • mui
    • ocx
    • scr
    • sys
    • tsp
    MSI File Types
    • msi
    PowerShell Scripts File Types
    • ps1
    • ps1xml
    Other Scripts File Types
    • js
    • vbs
    • wsf
    Java File Types
    • jar
    Don’t see a common file type that you’re trying to sign and should be supported? Please notify our team at Support@SSL.com.

    Share on twitter
    Twitter
    Share on facebook
    Facebook
    Share on linkedin
    LinkedIn
    Share on reddit
    Reddit
    Share on email
    Email