kas 仓库签名验证完整指南:GPG/SSH 密钥配置与供应链安全加固
kas 仓库签名验证完整指南:GPG/SSH 密钥配置与供应链安全加固
在构建 OpenEmbedded/BitBake 项目时,你是否担心上游仓库被恶意篡改?kas 是面向 bitbake 构建系统的初始化设置工具,它内置的仓库签名验证功能,可以在 checkout 前校验 Git 仓库的 commit/tag 签名,只放行由受信任 GPG/SSH 密钥签发的内容——这是加固供应链安全最直接的一步。本文带你从零掌握 kas 签名验证的完整配置方法。
为什么需要仓库签名验证?
kas 的典型工作流是:解析 YAML 配置文件 → 按配置克隆若干 Git 仓库 → 执行 bitbake 构建。攻击者若能劫持 DNS、中间人劫持或投毒镜像,就可能让构建者拉取到被篡改的源码。kas 的签名验证机制能堵住这个缺口:
- ✅ 只有携带受信任密钥签名的 commit 或 tag 才会被检出
- ✅ 验证失败直接报错(
RepoRefError),构建终止,绝不静默通过 - ✅ 自 5.3 版本起,验证在检出(checkout)之前执行(修复了 CVE-2026-47192),杜绝了"先检出、再验证"的时间窗口
该功能由 kas/keyhandler.py 中的 GPGKeyHandler / SSHKeyHandler 和 kas/repos.py 中的 SignatureValidator 类实现。
30 秒看懂配置结构
kas 签名验证的配置分两处,位于同一个 kas YAML 配置文件中:
| 配置项 | 位置 | 作用 |
|---|---|---|
signers |
顶层字典 | 定义受信任的公钥/证书来源,每个条目有唯一 signer_id |
signed |
仓库条目内 | 布尔值,设为 true 表示强制校验签名 |
allowed_signers |
仓库条目内 | 列出允许签名的 signer_id 列表 |
⚠️ 注意:
signed一旦启用,allowed_signers必须非空,否则 kas 直接报KasUserError。且同一仓库的多个 signer 必须使用同一种类型(GPG 与 SSH 不可混用)。
GPG 密钥配置:两种方式任选
方式一:从密钥服务器在线获取(推荐用于知名上游)
只需提供 gpg_keyserver 和 40 位十六进制 fingerprint。kas 会通过 GnuPG 从服务器拉取密钥,并严格比对指纹,不一致则抛出 KeyImportError:
signers:
jan-kiszka:
fingerprint: CA5F8C00F5FBC85466016C808AD4AC6F7AE5E714
gpg_keyserver: keyserver.ubuntu.com
repos:
kas:
url: https://example.com/kas.git
tag: '4.3'
commit: f650ebe2495a9cbe2fdf4a2c8becc7b3db470d55
signed: true
allowed_signers:
- jan-kiszka
指纹可通过 gpg --list-keys --with-fingerprint --keyid-format=long <KEYID> 获取(去掉空格后的 40 位字符串)。若密钥已缓存在本地,kas 会跳过下载并复用缓存。
方式二:从仓库文件导入本地密钥文件
若密钥服务器不可达(如离线环境),可将公钥文件(如 *.asc)放入某个仓库,用 repo + path 指向它:
signers:
my-maintainer:
repo: meta-keys # 提供密钥文件的仓库
path: keys/maintainer.asc
完整字段说明见官方文档 docs/userguide/project-configuration.rst 中 signers 一节。
SSH 密钥配置:Git 原生 SSH 签名的最佳拍档
Git 本身支持 SSH 签名(gpg.format = ssh),但 kas 需要公钥文件来构造校验。设置 type: ssh 并指向仓库内的 .pub 公钥文件即可:
signers:
testkey:
type: ssh
repo: this
path: ssh/testkey.pub
repos:
local:
path: testrepo
tag: signed-tag
signed: true
allowed_signers:
- testkey
kas 会调用 ssh-keygen 解析公钥,支持 RSA、ECDSA、ED25519 等类型,并通过 git 的 allowedSignersFile 机制完成校验。可选的 fingerprint 字段使用 SHA256:... 格式,可用 ssh-keygen -lf key.pub | awk '{print $2}' 获取。官方测试用例 tests/test_signature_verify/test-ssh-key.yml 展示了完整用法。
kas 的安全设计细节(值得一看)
理解底层机制能帮你排查问题。实现细节都在 kas/keyhandler.py 与 kas/repos.py:
- 隔离的本地密钥库:kas 在工作目录创建独立的
.kas_gnupg(GPG)与.kas_ssh-handler(SSH)目录(权限0700),不污染你系统的 GnuPG 主密钥环。 - 信任重置:每次运行先把密钥库中所有密钥的信任级别重置为
TRUST_NEVER,再只对你配置中导入的密钥授予TRUST_ULTIMATE——配置之外的任何密钥都不可信。 - 指纹强校验:无论是从服务器下载还是从文件导入,实际密钥指纹与配置声明不符都会触发
KeyImportError,防止"同 ID 不同钥"的欺骗攻击。 - 校验命令:若配置了 tag,执行
git verify-tag --raw <tag>(只验 tag 签名);否则执行git verify-commit --raw <commit>。 - 环境透传:GPG 密钥库路径会通过
GNUPGHOME环境变量注入构建环境,bitbake 等下游任务也能复用同一套受信任密钥。
验证通过时,日志会打印类似 Repository kas signature valid: Fingerprint CA5F... from "..." 的友好信息;失败则抛出 RepoRefError 并指明是哪个密钥签的(或未签名)。
供应链安全加固清单 🛡️
- 永远固定 commit:仅用 tag 或 branch 是危险的(kas 会主动告警"tags are mutable"),
commit + tag + signed三者组合最稳妥——tag 防篡改、commit 防重放。 - 优先离线密钥文件:内网/生产环境避免依赖外部密钥服务器,把公钥文件放入自己可控的仓库。
- 写全指纹:即使有密钥文件,也建议同时声明
fingerprint,双保险。 - 逐仓库启用:不需要对每个仓库都强制签名,可按风险等级只对关键上游开启
signed: true。 - 搭配构建证明:签名验证解决"源码可信",kas 的 kas/attestation.py 则按 SLSA/in-toto 标准生成构建溯源证明,两者结合形成完整的供应链信任链。
常见问题排查
| 现象 | 原因与对策 |
|---|---|
Could not import key ... Fingerprints do not match |
配置中的 fingerprint 与实际密钥不符,重新核对 40 位指纹 |
No keys imported / Multiple keys imported |
密钥服务器按指纹查不到唯一密钥,检查服务器可用性 |
not signed with a trusted key |
commit/tag 的签名者不在 allowed_signers 中,确认上游确实签名且 signer 声明正确 |
| GPG 相关功能不可用 | 需安装 python-gnupg 模块,否则 kas 报 MissingModuleError |
| SSH 类型不支持报错 | 确认 type: ssh 且公钥文件路径正确,仅 git 仓库支持签名验证 |
结语
kas 的仓库签名验证用不到 10 行 YAML,就为你的 bitbake 构建加装了一道"数字门卫":GPG 与 SSH 双协议支持、隔离密钥库、指纹强校验、检出前验证,层层防线确保每一行源码都来自你信任的签名者。如果你的项目依赖众多上游仓库,这套机制值得今天就配上——毕竟,供应链安全的最佳时机,永远是第一次构建之前。