GPG 签名验签解决的是一个很具体的问题:下游拿到一个安装包、一个压缩包或一次 Git 提交时,凭什么相信它没有被换过。仅靠 HTTPS 与 SHA256 校验值不够——校验值本身也放在同一台服务器上,服务器被入侵后两者会一起被改。用离线保管的私钥对产物做分离签名,把公钥指纹通过独立渠道分发,才能在下游形成可验证的信任链。本文覆盖密钥结构设计、签名、分发、验签、轮换与吊销的完整流程,命令可直接复制执行。
适用场景
以下场景都需要产物级签名,而不是只依赖传输层安全:
- 自建 APT / YUM 软件源,内网几十台服务器从该源安装包,源站一旦被投毒会横向感染;
- 对外发布 tar.gz、deb、rpm、jar 或固件升级包,用户需要在不信任网络的前提下验证来源;
- CI 流水线自动构建产物并上传制品库,需要证明「这个包确实由本次流水线产出」;
- Git 仓库要求提交签名,防止他人伪造作者身份往主干推代码;
- 合规审计要求提供「软件发布完整性与来源真实性」的证据链。
前置条件
- GnuPG 2.2 以上(
gpg --version确认),支持 ed25519 与--quick-*系列命令; - 一台不联网或严格受限的签名机,用于保管主密钥;私钥不要放在 CI 或开发机上;
- CI 环境只需要签名子密钥,或改用
gpg --detach-sign在签名机产出后在流水线中只做验签; - 一个稳定的身份标识(如
release@example.com),后续换密钥时要能对应到同一发布主体; - 公钥分发渠道已确定:官网静态页、代码仓库根目录、内部 Wiki,且指纹单独公示。
原理说明
OpenPGP 的密钥不是一个文件,而是一棵结构:主密钥(Primary Key)只承担「证明身份」和「签发子密钥」两项职责,子密钥(Subkey)分别承担签名与加密。这样设计的意义在于:日常签名用的是可轮换、可过期、可放在联网机器上的子密钥;主密钥离线保存,只在新增或吊销子密钥时才用一次。即使签名子密钥泄露,攻击者也只能伪造签名,不能签发新密钥、不能解密历史数据,主密钥持有人在吊销子密钥后即可止损。
签名本身有两种形态:内嵌签名(对文件本身签名,产出 .gpg)与分离签名(产出独立的 .asc 或 .sig,原文件不变)。发布场景应当用分离签名,因为下游可以在不解包、不改动原始字节的前提下验证,且签名文件可以随 CDN 一起分发。签名内容不是文件本身,而是对文件做哈希后的摘要,所以一个 2GB 的镜像签名只需几 KB。
验签的信任模型是薄弱环节,也是最容易被误解的地方。GPG 校验的是「签名与内容是否匹配、签名者公钥是谁」,它不判断这个公钥是否可信。因此 gpg --verify 输出 Good signature 只代表内容未被篡改;要确认来源,必须额外比对签名者公钥的指纹是否等于官方公示值。只导入公钥就完事,等于把信任建立在「我从哪下载的」上,而这正是攻击者能控制的环节。
操作步骤
第一步:在签名机上生成主密钥与子密钥
主密钥只用于认证,签名与加密各用一个子密钥,有效期分开设置便于独立轮换:
# 1) 生成主密钥:仅 cert 能力,有效期 2 年,交互式设置强口令
gpg --quick-generate-key "Example Release Signing <release@example.com>" ed25519 cert 2y
# 2) 取主密钥指纹(后续所有命令都用指纹而不是邮箱,避免同名歧义)
FPR=$(gpg --list-keys --with-colons release@example.com | awk -F: '/^fpr/{print $10; exit}')
echo "PRIMARY FPR = $FPR"
# 3) 添加签名子密钥(日常签名用,有效期 1 年,便于单独轮换)
gpg --quick-add-key "$FPR" ed25519 sign 1y
# 4) 添加加密子密钥(用于加密发布通知等,可选)
gpg --quick-add-key "$FPR" cv25519 encr 1y
# 5) 结构复核:主密钥应为 [SC] 或 [C],子密钥为 [S]/[E]
gpg --list-keys --keyid-format long "$FPR"
# 6) 备份私钥与吊销证书到离线介质(拔掉介质后再继续)
gpg --armor --export-secret-keys "$FPR" > /media/offline/release-secret.asc
gpg --output /media/offline/release-revoke.asc --gen-revoke "$FPR"
第 6 步的吊销证书必须现在就生成并离线保存。密钥丢失或被窃时,只有拿着它才能向外界宣告「这把钥匙作废了」;事后再生成是来不及的。--gen-revoke 是交互式命令,会要求选择吊销原因并再次输入口令,按提示操作即可。
第二步:对发布产物做分离签名
# 1) 固定使用签名子密钥(! 后缀强制用子密钥,避免误用主密钥)
FPR=ABCD1234EFGH5678IJKL90MNOPQRSTUVWXYZ0123
gpg --armor --detach-sign \
--local-user "$FPR"! \
--output dist/app-1.2.0.tar.gz.asc \
dist/app-1.2.0.tar.gz
# 2) 同时生成 SHA256 清单,便于未装 GPG 的下游做基础校验
( cd dist && sha256sum app-1.2.0.tar.gz > SHA256SUMS )
# 3) 对清单本身也签名,避免校验值被单独替换
gpg --armor --detach-sign --local-user "$FPR"! --output dist/SHA256SUMS.asc dist/SHA256SUMS
# 4) 自检:确认签名可用、且用的是子密钥
gpg --verify dist/app-1.2.0.tar.gz.asc dist/app-1.2.0.tar.gz
gpg --list-packets dist/app-1.2.0.tar.gz.asc | grep -E 'keyid|digest algo'
--local-user "$FPR"! 里的感叹号是强制后缀,意思是「只用这个密钥本身,不要自动挑子密钥」。不加 ! 时 GPG 会按内部规则选一个可签名密钥,一旦主密钥与子密钥都具备签名能力,就可能签在主密钥上,使离线主密钥被拉回联网环境使用。生产签名脚本必须带 !。
第三步:分发公钥并公示指纹
# 1) 导出公钥(只导出公钥,绝不导出私钥)
gpg --armor --export "$FPR" > dist/release-signing-key.asc
# 2) 生成二进制 keyring,供 apt 的 signed-by 直接引用
gpg --dearmor < dist/release-signing-key.asc > dist/release-signing-key.gpg
# 3) 输出可供人工核对的指纹与创建时间
gpg --fingerprint --with-colons "$FPR" | awk -F: '/^fpr/{print "FINGERPRINT:", $10}'
gpg --list-keys --with-colons "$FPR" | awk -F: '/^pub/{print "CREATED:", strftime("%Y-%m-%d", $6)}'
# 4) 同步上传到公钥服务器(可选,便于外部自动拉取,但不要只依赖它)
gpg --keyserver keyserver.ubuntu.com --send-keys "$FPR"
公钥服务器上的公钥可以被任何人上传,同名同邮箱的伪造公钥完全可能存在,因此只从 keyserver 拉公钥等于没有验证。正确做法是把 release-signing-key.asc 放在官网固定路径(如 https://example.com/security/release-signing-key.asc),同时在页面正文、软件包 README、内部 Wiki 三处公示完整 40 位指纹,让用户有独立渠道比对。
第四步:下游验签与 CI 自动化校验
验签不能只看 Good signature 一行字,必须同时校验指纹。下面这段脚本可直接放进流水线,任一步失败即中断发布:
#!/usr/bin/env bash
# verify-release.sh <artifact> <signature> <public-key>
set -euo pipefail
ARTIFACT="$1"; SIGNATURE="$2"; PUBKEY="$3"
EXPECTED_FPR="ABCD1234EFGH5678IJKL90MNOPQRSTUVWXYZ0123"
# 1) 导入前先核对公钥指纹,防止被替换的 keyring 蒙混过关
ACTUAL_FPR=$(gpg --show-keys --with-colons "$PUBKEY" | awk -F: '/^fpr/{print $10; exit}')
if [ "$ACTUAL_FPR" != "$EXPECTED_FPR" ]; then
echo "FAIL: public key fingerprint mismatch ($ACTUAL_FPR)"; exit 1
fi
# 2) 导入到隔离的临时钥匙环,避免污染本机默认 keyring
export GNUPGHOME=$(mktemp -d)
gpg --batch --import "$PUBKEY" 2>/dev/null
# 3) 验签,并额外校验签名者指纹(VALIDSIG 行包含签名子密钥与主密钥指纹)
OUT=$(gpg --status-fd 1 --verify "$SIGNATURE" "$ARTIFACT" 2>/dev/null)
echo "$OUT" | grep -q '^\[GNUPG:\] GOODSIG' || { echo "FAIL: bad signature"; exit 1; }
echo "$OUT" | grep -q "VALIDSIG .* $EXPECTED_FPR" || { echo "FAIL: signer mismatch"; exit 1; }
echo "OK: signature valid, signer $EXPECTED_FPR"
rm -rf "$GNUPGHOME"
注意 VALIDSIG 行末尾是主密钥指纹,中间是签名子密钥指纹。只校验主密钥指纹即可覆盖子密钥轮换的情况——这正是把签名放在子密钥上的另一个好处:换子密钥不需要下游改脚本。
第五步:Git 提交签名
# 1) 指定签名密钥并开启自动签名(! 强制用签名子密钥)
git config --global user.signingkey "$FPR"!
git config --global commit.gpgsign true
git config --global tag.gpgsign true
git config --global gpg.program gpg
# 2) 提交并验证
git commit -m "release: 1.2.0"
git log --show-signature -1
# 期望:gpg: Good signature from "Example Release Signing <release@example.com>"
# 3) 校验已有提交范围是否全部签名(CI 里可作为门禁)
git log --pretty='%H %G?' origin/main..HEAD | awk '$2!="G"{print "UNSIGNED:", $1; rc=1} END{exit rc+0}'
%G? 的输出含义:G 表示签名有效,U 表示签名有效但公钥未受信任,B 表示签名损坏,N 表示无签名。只接受 G,其余一律视为不合规。要让 U 变成 G,需要把签名者公钥导入 CI 的 keyring 并设置信任级别,或在脚本里显式比对指纹。
配置验证
# 1) 篡改检测:改动文件一个字节后验签必须失败
cp dist/app-1.2.0.tar.gz /tmp/tampered.tar.gz
printf 'x' >> /tmp/tampered.tar.gz
gpg --verify dist/app-1.2.0.tar.gz.asc /tmp/tampered.tar.gz
# 期望:BAD signature,退出码非 0
# 2) 签名者身份:确认是签名子密钥而非主密钥
gpg --list-packets dist/app-1.2.0.tar.gz.asc | grep -E 'issuer fpr|keyid'
# 3) 结构确认:主密钥 [C]、子密钥 [S]
gpg --list-keys --keyid-format long "$FPR"
# 4) 分离签名与产物是否配套:哈希应一致
sha256sum -c dist/SHA256SUMS
# 5) 退出码约定:0 通过,非 0 失败,可直接用于脚本判断
gpg --verify dist/app-1.2.0.tar.gz.asc dist/app-1.2.0.tar.gz; echo "exit=$?"
- 完整性:篡改后验签返回
BAD signature,退出码非 0,说明签名确实绑定了内容。 - 身份:
--list-packets里的 keyid 应等于签名子密钥,而不是主密钥。 - 可用性:正常产物验签退出码为 0,脚本可直接依赖该退出码做门禁。
常见问题
Q1:验签输出 Good signature 但带一行 WARNING: This key is not certified with a trusted signature!,这个警告要不要处理?
这句话的意思是:内容没问题,但 GPG 无法确认这把公钥真的属于声称的那个人,因为本机 keyring 没有为它建立信任路径。它不影响「内容未被篡改」的结论,但影响「来源是否真实」的判断。处理方式有两种:一是最稳妥的,人工通过独立渠道(官网公示页、电话、当面)核对 40 位指纹后,用 gpg --import-ownertrust 把该密钥标为完全信任;二是工程化方式,不依赖 GPG 的信任网,而是在脚本里显式比对 VALIDSIG 行末的指纹与硬编码的期望值,指纹不匹配就失败。后者更适合 CI,因为它不依赖本机 keyring 状态,行为完全确定。
Q2:为什么签名要指定子密钥,而且必须带 !?
三个原因。第一,隔离风险:主密钥离线保存,联网机器上只有签名子密钥,泄露后损失可控且可通过吊销证书止损。第二,便于轮换:子密钥有独立有效期,到期换新子密钥、重新分发自签名即可,下游不需要改任何地址或指纹。第三,避免歧义:主密钥若同时具备 cert 与 sign 能力,GPG 可能挑主密钥来签,导致离线密钥被迫上线。带 ! 时 GPG 只使用指定密钥本身,不做子密钥推断,行为可预测。如果签名后发现 --list-packets 里 keyid 与预期不符,就是漏了 !。
Q3:密钥过期了,之前签发的签名还有效吗?怎么续期?
已签发的签名仍然有效。OpenPGP 的时间判定基于签名生成时刻,密钥在签名时有效即可;过期只影响「之后能否再签」以及验签时是否附加 EXPKEYSIG 提示,脚本里若只检查 GOODSIG 就会通过。续期需要主密钥在场,用 gpg --quick-set-expire "$FPR" 2y 延长主密钥,用 gpg --quick-set-expire "$FPR" 1y '*' 把全部子密钥设为 1 年,然后重新导出公钥并分发——下游必须拿到更新后的公钥,否则本地 keyring 里的过期信息不会自动刷新。若密钥已泄露而非单纯过期,正确做法是导入吊销证书,gpg --import release-revoke.asc 并上传 keyserver,而不是续期。
Q4:GPG 签名和镜像签名(cosign)、SBOM 是重复投入吗?
三者解决不同层面的问题,互不替代。GPG 签名作用于文件与提交,是通用的字节级完整性与来源证明,不限定生态;cosign 作用于容器镜像,把签名写进镜像仓库的附属制品,并与 OIDC 身份绑定,解决「这个镜像由哪条流水线的哪个身份构建」;SBOM 是成分清单,回答「里面有哪些依赖」,本身不含签名,但可以被 GPG 或 cosign 签名后一起分发。实践中常见组合是:源码提交用 GPG 签名,构建产物(tar.gz/deb/rpm)用 GPG 分离签名,镜像用 cosign 签名,SBOM 作为产物之一被同一把密钥签名。这样任何一层被替换都能被发现。
总结
GPG 签名验签的落地不复杂,难的是把「信任」这件事做对。技术上只需四步:离线主密钥 + 可轮换签名子密钥、--detach-sign 分离签名、独立渠道分发公钥、脚本中同时校验 GOODSIG 与 VALIDSIG 指纹。真正决定成败的是流程:吊销证书是否提前生成并离线保存、指纹是否在官网与文档中公示、CI 是否把验签失败设为硬门禁、子密钥到期是否有提醒。把这四点写进发布规范,签名才有意义;否则一把从不轮换、指纹无人核对、验签失败只打警告的密钥,只是给审计交了一份看起来合规的材料。