Sign the PyInstaller executable and the MSI installer

[PierreRaybaut]

Context

The artifacts produced by the release CI workflow (the PyInstaller binary DataLab.exe and the MSI installer) are not digitally signed. This has several consequences:

• Windows SmartScreen displays an "Unknown publisher" warning on first launch, which degrades user experience and can block installation in corporate environments.
• IT security policies: many organisations refuse to execute unsigned binaries.
• Integrity verification: the lack of signature prevents any automated cryptographic verification of the origin and integrity of downloaded artifacts.
• Trust: for an open source project with industrial ambitions, signing is an expected signal of quality and maturity.

Code signing was intentionally deferred until the release process was fully automated via GitHub Actions (see related issue #327): signing, especially for a Windows binary and an MSI installer, is significantly easier to set up in an automated, reproducible environment than in a heterogeneous local workflow.

Goal

Add a code signing (Authenticode) step to the release CI workflow for:

1. The PyInstaller executable DataLab.exe.
2. The MSI installer generated by the WiX Toolset.

Signing must happen after artifacts are produced by the existing jobs, without changing the build logic itself.

Technical options to investigate

• Certificate type:
  • OV (Organization Validation) or EV (Extended Validation)?
  • An EV certificate grants immediate SmartScreen reputation but requires a hardware device (HSM / USB token) — poorly compatible with CI execution.
  • Cloud-based solutions such as Azure Key Vault + Trusted Signing (formerly Azure Code Signing) or DigiCert KeyLocker allow signing from a CI runner without a physical HSM.
• Provider: Sectigo, DigiCert, GlobalSign, SSL.com, Microsoft Trusted Signing, etc. — trade-off between cost, SmartScreen reputation and CI integration.
• Signing tool: signtool.exe (Windows SDK), osslsigncode, or a dedicated tool from the provider.
• Secrets management: credentials and certificate access stored in GitHub Actions secrets, with a documented rotation procedure.
• Timestamping: mandatory so that signatures remain valid after the certificate expires (/tr + /td sha256 with signtool).
• Verification: post-signing verification step (signtool verify /pa /v).

Acceptance criteria

• DataLab.exe and DataLab-X.Y.Z.msi produced by the CI workflow are digitally signed and timestamped.
• signtool verify /pa succeeds on both artifacts.
• The SmartScreen "Unknown publisher" warning no longer appears (subject to the chosen certificate type and reputation accrual).
• Signatures remain valid after the certificate expires, thanks to timestamping.
• The certificate renewal procedure is documented and tested.

Dependencies

• Blocker resolved: fully automated release CI workflow (see related issue Automate the full release process via GitHub Actions).
• Budget: code signing certificate acquisition (recurring annual cost).
• Organisational decision: choice of provider and certificate type.

[PierreRaybaut]

After reviewing the options for Windows code signing (Authenticode), we have decided not to acquire an OV or EV code-signing certificate at this stage, and to address the underlying need through a lighter, zero-cost mechanism instead. This note explains the reasoning and the concrete actions taken.

Restated primary goal

The primary goal of this issue, as originally stated, is to let users make sure they are running the official DataLab binary, from a trusted source. Removing the Windows SmartScreen "Unknown publisher" warning is desirable, but it is a UX improvement, not a prerequisite for verifying authenticity and integrity.

What each option actually covers

Need	SHA-256 hashes + build attestations	OV Authenticode	EV Authenticode
Verify integrity (artifact not tampered with)	yes	yes	yes
Verify origin (artifact built from our repository, by our CI)	yes (cryptographically, via Sigstore-backed attestation)	yes (UAC shows "DataLab Platform")	yes
Remove "Unknown publisher" in UAC	no	yes	yes
Remove SmartScreen warning	no	only after the certificate accrues reputation (thousands of downloads)	yes, immediately
Annual cost	0 €	~250–400 €	~350–600 € + cloud HSM or USB token
CI integration	native (GitHub OIDC)	requires cloud HSM (Azure Trusted Signing, DigiCert KeyLocker, SSL.com eSigner, …)	same, with stricter onboarding

Authenticode is the only way to make the Windows shell happy out of the box, but it does not add anything to the integrity/origin guarantee that GitHub-issued attestations already provide — and the latter is verifiable independently of any third-party CA, with a single command, by any user who cares to check.

Decision

We implement step 1 only for now:

• Generate a SHA256SUMS file covering every artifact published in a release (.whl, .tar.gz, .msi, .pdf).
• Generate a Sigstore-backed build provenance attestation for each binary artifact, using the official actions/attest-build-provenance action. The attestation cryptographically links each artifact to the exact workflow run, commit and repository that produced it.
• Publish both as part of the GitHub release.

Users can then verify any downloaded artifact with:

# Integrity
sha256sum -c SHA256SUMS

# Origin / provenance (requires the GitHub CLI)
gh attestation verify DataLab-X.Y.Z.msi --repo DataLab-Platform/DataLab

This is the standard practice in the scientific Python ecosystem (CPython, NumPy, SciPy, …) and is sufficient to answer the original need: a user — or an IT security team — can prove, with public-key cryptography and no trust in any third-party CA beyond GitHub/Sigstore, that the binary they are about to run was built by our official CI from a specific commit of DataLab-Platform/DataLab.

Why we are deferring Authenticode signing

• Cost vs. benefit imbalance for our user base. DataLab targets scientific/technical users, often deploying inside controlled environments. The added value of removing the SmartScreen warning, while real, does not justify a recurring ~300–500 €/year cost plus the operational overhead of cloud HSM credentials, certificate rotation, and per-release signing infrastructure — for a need that is already covered by free, equally trustworthy means.
• No demonstrated blocker. We have not received user feedback indicating that SmartScreen or "Unknown publisher" prevents adoption. If such feedback materializes, we can revisit.
• Reversible decision. Adding Authenticode signing later is an incremental change to the existing CI workflow — it does not invalidate or interfere with the attestations introduced now. Both mechanisms coexist cleanly.

What changes in the CI workflow

• release.yml and release-rc.yml: the GitHub-release job now generates SHA256SUMS, calls actions/attest-build-provenance@v2 for the wheel, sdist and MSI, and uploads SHA256SUMS alongside the existing release assets. The job permissions are extended with id-token: write and attestations: write, both required by the attestation action.
• No change to the build itself, no new secret to manage, no new third-party dependency, no recurring cost.

Scope kept open for a future iteration

If we later decide that the UX cost of SmartScreen is no longer acceptable, the recommended follow-up is Azure Trusted Signing (OV) integrated via azure/trusted-signing-action, with the certificate stored in a Microsoft-managed cloud HSM and signing happening on the Windows runner after PyInstaller and before WiX. This would be tracked as a separate, smaller issue, with the budget question made explicit.

Updated acceptance criteria for this issue (revised scope)

• A SHA256SUMS file is published with every release.
• A build provenance attestation is generated for .whl, .tar.gz and .msi and is verifiable with gh attestation verify.
• The verification procedure is documented (this note; to be promoted to user documentation when the first attested release ships).
• (Out of scope, deferred) signtool verify /pa succeeds on DataLab.exe and the MSI.
• (Out of scope, deferred) SmartScreen "Unknown publisher" warning no longer appears.

[PierreRaybaut]

Waiting for the final test before closing the issue: the first release using our new CI workflow