Preferences - Code signing

The Preferences - Code signing dialog box is one of the pages that appears when you choose the Edit > Preferences command on the main menu bar. It allows you to set the options that InstallMate uses when it runs the Microsoft SignTool tool to sign your installation packages.

Note: The options in this dialog box are used as global defaults. You can also choose to have per-configuration Code signing settings, which are accessible through the Advanced... button on the Package attributes pane.

See Digital Signatures for background information about code signing and digital signatures.

Converting SPC/PVK files to PFX

If your code signing certificate consists of separate .spc and .pvk files, you must convert this to a single .pfx file using Microsoft's pvk2pfx.exe tool that is included in the InstallMate 9\Tools folder on your system. The basic syntax is:

pvk2pfx -pvk c:\path\to\private.pvk -spc c:\path\to\certificate.spc -pfx c:\path\to\certificate.pfx

In this command, the -pvk and -spc parameters specify input files, and the -pfx parameter specifies the output file. Consult the Microsoft documentation for pvk2pfx.exe for details of its usage.

Dialog fields and options

This dialog box contains the following fields and options.

Attribute Description
Code signing certificate for installer signing
PFX file

Select this option if your code signing certificate is contained in a PFX file, then enter the path to your PFX (Personal Information Exchange) file that contains your code signing certificate, or click the ... (browse) button to open a standard Windows Open dialog to browse for the file. This file contains the credentials (certificate information) that will be included with the signature.

  • SignTool command line option: /f filepath
Password

Enter the password for the private key inside the PFX file, if any. This password is stored in encrypted format on the system. You must specify this password if your PFX file is protected by one, or SignTool with fail with exit code 1.

  • SignTool command line option: /p password
CSP name

Enter the name of the Cryptographic Service Provider that contains the private key container if the PFX file does not contain the private key.

  • SignTool command line option: /csp CSPName
Container

Enter the name of the private key container within the CSP that contains the private key container if the PFX file does not contain the private key.

  • SignTool command line option: /kc PVKContainerName
Stored name

Select this option if your code signing certificate is contained in a stored container, including most token-based certificates. Enter the name of your stored certificate, also known as the Subject name. This name is visible in the Windows Certificate Manager.

  • SignTool command line option: /n "stored name"
Automatic certificate
selection

Select this option if you want to let SignTool choose the best available certificate. The certificate(s) must be stored in the Windows certificate store, as accessible through Windows Certificate Manager.

  • SignTool command line option: /a
Code signing options
(implicit)

The following options are implicitly added to the SignTool command line:

  • /d <ProductName> to add a description of the contents to be signed
  • /du <WebSite> to add the product information URL, if available
Sign with SHA-1

Sign the installer using Secure Hash Algorithm revision 1, a 160-bit (20-byte) digest algorithm. This was the default and still is the most commonly used algorithm, but is being phased out as of 2016 and replaced by SHA-256.

It is recommended that your installers be signed with both SHA-1 and SHA-256 signatures to ensure backward compatibility, unless you are certain that your installers will only be deployed on Windows 7 or later systems.

  • SignTool command line option: /fd sha1 (or none, because SignTool defaults to SHA-1)

Note: If you select the option Add MSI wrapper in the Package settings, then the MSI wrapper will always be signed with a SHA-1 digest if you enable code signing. This is done because the MSI format does not support SHA-256 signatures. For more information, see Concerns with MSIs on the Microsoft web site. The main .exe installer will use all signature(s) that you specify: SHA-1 and/or SHA-256.

Timestamp

Check this box to include a timestamp in the SHA-1 signature; clear it to sign the distribution package without timestamp. In general, it is recommended to include a timestamp in your signature. This allows customers to verify that your certificate was valid at the time of signing, even if it has since expired (Software Publishing Certificates and others have a built-in expiry date).

Enter the fully qualified URL of the timestamping server. This should be a trusted server (usually associated with a Certification Authority) that offers a certified timestamping service. The default value is http://timestamp.digicert.com, the DigiCert Inc. timestamping server.

  • SignTool command line option: /t serverURL
Sign with SHA-256

Sign the installer using Secure Hash Algorithm revision 2, with a 256-bit (32-byte) digest algorithm. As of 2016, this is the recommended signature algorithm, but it is only supported from Windows 7 onwards. For that reason, it is recommended that your installers be signed with both SHA-1 and SHA-256 signatures.

  • SignTool command line option: /fd sha256 /as

Warning Warning: SHA-2 signatures are not universally supported and your system or your code signing certificate might not support signing with these digests. If you see a diagnostic message BLD:E0039 Code signing failed - SignTool returned nonzero exit code 1 after code signing when you have selected SHA-256, then you may have to upgrade your code signing certificate (or your Windows system, if you are still using a pre-Windows 7 system).

Timestamp

Check this box to include a timestamp in the SHA-256 signature; clear it to sign the distribution package without timestamp. As with the SHA-1 timestamp above, it is recommended that you include a timestamp in your digital signature.

Enter the fully qualified URL of the timestamping server. This should be a trusted RFC-3161 compliant timestamping server (usually associated with a Certification Authority) that offers a certified timestamping service. The default value is http://timestamp.digicert.com, the DigiCert Inc. RFC-3161 timestamping server.

  • SignTool command line option: /tr serverURL /td sha256

Note 1: SHA-256 timestamping can be very slow at times; it may occasionally take 30-60 seconds. Nevertheless, we recommend that you include the SHA-256 timestamp to ensure that your signature remains valid even after the expiry of your code signing certificate.

Note 2: SHA-256 timestamps require an RFC-3161 compliant timestamping server, which is not the same as the timestamping servers used for SHA-1 (and MD5) signatures.

Custom options

Enter any custom command line options that your code signing certificate or process requires. These options will be added verbatim to the SignTool command line, except that any symbolic references will be expanded first.

  • Do not specify any of the command line options that are already covered above such as /kc or any of the implicit options such as /du. Check the documentation of the options above for the specific tool to see which options are already covered by InstallMate Builder.
  • You can use symbolic references such as <BuildTarget> in the custom options; they will be expanded before use. To prevent expansion of all or a part of the custom options, enclose the verbatim part within `backquotes`.
Show console window

Check this box to show the console window in which SignTool.exe runs; clear the box to keep that hidden.

Note: The console window must be kept visible if your code signing certificate requires interaction during the code signing process, for example to enter a token-based password as is the case for some types of EV certificates. An invisible console window precludes the display of the password prompt, even if that takes place in a separate popup window.

Verbose output Check this box to make SignTool produce more verbose output; clear it for minimal output. The output is briefly visible in the console window (see Show console window) but is also captured in the code signing log file, which you can find in the file PackageName.SignCode.log in your InstallMate project folder.
Debug info Check this box to make SignTool produce debug output; clear it for standard output. The output is briefly visible in the console window (see Show console window) but is also captured in the code signing log file, which you can find in the file PackageName.SignCode.log in your InstallMate project folder.