Code Signing

Introduction

Code-signing ensures that the installer, uninstaller and launchers can be traced back to a particular vendor. A third party certificate authority guarantees that the signing organization (you) is known to them and has been checked to some extent. The certificate authority has the ability to revoke a certificate in case it gets compromised.

The basis for code signing is a private key / public key pair that you generate on your computer. The private key is only known to you and you never give it to anyone else. The certificate provider takes your public key and signs it with its own private key. That key in turn is validated by an official root certificate that is known to the operating system. The private key, the public key and the certificate chain provided by the certificate provider are required for code signing.

On Windows, code signing is particularly important since Windows Vista. For unsigned applications that require admin privileges, Window Vista and higher will display special warning dialogs to alert the user that the application is untrusted and may harm the computer.

On macOS 10.8 or higher the default security setting makes it more difficult for the end user to install an application that has not been signed, so code signing is practically required.

Obtaining Code Signing Certificates

You need different certificates for code signing on Windows and macOS:

Key Store Passwords

Private keys are sensitive information. If they get into the wrong hands, your identity is compromised. Because of that, private keys are secured with a password. When install4j signs your installers and launchers, it needs to work with the private key.

When you start a build in the install4j IDE, you will be asked for the Windows and macOS key store passwords as required. install4j does not store those passwords to disk, but they are cached on a per-project level as long as the install4j IDE remains open.

When you do a command line build, the install4j command line compiler will ask you for the required passwords. If you want to fully automate a build with code signing, you can pass passwords on the command line by setting the --win-keystore-password=[password] and --mac-keystore-password=[password] command line parameters. The install4j ant task offers the corresponding "winKeystorePassword" and "macKeystorePassword" attributes. Please note that adding these passwords to shell scripts or ant build files constitutes a security risk.

In a setup where only a restricted number of people can build signed executables, you can use the --disable-signing command line parameter, the "disableSigning" ant task attribute or the corresponding build option in the "Build" step of the install4j IDE to temporarily disable code signing. In that way, other developers can build fully functional, unsigned installers without modifying the project file.

HTTP connections during code signing

Code signing certificates issued by certificate providers expire after a certain time. For Windows code signing, the expiry time is usually one or two years, after which you have to purchase a renewal from your certificate provider. Executables that were signed while the certificate was still valid are trusted indefinitely unless the certificate is revoked.

A computer that validates an executable compares the signing time and the expiry time of your certificate. Certificate providers want to prevent you from turning back the clock of your computer to circumvent the expiry of your certificate. This is why the signing time has to be counter-signed by a certificate provider. Certificate providers offer free web services that will confirm that a signature has been performed at a particular time. This counter-signature is not related to a particular certificate - so one can use the web service of any certificate provider, regardless of where the certificate came from. install4j uses the VeriSign time stamp service.

The consequence of this scheme is that you need an internet connection at build time in order to get a trusted time-stamp counter signature. Many build servers are behind fire walls and you might need to set up a proxy to get internet connectivity. install4j will try to auto-detect the proxy information. If that fails, the IDE will ask you for proxy information, but the command line builds will not ask for user-input in order to avoid hanging builds due to temporary internet connectivity problems.

For command line builds, you can pass the following VM parameters to the command line compiler:

The authentication parameters are optional, only the first 3 parameters are required to set up a proxy.

If you pass these parameters to the command line compiler, you have to prefix them with "-J" (such as -J-DproxySet=true) to mark them as VM parameters. In the ant task, use nested "vmParameter" elements to pass the above parameters (without the "-J" prefix).