From 7b563c235edb6232777782d2156a16fdb1258529 Mon Sep 17 00:00:00 2001 From: "dolgolyov.alexei" Date: Tue, 24 Mar 2026 15:14:03 +0300 Subject: [PATCH] docs: add Windows code signing review for open-source projects --- README.md | 6 +- windows-code-signing.md | 153 ++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 windows-code-signing.md diff --git a/README.md b/README.md index c86585f..d812274 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Claude Code Facts -> Last updated: 2026-03-23 +> Last updated: 2026-03-24 A collection of interesting and useful facts, tips, tools, and guides for working with Claude and Claude Code. @@ -13,3 +13,7 @@ MCP servers, skills, and plugins that extend Claude Code — including Context7 ### [CI/CD for Python Apps on Gitea](gitea-python-ci-cd.md) Reusable reference for building CI pipelines, release automation, and installer packaging for Python apps on Gitea — covering lint/test workflows, cross-compiled Windows builds (embedded Python + NSIS), Linux tarballs, Docker images, and Gitea REST API release management. + +### [Windows Code Signing for Open-Source Projects](windows-code-signing.md) + +Review of code signing options for Windows executables — Azure Trusted Signing ($9.99/mo, immediate SmartScreen trust), SignPath.io (free but GitHub-only), SSL.com, Certum, and self-signed. Includes CI/CD integration examples for Gitea Actions. diff --git a/windows-code-signing.md b/windows-code-signing.md new file mode 100644 index 0000000..ce106f9 --- /dev/null +++ b/windows-code-signing.md @@ -0,0 +1,153 @@ +# Windows Code Signing for Open-Source Projects + +A review of code signing options for Windows executables (.exe installers), focused on personal/small open-source projects distributed outside the Microsoft Store. + +## Why Sign? + +Unsigned executables trigger: +- **Chrome**: "This file isn't commonly downloaded and may be dangerous" +- **SmartScreen**: "Windows protected your PC — Unknown publisher" +- **Edge**: Download blocked with "unverified" warning + +These warnings significantly reduce user trust and installation rates. + +## Options Reviewed (2026) + +### 1. Azure Trusted Signing (Recommended) + +**Cost:** ~$9.99/month (Basic tier) + +**Key advantages:** +- **Immediate SmartScreen trust** — Microsoft is the CA, so signed binaries are trusted from day one +- Available to **individuals** — no business entity required +- Identity verification via government ID + address (takes a few business days) +- Cross-platform CI tool (`AzureSignTool`, .NET-based) +- Microsoft-backed trust chain + +**Setup:** +1. Create Azure account + subscription +2. Provision "Trusted Signing" resource in Azure portal +3. Complete identity verification (personal or organization) +4. Create certificate profile +5. Create Azure AD app registration for CI credentials (client ID + secret) + +**CI integration (Gitea Actions / GitHub Actions):** + +```yaml +- name: Install .NET (for AzureSignTool) + uses: actions/setup-dotnet@v4 + with: + dotnet-version: '8.0' + +- name: Sign installer + run: | + dotnet tool install --global AzureSignTool + AzureSignTool sign \ + -kvu "${{ secrets.AZURE_KEY_VAULT_URL }}" \ + -kvc "${{ secrets.AZURE_CERT_NAME }}" \ + -kvi "${{ secrets.AZURE_CLIENT_ID }}" \ + -kvs "${{ secrets.AZURE_CLIENT_SECRET }}" \ + -kvt "${{ secrets.AZURE_TENANT_ID }}" \ + -tr http://timestamp.digicert.com -td sha256 \ + build/MyApp-setup.exe +``` + +**Required secrets:** +- `AZURE_KEY_VAULT_URL` — Trusted Signing account endpoint +- `AZURE_CERT_NAME` — Certificate profile name +- `AZURE_CLIENT_ID` — Azure AD app registration client ID +- `AZURE_CLIENT_SECRET` — Azure AD app registration secret +- `AZURE_TENANT_ID` — Azure AD tenant ID + +**Gotchas:** +- Identity verification can take a few business days +- Basic tier shows your verified personal name (not a custom organization name) +- Relatively new service — documentation is still evolving +- Requires Azure subscription (free tier works, signing resource costs $9.99/mo) + +--- + +### 2. SignPath.io (Free, but restrictive) + +**Cost:** Free for qualifying open-source projects. + +**Requirements:** +- OSI-approved license +- **Public repository on a major forge** (GitHub, GitLab) — self-hosted Gitea likely does not qualify +- Project must show community activity (stars, contributors, issues) +- Signing uses SignPath's own certificate (not yours) + +**SmartScreen:** Immediate trust (SignPath's cert has established reputation). + +**CI/CD:** Native GitHub Actions integration only. Poor fit for Gitea Actions — would require mirroring to GitHub. + +**Verdict:** Best free option if you have a public GitHub repo. Not viable for self-hosted Gitea. + +--- + +### 3. SSL.com + +**Cost:** OV ~$200-350/year, EV ~$350-500/year + eSigner cloud signing costs. + +**Key facts:** +- Free open-source program **discontinued** as of late 2024 +- CA/Browser Forum rules (June 2023) require hardware token or cloud key storage — no PFX file downloads +- eSigner cloud service has CLI tools and API, works with any CI +- EV certificates provide immediate SmartScreen trust; OV needs reputation + +**Verdict:** Expensive for personal projects. Only makes sense if you need EV and can justify the cost. + +--- + +### 4. Certum (Asseco, Poland) + +**Cost:** ~$27-59/year for open-source OV code signing (cheapest legitimate option). + +**Key facts:** +- Requires hardware token (SimplySign cloud or physical card reader) +- SimplySign cloud option can work in CI with effort +- OV only — SmartScreen reputation must be built over time + +**Verdict:** Cheapest paid option. Good budget choice if you can wait for SmartScreen reputation. + +--- + +### 5. Self-Signed Certificates + +**SmartScreen impact: None.** + +- Provides zero SmartScreen benefit +- May trigger more aggressive antivirus warnings than unsigned binaries +- Only useful for internal distribution with controlled trust stores (Group Policy) + +**Verdict:** Pointless for public distribution. + +--- + +## Comparison Table + +| Option | Cost | SmartScreen | CI/CD Fit | Individual OK? | +|--------|------|-------------|-----------|----------------| +| **Azure Trusted Signing** | $9.99/mo | Immediate | Excellent | Yes | +| SignPath.io | Free | Immediate | GitHub only | Yes (if public repo) | +| SSL.com OV | ~$250/yr | Needs reputation | Good (eSigner) | Yes | +| SSL.com EV | ~$400/yr | Immediate | Good (eSigner) | Yes | +| Certum Open Source | ~$30-60/yr | Needs reputation | Moderate | Yes | +| Self-signed | Free | None | Easy | N/A | + +## Recommendation + +**Azure Trusted Signing** is the best option for personal open-source projects: +- Affordable ($9.99/mo) +- Immediate SmartScreen trust +- No business entity required +- Clean CI integration with any platform + +If budget is zero and the project is on public GitHub, try **SignPath.io** first. + +## References + +- [Azure Trusted Signing documentation](https://learn.microsoft.com/en-us/azure/trusted-signing/) +- [AzureSignTool (GitHub)](https://github.com/vcsjones/AzureSignTool) +- [SignPath.io open-source program](https://signpath.io/open-source) +- [CA/Browser Forum code signing requirements](https://cabforum.org/working-groups/code-signing/)