3. 环境准备：安装 Cosign CLI、配置 OIDC 认证、初始化密钥对

本章是实践课程的基石环节。在开始镜像签名、水位巡检与阈值建模之前，必须完成以下三项核心准备工作：安装 Cosign 命令行工具、配置基于 OIDC 的身份认证、以及初始化用于签名的密钥对（涵盖本地密钥与云密钥管理服务 KMS）。以下步骤均以生产环境稳定性为前提，兼顾安全性与可复现性。

3.1 安装 Cosign CLI

Cosign 是 Sigstore 项目提供的无密钥签名工具，支持多种安装方式。推荐使用官方发布的最新稳定版本，以确保与 Sigstore 生态的兼容性。

# 下载最新二进制
wget "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

brew install cosign

# 使用官方安装脚本
iwr -useb https://github.com/sigstore/cosign/releases/latest/download/cosign-windows-amd64.exe -OutFile cosign.exe
# 将 cosign.exe 添加到 PATH

docker pull gcr.io/projectsigstore/cosign:latest
alias cosign='docker run --rm -v $HOME/.cosign:/root/.cosign gcr.io/projectsigstore/cosign:latest'

3.2 配置 OIDC 认证

OIDC（OpenID Connect）是 Sigstore 无密钥签名流程的核心身份层。通过 OIDC，Cosign 可以自动获取短期有效的身份令牌，无需手动管理长期密钥。本课程以 GitHub Actions 和 Google Cloud Workload Identity Federation 为例进行配置。

3.2.1 理解 OIDC 在 Cosign 中的角色

在无密钥签名模式下，Cosign 使用 OIDC 令牌向 Fulcio（证书颁发机构）证明身份，Fulcio 签发短期证书后，Cosign 使用该证书对镜像进行签名。整个过程无需生成或存储私钥。

3.2.2 配置 GitHub Actions OIDC

在 GitHub Actions 工作流中启用 OIDC 认证，需要为工作流分配 id-: write 权限，并配置信任关系。

# .github/workflows/sign-image.yml
name: Sign Container Image with Cosign
on:
  push:
    branches: [ main ]

permissions:
  id-: write   # 允许工作流请求 OIDC 令牌
  contents: read

jobs:
  sign:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Install Cosign
        run: |
          wget "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

      - name: Sign the image
        env:
          IMAGE: ghcr.io/${{ github.repository }}:latest
        run: |
          cosign sign --yes $IMAGE

3.2.3 配置 Google Cloud Workload Identity Federation

对于 GCP 环境，需要创建 Workload Identity Pool 和 Provider，并将 GitHub 仓库或 GCP 服务账号映射为 OIDC 主体。

# 创建 Workload Identity Pool
gcloud iam workload-identity-pools create "cosign-pool" \
  --location="global" \
  --display-name="Cosign OIDC Pool"

# 创建 OIDC Provider
gcloud iam workload-identity-pools providers create-oidc "github-provider" \
  --location="global" \
  --workload-identity-pool="cosign-pool" \
  --issuer-uri="https://.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.repository=assertion.repository"

# 绑定服务账号
gcloud iam service-accounts add-iam-policy-binding "cosign-sa@PROJECT.iam.gserviceaccount.com" \
  --role="roles/iam.workloadIdentityUser" \
  --member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/cosign-pool/attribute.repository/your-org/your-repo"

3.3 初始化密钥对

虽然 Cosign 支持无密钥签名，但在某些场景下（如离线环境、合规要求、长期密钥管理），仍然需要生成并管理密钥对。本课程同时覆盖本地密钥生成与云 KMS 集成两种模式。

3.3.1 本地密钥对生成

使用 Cosign 内置的 generate-key-pair 命令生成加密密钥对。私钥默认使用密码保护，公钥以 cosign.pub 文件形式输出。

# 生成密钥对（交互式输入密码）
cosign generate-key-pair

# 非交互式生成（通过环境变量传递密码）
export COSIGN_PASSWORD="your-strong-password"
cosign generate-key-pair

# 查看生成的文件
ls -la ~/.cosign/
# 输出示例：
# -rw-------  1 user user  528 Mar 15 10:00 cosign.key
# -rw-r--r--  1 user user  178 Mar 15 10:00 cosign.pub

3.3.2 集成密钥管理服务（KMS）

对于生产环境，推荐将私钥托管在云 KMS 中，避免本地密钥泄露风险。Cosign 原生支持 AWS KMS、GCP Cloud KMS、Azure Key Vault 以及 HashiCorp Vault。

以下以 GCP Cloud KMS 为例，展示密钥创建与 Cosign 集成步骤：

# 1. 创建密钥环和密钥
gcloud kms keyrings create "cosign-keyring" --location "global"
gcloud kms keys create "cosign-signing-key" \
  --location "global" \
  --keyring "cosign-keyring" \
  --purpose "asymmetric-signing" \
  --default-algorithm "ec-sign-p256-sha256"

# 2. 授予 Cosign 访问权限
gcloud kms keys add-iam-policy-binding "cosign-signing-key" \
  --location "global" \
  --keyring "cosign-keyring" \
  --member "serviceAccount:cosign-sa@PROJECT.iam.gserviceaccount.com" \
  --role "roles/cloudkms.signerVerifier"

# 3. 使用 KMS 密钥进行签名
cosign sign --key "gcpkms://projects/PROJECT/locations/global/keyRings/cosign-keyring/cryptoKeys/cosign-signing-key/versions/1" \
  --yes ghcr.io/your-org/your-image:latest

# 4. 使用 KMS 密钥进行验证
cosign verify --key "gcpkms://projects/PROJECT/locations/global/keyRings/cosign-keyring/cryptoKeys/cosign-signing-key/versions/1" \
  ghcr.io/your-org/your-image:latest

3.4 环境准备全景图

下图展示了从工具安装到密钥初始化的完整流程，以及各组件之间的依赖关系：