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

2. 环境准备：安装 Cosign CLI、配置 OIDC 身份提供商、初始化密钥对

本章是 Cosign 签名链路模板化配置的实操起点。在开始签名与验证之前，必须完成三个基础环境的搭建：Cosign CLI 安装、OIDC 身份提供商配置以及密钥对初始化。以下内容将按照生产级标准，分步骤完成环境准备。

2.1 安装 Cosign CLI

Cosign 官方提供多种安装方式，推荐使用二进制安装或包管理器安装，确保版本一致性与可重复性。下表列出主流操作系统的安装命令与验证方法：

操作系统	安装命令	验证命令
Linux (amd64)	`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 bucket add extras; scoop install cosign`	`cosign version`
容器化安装	`docker pull gcr.io/projectsigstore/cosign:latest`	`docker run --rm gcr.io/projectsigstore/cosign:latest version`

版本锁定建议： 生产环境中请使用固定版本号（如 v2.2.3）而非 latest，避免因版本升级导致签名链路行为不一致。可通过 cosign version 输出中的 GitVersion 字段确认当前版本。

2.2 配置 OIDC 身份提供商

Cosign 支持通过 OIDC（OpenID Connect）进行无密钥签名，这是 Sigstore 生态的核心能力。配置 OIDC 身份提供商（IdP）后，Cosign 可以自动获取短期证书，无需手动管理长期密钥。以下以 GitHub Actions 和 Google Cloud Workload Identity Federation 为例，展示两种主流 IdP 的配置要点。

IdP 类型	配置项	说明
GitHub Actions	`id-: write` 权限	在 workflow 中设置 `permissions: id-: write`，Cosign 自动通过 `ACTIONS_ID__REQUEST_` 环境变量获取 OIDC
GitLab CI	`id_tokens` 配置块	在 `.gitlab-ci.yml` 中定义 `id_tokens: SIGSTORE_ID_: { aud: sigstore }`
Google Cloud	Workload Identity Pool	创建 Workload Identity Pool 和 Provider，绑定服务账号，Cosign 通过 `google-github-actions/auth` 获取 OIDC
其他 OIDC 兼容 IdP	自定义 Issuer URL	通过 `--oidc-issuer` 参数指定 IdP 地址，并确保 Cosign 信任该 Issuer 的根证书

  OIDC 配置检查清单：
  确认 IdP 已签发 OIDC ，且  中包含 sub、iss、aud 等标准声明。
确保 Cosign CLI 版本 ≥ v2.0.0，旧版本对 OIDC 支持不完整。
在 CI/CD 环境中，OIDC  的过期时间通常为 5-10 分钟，签名操作需在有效期内完成。

2.3 初始化密钥对

虽然 OIDC 模式可以免去密钥管理，但在离线环境、自建 Sigstore 或需要长期密钥签名的场景下，仍需初始化密钥对。Cosign 支持生成加密密钥对（RSA/ECDSA）和纯密钥对（无加密）。

以下命令生成一个加密的 ECDSA P-256 密钥对，并输出到指定路径：

# 生成加密密钥对（推荐用于生产环境）
cosign generate-key-pair \
  --output-key-pair cosign.key \
  --output-key-pair cosign.pub \
  --kms false

# 系统会提示输入加密密码，请使用强密码并妥善保管
# 输出文件：
#   cosign.key  — 私钥（加密存储）
#   cosign.pub  — 公钥（明文存储）

对于纯密钥对（无加密密码），适用于自动化流水线中密钥由 KMS 管理的场景：

# 生成纯密钥对（无加密，配合 KMS 使用）
cosign generate-key-pair \
  --output-key-pair cosign.key \
  --output-key-pair cosign.pub \
  --kms false \
  --no-password true

密钥安全警告：

私钥文件（cosign.key）必须设置 chmod 600 权限，禁止提交到版本控制系统。
加密密码建议使用密码管理器生成并存储，不要硬编码在脚本或 CI 配置中。
公钥（cosign.pub）可以公开分发，用于验证方导入信任根。

2.4 环境准备整体流程

下图展示了从安装 CLI 到完成密钥初始化的完整链路，以及 OIDC 模式与密钥对模式的分支选择：

2.5 验证环境就绪

完成上述步骤后，执行以下命令验证环境是否准备完毕：

# 1. 验证 Cosign CLI 版本
cosign version

# 2. 验证 OIDC  可获取（以 GitHub Actions 为例）
echo $ACTIONS_ID__REQUEST_ | head -c 20

# 3. 验证密钥对文件存在且权限正确
ls -la cosign.key cosign.pub
stat -c "%a %n" cosign.key  # 应输出 600 cosign.key

# 4. 测试公钥可读取
cosign public-key --key cosign.key

快速排障： 如果 cosign public-key 提示密码错误，请确认输入的加密密码与生成时一致。如果 OIDC 获取失败，检查 CI 平台的 OIDC 权限配置是否已正确开启。