逐行解读kubesec加密Secret文件格式从# kubesec:v:4到mac的v1-v4版本演进【免费下载链接】kubesecSecure Secret management for Kubernetes (with gpg, Google Cloud KMS and AWS KMS backends)项目地址: https://gitcode.com/gh_mirrors/kub/kubesec如果你用过 kubesec 为 Kubernetes Secret 加密多半在加密文件末尾见过# kubesec:v:4、# kubesec:mac:...这样一行行注释。kubesec 是面向 Kubernetes 的 Secret 加密管理工具支持 gpgPGP、Google Cloud KMS 与 AWS KMS 三种后端让你把加密后的 Secret 直接提交到 VCS。本文逐行解读 kubesec 加密 Secret 文件格式从# kubesec:v:4到mac字段带你理清 v1-v4 的完整版本演进。一、kubesec 加密文件长什么样先看全貌kubesec 的设计哲学是只加密data和stringData里的值密钥名保持不变。这样git diff和git merge依然友好即使没有解密密钥你也能确认某个条目是否存在这一点在 README.md 中有明确说明。一份典型的加密 Secret 文件结构如下apiVersion: v1 kind: Secret metadata: name: myapp-default-0 data: KEY: TUFkWD1iuKs.O....D... ANOTHER_KEY: iOy1nf90M6FrrEIoymN6cOSUYM.E....q... type: Opaque # kubesec:v:4 # kubesec:pgp:160A7A9CF46221A56B06AD64461A804F2609FD89:LS0tLS1CRUdJTi... # kubesec:aws:arn:aws:kms:us-west-1:000000000000:key/...:QmVmdXJl... # kubesec:mac:PYsYSsk... 注意整个加密协议头都藏在以#开头的 YAML 注释行里统一位于文件末尾且共享# kubesec:前缀。这套前缀常量定义在cmd/encrypt.go的 L84-L94常量值含义NS# kubesec:所有协议行的公共前缀NSVersionv:格式版本标记NSPGPpgp:PGP 密钥行NSGCPKMSgcp:Google Cloud KMS 密钥行NSAWSKMSaws:AWS KMS 密钥行NSMACmac:完整性校验值kubesec 判断一个文件是否已被加密靠的就是在正文之后找到\n# kubesec:v:cmd/encrypt.goL165-L167 的IsEncrypted。二、# kubesec:v:4版本标记v1-v4 演进时间线版本常量定义在cmd/encrypt.goL22-L25const version 1 // v1初始版本 const versionWithAWSKMSAndGCPKMSSupport 2 // v2新增 KMS 后端 const versionWithMAC 3 // v3新增 MAC const versionWithStringDataSupport 4 // v4新增 stringData对照 CHANGELOG.md四个版本的演进一目了然版本标记kubesec 版本发布日期新增能力v:10.1.02017-08-11基础 PGP 加密 DEKv:20.2.02017-08-29新增 Google Cloud KMS / AWS KMS 后端v:30.3.02017-09-16新增mac完整性校验AES-GMACv:40.9.02018-06-25支持stringData字段的加解密 有个容易忽略的细节版本号并非越高越新。marshalWithEncryptionContextcmd/encrypt.goL342-L366在写文件时默认写v:3只有当 Secret 里真的存在stringData字段时才升级为v:4。也就是说v:4本质是含 stringData 的 v3。解密时reconstructEncryptionContextcmd/decrypt.goL76-L129会逐行扫描所有# kubesec:注释行遇到v:行就用IsVersionSupported校验遇到不支持的版本会直接报错提示你升级 kubesec——这保证了向前兼容的硬边界。三、pgp / gcp / aws 密钥行DEK 如何被保护先理解一个核心概念数据加密密钥DEK。kubesec 加密流程是典型的两层结构为每个 Secret 随机生成一把 256-bit 的 DEKcmd/encrypt.goL180-L186用 DEK 以 AES-GCM 加密data/stringData里的每个值再把 DEK 本身交给--key指定的一个或多个主密钥PGP 指纹 / GCP KMS 密钥 / AWS KMS 密钥加密写成# kubesec:pgp:...等注释行。每条密钥行的格式为# kubesec:类型:密钥ID:base64(加密后的DEK)其中pgp 行密钥 ID 是 PGP 指纹≥16 位十六进制加密后的 DEK 是PGP 加密 签名的产物gpg.EncryptAndSign见cmd/encrypt.goL368-L387gcp / aws 行密钥 ID 分别是projects/...资源路径或arn:...加密后 DEK 直接是 KMS 返回的密文。解密端cmd/decrypt.go的loadPGPKey/loadGCPKMSKey/loadAWSKMSKey三个函数分别逐行还原这些信息并尝试用本地密钥/云凭证解开第一个可解的 DEK。 安全机制亮点当你用--key-...移除某个主密钥时KeySetMutation.applyTocmd/encrypt.goL400-L427会自动触发DEK 轮换RotateDEK因为被移出信任链的人可能还留着手里的旧文件。四、mac行AES-GMAC 完整性校验逐行解析# kubesec:mac:行是整个格式里最容易被误删的一行。它在 v3 引入作用是任何对 data 值或密钥行的篡改包括git merge产生的冲突残留都会让解密直接失败。生成逻辑在cmd/encrypt.go的computeMACL224-L238AAD附加认证数据 data stringData 的所有键值按 key 排序 所有密钥 ID排序后由gatherAdditionalAuthenticatedDataForMACL240-L262构造——注意 MAC 绑定的是明文内容与密钥集合不只是密文用 DEK 做 AES-GMAC空明文加密得到 MAC 值追加为文件最后一行。有一个精巧的稳定性设计重加密时若旧 MAC 用新 DEK 验证通过说明数据没变就原样复用旧 MACL226-L232避免无意义的 diff 噪音。而老文件用户会遇到这条友好报错cmd/decrypt.goL118-L127遇到v:1/v:2且缺 MAC 的文件kubesec 提示你执行kubesec edit -i --recompute-mac secret.enc.yml人工确认内容后补算 MAC文件即升级为 v3。五、data 值里的三段式密文不止是 base64data下每个值形如TUFkWD1iuKs.O....D...用.分成最多三段每段都是独立 base64段内容说明第 1 段密文AES-GCM 输出去掉 tag 部分第 2 段IV96-bit12 字节随机数GCM 标准长度第 3 段tag16 字节认证标签解析代码在crypto/aes/cipher.go的parse函数L56-L80若只有两段如mac这种空明文 GMAC会自动补一个空的第一段。另外两个细节48 字节块填充cmd/encrypt.goL19-L20 把每个值补齐到 48 字节的整数倍再加密防止密文长度泄露原文长度解密时按首个\u0000截断还原cmd/decrypt.goL61-L64。IV 缓存内容未变化的字段在重新加密时会复用原 IVcrypto/aes/cipher.goL91-L99 的 stash 机制配合--parent选项可实现解密→修改→保 DEK 重加密而 diff 最小化。六、实用技巧introspect 与常见故障排查谁有权限解密这个 Secret运行kubesec introspect secret.enc.ymlcmd/introspect.go会解析所有# kubesec:行按 PGP / GCP KMS / AWS KMS 分组列出密钥 IDPGP 指纹还会尝试匹配本地公钥的 UID让你不用解密就能审计访问范围。症状原因解法MACs dont matchdata 或密钥行被改动常见于 merge 冲突核对内容后kubesec edit -i --recompute-macMAC is missingv1/v2 旧文件同上补算 MACSecret was encrypted with newer version本地 kubesec 版本过旧升级 kubesecUnable to decrypt DEK本地没有任何能解开 DEK 的密钥--debug查看逐个尝试的明细七、小结一张表看懂格式协议行格式引入版本作用版本行# kubesec:v:1-4v1声明格式版本控制兼容边界密钥行# kubesec:pgp/gcp/aws:id:b64(DEK)v1/v2存放被主密钥加密的 DEKMAC 行# kubesec:mac:gmacv3数据密钥的 AES-GMAC 完整性校验data 值b64(密文).b64(IV).b64(tag)v148 字节填充 AES-GCM 加密回到文章开头的问题# kubesec:v:4到mac这一小段注释就是 kubesec 全部安全承诺的载体——版本行划定兼容边界密钥行保管 DEKmac 行守住完整性。理解了这套逐行协议你也就读懂了 kubesec 为什么敢把加密后的 Secret 放心放进 Git。【免费下载链接】kubesecSecure Secret management for Kubernetes (with gpg, Google Cloud KMS and AWS KMS backends)项目地址: https://gitcode.com/gh_mirrors/kub/kubesec创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考