# Code signing — the Windows "unknown publisher" prompt

**English summary.** The binaries in this repository are **not** code-signed, so the first run shows Windows SmartScreen's blue "Windows protected your PC" box — click *More info → Run anyway*. This document explains what signing would actually require (an OV or EV certificate; since June 2023 the private key must live on a hardware token or a cloud HSM; alternatives are Azure Trusted Signing and the free SignPath Foundation programme for open source), how to sign the NSIS installer and `Uninstall.exe` (`signtool sign /fd SHA256 /tr <timestamp-url> /td SHA256`), and why a `.zip` cannot be signed at all. **This document is in Chinese.**

---

# 关于代码签名（Windows 的「未知发布者」怎么办）

先说结论：**不签也能发布**，只是别人第一次双击会看到一个蓝色的「Windows 已保护你的电脑」框，点「更多信息 → 仍要运行」就能装。这个仓库现在就是这种情况。

下面把这事讲清楚，方便以后真去签。

---

## 1. 签名到底解决什么

| | 没签名 | 有签名（OV） | 有签名（EV） |
|---|---|---|---|
| 双击时 | 蓝色 SmartScreen 警告，「未知发布者」 | 早期仍可能警告，随下载量累积逐渐消失 | 立刻显示你的公司名，基本不拦 |
| 属性 → 数字签名 | 空 | 有，能看到签名者 | 有 |
| 被杀毒软件误报 | 概率更高 | 低一些 | 更低 |
| 能不能防篡改 | 不能（只能靠 SHA256） | 能 | 能 |

签名**不等于安全审计**，只证明「这个文件确实来自证书持有者，且之后没被改过」。

## 2. 2023 年 6 月之后的新规矩（很多人不知道）

CA/Browser Forum 从 2023-06-01 起要求：**所有代码签名证书的私钥必须放在硬件令牌（USB HSM）或云 HSM 里**，不能再像以前那样发一个 `.pfx` 文件给你随便拷。

所以现在只有三条路：

1. **买硬件令牌**：证书 + 一个 USB key（约 ¥1500~3000/年，需要企业或个体工商户资质，个人一般买不了 OV/EV）。
2. **用云签名服务**（推荐给个人/小团队）：
   - **Azure Trusted Signing**：微软自己的，约 $9.99/月起，个人也能申请（要身份验证 + 有一定历史），签名在云端完成，CI 里几行配置就能用。
   - 各家 CA 的云 HSM 方案（DigiCert KeyLocker、Sectigo 等），价格更高。
3. **开源项目免费签**：
   - **[SignPath Foundation](https://signpath.org/)**：给开源项目免费提供代码签名（含 EV），要求仓库公开、构建可复现、走他们的 CI。对「个人开源小工具」来说这是最现实的免费方案。

**没有证书的话：** 别去买淘宝上的「便宜证书」，那种多半是盗用别人身份签的，被吊销后你所有版本一起失效。

## 3. 真签的时候，具体怎么签

工具是 Windows SDK 里的 `signtool.exe`（装了 Visual Studio 或 Windows SDK 就有）。

**签安装程序：**

```powershell
signtool sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 `
  /f "证书.pfx" /p "密码" `
  "release\cute-fat-fish-pet-1.2.1-setup.exe"
```

- `/fd SHA256`：文件摘要算法；`/td SHA256` + `/tr`：时间戳（**一定要打时间戳**，否则证书过期后旧版本签名一起失效）。
- 用云签名 / 硬件令牌时把 `/f /p` 换成对应的 `/dlib` + `/kc` 或 Azure 的 `signtool` 封装。

**签卸载器 `Uninstall.exe`：** 它在安装时由 NSIS 从包里写出来，所以要签的是打进包里的那一份。最省事的做法是让 NSIS 编译时自动签（在 `build\installer.nsi` 顶部加）：

```nsis
!define SIGNTOOL '"C:\Program Files (x86)\Windows Kits\10\bin\10.0.22621.0\x64\signtool.exe"'
!finalize '${SIGNTOOL} sign /fd SHA256 /tr http://timestamp.digicert.com /td SHA256 "%1"'
```

**签完必须验证：**

```powershell
signtool verify /pa /v "release\cute-fat-fish-pet-1.2.1-setup.exe"
```

（`/pa` = 用默认验证策略，别漏，否则有漏洞的旧策略也会「通过」。）

**zip 不能签**——zip 本身没有签名字段。要么把里面的 `electron.exe` / `launcher\pet.ico` 之类先签好再压缩，要么就只发 `.sha256`。

## 4. 不签的话，怎么让用户放心

这个仓库现在就是这么做的：

1. 每个 Release 都附上 `.exe.sha256` / `.zip.sha256`，README 里写明大小与哈希，用户可以用

   ```powershell
   Get-FileHash .\cute-fat-fish-pet-1.2.1-setup.exe -Algorithm SHA256
   ```

   对一下是不是一样。
2. 安装包里的东西全部可查：`第三方声明.txt` 列了每个组件的来源与许可证，`LICENSE.txt` 是 MIT 全文。
3. 想更进一步，可以用 GPG 签 git tag（`git tag -s v1.2.1`）——这证明「这个 tag 是你打的」，但**不影响 SmartScreen**，两者是两回事。

## 5. 签名的钱花在哪最值

按性价比排：**SignPath Foundation（开源免费）→ Azure Trusted Signing（约 $120/年）→ 买 OV 证书 + 令牌（约 $200~400/年）→ EV（更贵，除非你很在意「公司名显示 + 立刻不拦」）**。

如果只是想让朋友、群友装着放心，第 4 节那三条完全够用；等下载量上来了再考虑签。