Knowledge Base

Notice Information in this article applies to Excelsior JET version 4.5 and above.

SUMMARY

This document contains step-by-step instructions for digitally signing a Windows executable and for injecting those steps into a build process that involves Excelsior JET.

If you already have a code signing certificate and are familiar with the code signing process, skip to the last section right away.

INTRODUCTION

Just as digital signing of documents and emails confirms their integrity and identities of their authors and senders, code signing confirms the integrity of executable files and the identity of their authors and/or publishers.

In particular, your application must be digitally signed in order to qualify for the “Compatible with Windows 7” or similar logo. The Windows 7 Client Software Logo Technical Requirements document says unequivocally: “All executable files must be signed with an Authenticode certificate.” (Authenticode is the trade name of the Microsoft’s code signing technology.)

If nothing else, signing your installers and executables would improve the UAC experience of your end users. Instead of a scary “An unidentified program wants access to your computer” warning message, they will see “A program needs your permission to continue” box bearing your name next to the “Verified Publisher” label.

For instance, we did not sign Excelsior JET itself prior to version 7.2. Here is the difference the signature now makes on Windows 7 with default UAC settings:

Excelsior JET 7.0 Setup (unsigned)
Excelsior JET 7.0 Setup (unsigned)
Excelsior JET 7.2 Setup (signed)
Excelsior JET 7.2 Setup (signed)

DETAILS

Obtaining a code signing certificate

First of all, you need a code signing certificate signed by a trusted certificate authority (CA), such as VeriSign or Thawte. You may find the full list of Microsoft recognized CAs at the Microsoft Root Certificate Program Members page on MSDN , but note that prices vary greatly from CA to CA and from channel to channel.

Hint: As of October 2010, you may get a very good deal on Comodo code signing certificates through Tucows. All you need to do is go to Tucows Author Resource Center, register as an author (free), log in, and follow the “Code Signing Certificates” link in the sidebar.

Whether you take advantage of this offer or not, you will need to prove your identity to the CA prior to receiving your certificate. Usually faxing them a few documents is enough. For companies, these may be articles of organization, business tax license, bank account statement, etc. An individual would have to fax a copy of a photo ID and document(s) bearing his/her name and address specified in the certificate, such as an utility bill.

Executable Signing And Verification

You may sign not only the executables (.exe files), but also DLLs, ActiveX controls (.ocx), Windows Installer packages (.msi), etc. The EXE and DLL files produced by Excelsior JET are just conventional Windows executables, so there is nothing special about the signing procedure itself. You may however need to modify the packaging steps

Prerequisites

You will need:

  1. SignTool.exe from Windows Platform SDK. The rest of the SDK is not needed for code signing, so if you do not have it installed on your build system, copy just that file.
  2. CAPICOM.dll version 2.1.0.1 or higher. That DLL is not included in the recent SDK versions (only its .NET counterparts are present), but Microsoft has made version 2.1.0.2 available as a separate download.

    Troubleshooting CAPICOM.DLL installation

    CAPICOM.DLL must be registered as a COM server. However, the installer fails to register it under 64-bit Windows 7 (and maybe other recent flavors of Windows.)

    If the DLL is not registered, SignTool will complain that it cannot be found even if they are in the same directory:

        SignTool Error: Signtool requires CAPICOM version 2.1.0.1 or higher. Please
                copy the latest version of CAPICOM.dll into the directory that contains
                SignTool.exe. If CAPICOM.dll exists, you may not have proper
                permissions to install CAPICOM.
    
        Number of errors: 1

    In order to properly register the DLL, run the following command with administrative privileges:

        regsvr32 full-path-to-CAPICOM.DLL

    Rumor also has it that on 64-bit systems CAPICOM.DLL must be coped to %SYSTEMROOT%\SysWOW64 prior to registration, but that has proven to be unnecessary on our systems.

  3. Code signing certificate and private key. Note: SignTool expects the certificate and key stored together in one file in PKCS #12 format. If the certificate and key you have received from your CA are in a different format, you will also need the pvkimprt.exe tool from another Microsoft download. to combine them in a PKCS #12 file. Refer to the instructions provided by your CA or to the article “Code Signing for Developers” in the REFERENCES section below.
  4. Private key password.
  5. Timestamp server URL, e.g. http://timestamp.comodoca.com/authenticode. Important: The timestamp confirms the existence of the file being signed at the time of signature as measured by server clock. In other words, it confirms that the certificate was valid at the real time of signature, not the system time of the computer on which you run SignTool. If you do not timestamp the signature, it will expire when the certificate expires.

Signing

    signtool sign /f certificate-file
                  /p password
                  /t timestamp-server-URL
                  file-to-sign-1 file-to-sign-2 ...

Example:

    C:\temp> signtool sign /f MyCert.p12 /p SeCRetpASsw0rd /t http://timestamp.comod
    oca.com/authenticode MyApp.exe
    Done Adding Additional Store
    Successfully signed and timestamped: MyApp.exe

Signature Verification

    signtool verify /pa signed-file-1 signed-file-2 ...

(for some reason omission of /pa results in a error message asking to specify it :) )

Example:

    C:\temp> signtool verify /pa MyApp.exe
    Successfully verified: MyApp.exe

Timestamp Validation

Temporarily advance the system date beyond the certificate expiration date (max three years from whatever is the current date) and re-verify the file.

If the signature was not timestamped, verification shall fail:

    C:\temp> date 1-1-2020
    C:\temp> date 
    Wed Jan  1 14:40:38 NCAST 2020
    C:\temp> signtool verify /pa MyApp.exe
    SignTool Error: WinVerifyTrust returned error: 0x800B0101
            A required certificate is not within its validity period when verifying 
    against the current system clock or the timestamp in the signed file.
    SignTool Error: File not valid: MyApp.exe

    Number of errors: 1

Avoiding Interference With JetPackII

An important caveat is that Excelsior JET modifies the executables when preparing them for deployment, so they must be signed after they were post-processed by JetPackII, but, obviously, before packaging. This is easy to achieve if you are using a third-party setup generator or export your compiled application into a self-contained directory. However, if you use the bundled Excelsior Installer, the procedure is a bit more complicated, because JetPackII invokes the packager automatically. You need to use the command-line xpack tool to separate executable post-processing from packaging.

For details, refer to the section “Installations protected by license managers” in the Chapter “Deployment Automation” of the Excelsior JET User’s Guide.

REFERENCES

  1. Introduction To Code Signing (MSDN)
    http://msdn.microsoft.com/en-us/library/ms537361%28VS.85%29.aspx
  2. Microsoft Root Certificate Program Members (MSDN)
    http://msdn.microsoft.com/en-us/library/ms995347.aspx A list of trusted CAs maintained by Microsoft. Choose among those with "Yes" in the "Code Signing" column (some of them do not provide time stamping, but you are not obliged to use the certificate issuer’s service to time stamp the respective signatures.)
  3. Code Signing for Developers.
    http://www.wiscocomputing.com/articles/code-signing.htm This article on WISCO Computing Web site provides much more detailed instructions on obtaining and using Microsoft code signing tools.
  4. Excelsior JET User’s Guide, Chapter “Deployment Automation”, section “Installations protected by license managers”.

Article ID: 34
Last Revised On: 22-Oct-2010