Code Signing InVEST Installation Media

Codesigning InVEST Installation Media

The most recent manual Windows code-signing steps (Spring 2025)

We shouldn't need to this manually anymore, it's automated as part of our build process. But here are the instructions anyway.

1. Set up your yubikey by ensuring your PUK is not set to the default and that you have the Yubikey smart card minidriver installed. See the yubico docs for complete steps.
2. On a Windows computer, download the Windows installer for the Workbench from the release page on GitHub.
3. Open a command prompt (recommended: use "Developer Command Prompt for VS 2019") and navigate to the directory where the downloaded installer is located.
4. Follow the steps on the yubico docs under "Procedure" to sign the installer. If you're using a Developer Command Prompt, signtool.exe will already be on your PATH.
5. Upload the signed installer to the release page on GitHub and to Google Cloud, overwriting the binaries that are already there.

Which InVEST Versions are Signed

• InVEST Windows Installers version 3.8.0 and later
• InVEST DMGs version for 3.9.0 and later

The initial signature

Assuming everything is working, installers and disk images on the main natcap/invest repository are all automatically signed as a part of the regular Github Actions binary build workflows.

Renewing a Code-Signing Certificate

1. See instructions at https://uit.stanford.edu/service/ssl/codesigning.
2. When submitting a support request, make sure they do not revoke the old certificate
   • If prior binaries have not been timestamped, revoking the certificate will cause problems.
   • Stanford's certificate issuer can handle keeping expired certs around (according to a UIT rep), so let's do that.
3. When you have the certificate, upload it to GCP and update Makefile and our github actions to use the new cert and password.

If a certificate is revoked

When a certificate is revoked (as it was in January, 2021), the revocation will also prevent Gatekeeper (Mac OS) and SmartScreen (Windows) from opening the installers if the binaries are not timestamped. The only known way around this is to re-sign the installation media.

If the binaries were timestamped at the time of signing, there should be no problem with launching the old binaries.

Re-Signing on Windows

1. Download the current certificate (.pfx or .p12) and retrieve the password.

2. Download the InVEST installer to sign

3. Execute the following signtool.exe calls to re-sign and re-timestamp the binary:

   signtool.exe sign /f "<path to certificate>" /p "<certificate password>" <path to InVEST installer>
   signtool.exe timestamp -t http://timestamp.sectigo.com <path to InVEST installer>
   

   For me, signtool.exe is located at C:\Program Files (x86)\Windows Kits\10\App Certification\signtool.exe. If that doesn't work for you, try running a find "C:\Program Files (x86)" -name "signtool.exe", as the binary might have moved.

   See this help page about why timestamping matters.

4. Upload the re-signed installer file to the target distribution locations:

   • Google Cloud
   • The Github Release for this version

5. Repeat for each affected version of InVEST

Re-Signing on Mac

The codesign binary may require XCode developer tools.

1. Download the .pfx or .p12 certificate file and retrieve the certificate password

2. Double-click the certificate to install it to your local key store. You'll need to enter the certificate password to do so. The key will be identified in your key store as "Stanford University"

3. Download the InVEST DMG to sign.

4. Execute the following command to re-sign the binary:

   codesign --force --timestamp --verbose --sign "Stanford University" <path to InVEST DMG>
   

   The --force is needed to overwrite the existing signature.

5. Upload the re-signed DMG to the target distribution locations:

   • Google Cloud
   • The Github Release for this version

6. Repeat for each affected version of InVEST