docs: add Windows code signing review for open-source projects

2026-03-24 15:14:03 +03:00
parent 01c8f71fee
commit 7b563c235e
2 changed files with 158 additions and 1 deletions
--- a/windows-code-signing.md
+++ 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/)