容器镜像签名工具 (Signatures for container images) 镜像文档

1. 镜像概述

1.1 概述

本镜像是一款轻量级容器镜像签名与验证工具，基于OCI（开放容器倡议）标准构建，提供命令行界面用于对容器镜像进行数字签名、签名验证及密钥管理。通过加密算法确保镜像在分发和部署过程中的完整性、真实性和来源可信性，是容器供应链安全的核心保障工具。

1.2 主要用途

• 对容器镜像进行数字签名，生成不可篡改的签名元数据
• 验证容器镜像的签名信息，确认镜像未被篡改且来源可信
• 管理签名密钥（生成、导入、导出、轮换）
• 集成CI/CD流水线，实现自动化签名与验证流程
• 与主流容器 registry（如Docker Hub、Harbor、AWS ECR）无缝对接

2. 核心功能和特性

2.1 签名与验证

• 支持多种非对称加密算法：RSA（2048/4096位）、ECDSA（P-256/P-384）、ED25519
• 兼容OCIv1镜像规范，支持所有符合OCI标准的容器镜像（如Docker、containerd镜像）
• 签名元数据支持嵌入镜像manifest或独立文件存储

2.2 密钥管理

• 内置密钥生成工具，支持自动生成公私钥对
• 支持外部密钥导入/导出（PEM格式），兼容主流密钥管理系统（KMS）
• 私钥加密存储，支持密码保护

2.3 集成能力

• 原生支持Docker、containerd等容器运行时
• 适配CI/CD工具链（Jenkins、GitLab CI、GitHub Actions）
• 支持私有/公共容器registry认证（用户名密码、token、TLS）

2.4 安全性与合规

• 签名过程全程内存加密，避免密钥泄露
• 支持签名元数据审计日志输出（JSON格式）
• 符合NIST SP 800-177数字签名标准

3. 使用场景和适用范围

3.1 典型使用场景

• 企业内部镜像分发：确保内部团队共享的镜像未被篡改，仅可信镜像可部署至生产环境
• 开源项目镜像发布：向用户提供可验证的***镜像，证明镜像来源为项目维护者
• CI/CD流水线集成：在镜像构建后自动签名，部署前强制验证签名，形成"构建-签名-验证-部署"闭环
• 多团队协作：通过统一签名策略管控跨团队镜像共享，确保镜像符合安全基线
• 合规审计：满足***、***等行业对软件供应链可追溯性的合规要求

3.2 适用范围

• 容器平台：Docker、Kubernetes、containerd、CRI-O
• 镜像仓库：Docker Hub、Harbor、GitLab Container Registry、AWS ECR、Azure ACR
• 架构支持：linux/amd64、linux/arm64

4. 使用方法和配置说明

4.1 镜像拉取

bash
# 拉取最新版
docker pull [镜像仓库地址]/signatures-for-container-images:latest

# 拉取指定版本（如v1.2.0）
docker pull [镜像仓库地址]/signatures-for-container-images:v1.2.0

4.2 基础命令格式

工具通过命令行参数执行操作，基本语法：

bash
docker run --rm -v [本地目录]:/work [镜像名称] [命令] [参数]

• --rm：容器退出后自动清理
• -v [本地目录]:/work：挂载本地目录用于密钥、签名文件的持久化存储

4.3 密钥管理

4.3.1 生成密钥对

生成RSA-4096密钥对（默认存储路径/work/keys）：

bash
docker run --rm -v $(pwd)/keys:/work/keys signatures-for-container-images \
  key generate \
  --algorithm rsa \
  --bits 4096 \
  --key-path /work/keys

生成后文件结构：

./keys/
├── private.key  # 私钥（PEM格式，需加密存储）
└── public.key   # 公钥（PEM格式，用于验证签名）

4.3.2 导入外部密钥

导入已有的PEM格式私钥：

bash
docker run --rm -v $(pwd)/my-keys:/work/my-keys -v $(pwd)/keys:/work/keys \
  signatures-for-container-images \
  key import \
  --type private \
  --input /work/my-keys/existing-private.pem \
  --output /work/keys/imported-private.key \
  --password "密钥密码"  # 若私钥加密

4.4 镜像签名

4.4.1 签名本地镜像

对本地myapp:v1.0镜像签名（需挂载Docker守护进程socket访问本地镜像）：

bash
docker run --rm \
  -v $(pwd)/keys:/work/keys \
  -v $(pwd)/signatures:/work/signatures \
  -v /var/run/docker.sock:/var/run/docker.sock \  # 访问本地Docker
  signatures-for-container-images \
  sign \
  --image myapp:v1.0 \
  --private-key /work/keys/private.key \
  --output /work/signatures/myapp-v1.0.sig \  # 签名文件输出路径
  --algorithm rsa  # 可选，默认使用密钥对应算法

4.4.2 签名远程仓库镜像

对私有仓库harbor.example.com/library/myapp:v1.0签名：

bash
docker run --rm \
  -v $(pwd)/keys:/work/keys \
  signatures-for-container-images \
  sign \
  --image harbor.example.com/library/myapp:v1.0 \
  --private-key /work/keys/private.key \
  --registry-url harbor.example.com \
  --registry-username admin \
  --registry-password Harbor***  # 仓库认证信息

4.5 镜像签名验证

4.5.1 验证本地镜像

验证本地myapp:v1.0镜像的签名：

bash
docker run --rm \
  -v $(pwd)/keys:/work/keys \
  -v $(pwd)/signatures:/work/signatures \
  -v /var/run/docker.sock:/var/run/docker.sock \
  signatures-for-container-images \
  verify \
  --image myapp:v1.0 \
  --public-key /work/keys/public.key \
  --signature /work/signatures/myapp-v1.0.sig

验证成功输出：

[INFO] Signature verification succeeded
Image: myapp:v1.0
Signer: [公钥指纹]
Signature time: 2024-05-20T10:30:00Z
Integrity check: PASSED

4.5.2 验证远程镜像

验证远程仓库镜像签名：

bash
docker run --rm \
  -v $(pwd)/keys:/work/keys \
  signatures-for-container-images \
  verify \
  --image harbor.example.com/library/myapp:v1.0 \
  --public-key /work/keys/public.key \
  --registry-url harbor.example.com

4.6 环境变量配置

通过环境变量简化命令参数，支持的变量如下：

示例：使用环境变量简化签名命令

bash
docker run --rm -v $(pwd)/data:/work \
  -e SIGN_KEY_PATH=/work/keys/prod-key.key \
  -e REGISTRY_URL=harbor.example.com \
  -e REGISTRY_USERNAME=admin \
  -e REGISTRY_PASSWORD=Harbor*** \
  signatures-for-container-images \
  sign --image myapp:v1.0

5. Docker部署示例

5.1 密钥生成与镜像签名完整流程

bash
# 1. 创建工作目录
mkdir -p ./keys ./signatures

# 2. 生成ECDSA密钥对
docker run --rm -v $(pwd)/keys:/work/keys \
  signatures-for-container-images \
  key generate --algorithm ecdsa --bits 384 --key-path /work/keys

# 3. 对本地镜像签名（假设已构建myapp:v1.0）
docker run --rm -v $(pwd)/keys:/work/keys -v $(pwd)/signatures:/work/signatures -v /var/run/docker.sock:/var/run/docker.sock \
  signatures-for-container-images \
  sign \
  --image myapp:v1.0 \
  --private-key /work/keys/private.key \
  --output /work/signatures/myapp-v1.0.sig

# 4. 验证签名
docker run --rm -v $(pwd)/keys:/work/keys -v $(pwd)/signatures:/work/signatures -v /var/run/docker.sock:/var/run/docker.sock \
  signatures-for-container-images \
  verify \
  --image myapp:v1.0 \
  --public-key /work/keys/public.key \
  --signature /work/signatures/myapp-v1.0.sig

6. 注意事项

• 私钥安全：私钥是签名核心，需存储在加密介质（如Vault、KMS），禁止直接挂载到容器持久化存储
• Docker socket挂载风险：挂载/var/run/docker.sock会授予容器对Docker守护进程的访问权限，生产环境建议使用远程镜像验证替代本地镜像操作
• 密钥轮换：建议每90天轮换一次签名密钥，旧密钥需保留用于验证历史镜像
• registry认证：访问私有仓库时，优先使用token认证（如 Harbor 的机器人账户token）而非明文密码

7. 命令参考