docs: add Windows code signing review for open-source projects
This commit is contained in:
@@ -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.
|
||||
|
||||
153
windows-code-signing.md
Normal file
153
windows-code-signing.md
Normal file
@@ -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/)
|
||||
Reference in New Issue
Block a user