Signing built applications

Signing your application means that Windows will not warn users about running executables from an "Unknown Publisher".

Windows

You can sign with a normal Microsoft Authenticode Certificate, however this does not build instant trust with the SmartScreen filter (the popup when you launch someone's installer or program).

If you have hardware drivers (for connecting to custom hardware), or you want a level of instant trust from Microsoft, you need an Extended Validation Code Signing Certificate (EV cert).

The EV certificate comes embedded on a secure USB token, and integrates with either some vendor signing software, or Microsoft's signtool software.

Publishing flow looks like this:

  1. Build production binaries/installers,
  2. Sign the executable,
  3. Zip the executable, and upload to your website/server/install media.

Buying an EV Token

Several certificate authorities provide Microsoft certified EV certificates. Microsoft have a page listing some providers and the steps. Most EV certificates cost around \$250-600USD/year.

We found that using Microsoft's link to Digicert's EV signing method presented a far lower price, though we don't know how long this will continue to occur.

Based on our experience, the purchase process required information such as company information, our DUNS number, and several confirmations of contact details.

After the authority independantly confirmed this information, they double-checked validity of the order by calling company directors.

The token is then shipped to you with instructions for activating the token and changing the token's password.

Signing an Executable

Token specific interactions may vary by provider, but signing tokens generally use the Windows SmartCard framework/standards, so the signing steps are reasonably generic.

Our certificate provider Digicert, provides their own signing software which allows for manual application signing in a very straightforward manner with a standalone exe file.

  1. The Microsoft recommended signing approach is to use signtool.exe which is included in the windows-sdk available here. You only need to install the "Windows SDK Signing tools for Desktop Apps" section.
  2. You then need to add the signtool.exe location to your path to call it from CMD more easily - C:\Program Files(x86)\Windows Kits\10\bin is typically the location, though this location may vary by SDK version.
  3. Sign your binary by calling signtool from the CLI, passing in options for timestamping, certificate types and the executable to sign.
signtool sign /fd sha256 program.exe
  1. A GUI prompt for your token's password will be presented, then the application will be signed.

We recommend cross-signing with the timestamp server of your certifiate provider like so,

signtool sign /tr http://timestamp.digicert.com /td sha256 /fd sha256 program.exe

You can validate the signing process by right-clicking on the executable and viewing "Properties" then "Digital Signature". This will show the timestamp, certificate and certificate authority details.

Signing on CI/CD

As the general signing flow requires a manual password entry into a graphical prompt, the signing process is tricky to integrate into a headless, automatic signing process. This is unfortunately by design.

There are some community created tools which try to ease this process - SafeNetTokenSigner is one example, but we found best success with a more manual signtool based method outlined below:

  1. Using the SafeNet tool to view the certificate/token details

    1. Export the certificate as a .cer and save it somewhere.
    2. View the certificate details (advanced or detailed view mode) and extract the "Container Name" which is a hex formatted string.
    3. Find and save the "Reader Name"
  2. Store your token's password and the container name as secure/private strings in your CI/CD system so they don't leak.

  3. Sign the application and manually provide the .cer, and password/container name, following our internal arc.exe signing command as example.

  4. signtool sign /tr http://timestamp.digicert.com /td sha256 /fd sha256 /f C:\electricui.cer /csp "eToken Base Cryptographic Provider" /kc [{{%EV_PASSWORD%}}]=%EV_CONTAINER_NAME% /n "Electric UI Pty Ltd" arc.exe
  5. No prompt should be required, and the executable will sign. Signtool will output a message:

    1. Done Adding Additional Store
    2. Successfully signed: arc.exe

For our build system, GoCD, the password and container name are exported as environment variables, and %ENV_VAR% is the normal Windows syntax to handle this.

If you embed these strings into a build script or use some other method, the % aren't required.

macOS

Applications running on macOS require signing and notarisation (in that order) in order to run normally on user's computers.

Without this step, users are shown a scary message about malicious software, and would need to open up their Security preferences and allow the untrusted application manually.

This is mandatory as of 10.15 (Catalina).

Prerequisites

Signing

Currently not publicly documented. Get in touch and we'll help you out.

Notarisation

Currently not publicly documented. Get in touch and we'll help you out.