📚 课程目录第4章环境准备

4. 环境准备：安装 Cosign CLI、配置 OIDC 认证、初始化密钥对（本地与云端）

本章是《基于 Cosign 的镜像供应链信任边界驱动开发实践》的实操起点。在构建信任边界之前，必须完成 Cosign 工具链的本地部署、身份认证体系对接以及密钥材料的初始化。以下步骤将确保你拥有一个可复现、可审计的签名环境。

4.1 安装 Cosign CLI

Cosign 是 Sigstore 项目提供的命令行工具，支持容器镜像签名、验证和存储。根据操作系统选择对应的安装方式：

操作系统	安装命令 / 方式	验证命令
Linux (amd64/arm64)	`# 下载最新二进制 curl -O -L "https://github.com/sigstore/cosign/releases/latest/download/cosign-linux-amd64" sudo mv cosign-linux-amd64 /usr/local/bin/cosign sudo chmod +x /usr/local/bin/cosign`	`cosign version`
macOS (Homebrew)	`brew install cosign`	`cosign version`
Windows (Scoop)	`scoop install cosign`	`cosign version`
容器化运行	`docker pull gcr.io/projectsigstore/cosign alias cosign='docker run --rm -v $HOME/.cosign:/root/.cosign gcr.io/projectsigstore/cosign'`	`cosign version`

版本锁定建议： 生产环境中建议锁定 Cosign 的次版本号（如 v2.2.x），避免因主版本升级导致的 CLI 参数不兼容。使用 cosign version 确认安装版本后，可通过 cosign completion 生成 shell 自动补全脚本。

4.2 配置 OIDC 认证

Cosign 支持通过 OpenID Connect (OIDC) 与云服务商的身份平台集成，实现免密钥签名。这是实现“信任边界驱动开发”中身份即策略的关键环节。以下以主流云平台为例：

云平台	OIDC 提供商	环境变量 / 配置	认证方式
GitHub Actions	`https://.actions.githubusercontent.com`	`export COSIGN_EXPERIMENTAL=1`	自动从 Actions OIDC 获取身份
GitLab CI	`https://gitlab.com`	`export COSIGN_EXPERIMENTAL=1 export COSIGN_OIDC_ISSUER=https://gitlab.com`	使用 ID 进行密钥对生成
Google Cloud	`https://accounts.google.com`	`gcloud auth login export COSIGN_EXPERIMENTAL=1`	通过 gcloud 凭证获取 OIDC
手动 OIDC 登录	自定义 OIDC 提供商	`cosign login <registry> -u <user> -p <>`	交互式浏览器认证或 device flow

安全警告： 在本地开发环境中启用 COSIGN_EXPERIMENTAL=1 会启用密钥对自动生成与 Fulcio 证书签发。该模式依赖网络可达的 Sigstore 公共实例。若在离线或内网环境，必须预先配置私有 Fulcio 和 Rekor 实例，否则签名操作将失败。

4.3 初始化密钥对（本地与云端）

Cosign 支持两种密钥管理模式：本地密钥对（适用于自托管信任根）和云端密钥对（通过 KMS 或 OIDC 动态生成）。以下对比两种模式的适用场景：

特性	本地密钥对	云端密钥对（KMS / OIDC）
密钥存储	本地文件系统（`~/.cosign/`）	云 KMS（AWS KMS / GCP KMS / Azure Key Vault）
私钥暴露风险	高（需手动保护文件权限）	低（私钥不出 KMS 边界）
轮换策略	手动执行	自动或半自动（KMS 版本管理）
审计能力	无内置审计	完整云审计日志
推荐场景	开发测试、小型团队	生产环境、合规要求严格

4.3.1 生成本地密钥对

# 生成加密私钥和公钥（密码短语保护）
cosign generate-key-pair

# 输出示例：
# Enter password for private key: ********
# Enter password for private key again: ********
# Private key written to cosign.key
# Public key written to cosign.pub

# 查看生成的密钥信息
cosign public-key --key cosign.key
# 输出：-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----

  密钥文件安全基线：
  cosign.key 权限必须设置为 600（仅所有者可读写）。
密码短语强度建议不低于 16 位，包含大小写字母、数字和特殊字符。
将 cosign.pub 上传至代码仓库的 .cosign/ 目录，供 CI/CD 验证使用。
切勿将 cosign.key 提交到版本控制系统。

4.3.2 配置云端密钥对（以 AWS KMS 为例）

# 前提：已配置 AWS CLI 凭证，且拥有 kms:CreateKey 权限

# 1. 创建非对称 KMS 密钥（ECC_NIST_P256 或 RSA_4096）
aws kms create-key --key-usage SIGN_VERIFY --customer-master-key-spec ECC_NIST_P256

# 2. 记录返回的 KeyId（例如：1234abcd-12ab-34cd-56ef-1234567890ab）

# 3. 使用 Cosign 引用 KMS 密钥
export COSIGN_KMS_KEY="awskms:///1234abcd-12ab-34cd-56ef-1234567890ab"

# 4. 通过 KMS 签名（无需本地私钥文件）
cosign sign --key $COSIGN_KMS_KEY <镜像引用>

4.4 密钥初始化流程总览

下图展示了从 CLI 安装到密钥就绪的完整链路，以及本地与云端两种模式的并行路径：

4.5 环境就绪检查清单

完成上述步骤后，使用以下清单确认环境已正确配置：

CLI 可用性： cosign version 返回版本号且无报错。
OIDC 连通性： cosign verify 在未指定密钥时提示“experimental mode enabled”或成功触发浏览器认证。
本地密钥对： ls -la ~/.cosign/ 包含 cosign.key 和 cosign.pub，且 cosign.key 权限为 600。
云端密钥对： cosign public-key --key $COSIGN_KMS_KEY 能正确导出公钥。
签名测试： 对一个测试镜像（如 busybox:latest）执行 cosign sign 并验证签名，确认端到端链路正常。