implementing-code-signing-for-artifacts

アーティファクトのコード署名を実装する

使用する場面

• サプライチェーンの改ざんを防ぐために、アーティファクトの整合性検証を確立する場合
• ビルドアーティファクトが真正で、変更されていないことを示す暗号学的な証明がコンプライアンスで必要な場合
• 発行者の身元を検証する必要がある顧客にソフトウェアを配布する場合
• 署名されていないアーティファクトを拒否するゼロトラストのデプロイパイプラインを実装する場合
• 来歴と整合性に関する SLSA Level 2+ の要件を満たす場合

使用しないでください（署名は整合性を提供しますが、機密性は提供しないため）アーティファクトの暗号化、コンテナーイメージの署名（cosign を使用してください）、ソースコードの認証（コミット署名を使用してください）。

前提条件

• 従来型の署名には GPG 鍵ペア、鍵レス署名には Sigstore アカウント
• パブリック配布用の認証局が発行したコード署名証明書
• 署名鍵または ID プロバイダーにアクセスできる CI/CD パイプライン
• デプロイパイプライン内の検証インフラストラクチャ

ワークフロー

ステップ 1：署名鍵を生成して管理する

# Generate GPG key for artifact signing
gpg --full-generate-key --batch <<EOF
Key-Type: eddsa
Key-Curve: ed25519
Subkey-Type: eddsa
Subkey-Curve: ed25519
Name-Real: CI Build System
Name-Email: [email protected]
Expire-Date: 1y
%no-protection
EOF

# Export public key for distribution
gpg --armor --export [email protected] > signing-key.pub

# Export private key for CI/CD (store in secrets manager)
gpg --armor --export-secret-keys [email protected] > signing-key.priv

ステップ 2：CI/CD でビルドアーティファクトに署名する

# .github/workflows/build-sign.yml
name: Build and Sign

on:
  push:
    tags: ['v*']

jobs:
  build-sign:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      id-token: write  # For Sigstore keyless signing
    steps:
      - uses: actions/checkout@v4

      - name: Build artifacts
        run: |
          make build
          sha256sum dist/* > dist/checksums.sha256

      - name: Import GPG Key
        run: |
          echo "${{ secrets.GPG_PRIVATE_KEY }}" | gpg --batch --import
          gpg --list-secret-keys

      - name: Sign artifacts
        run: |
          for file in dist/*; do
            gpg --detach-sign --armor --local-user [email protected] "$file"
          done

      - name: Install cosign for keyless signing
        uses: sigstore/cosign-installer@v3

      - name: Keyless sign with Sigstore
        run: |
          for file in dist/*.tar.gz; do
            cosign sign-blob "$file" \
              --output-signature "${file}.sig" \
              --output-certificate "${file}.cert" \
              --yes
          done

      - name: Create Release with signed artifacts
        uses: softprops/action-gh-release@v2
        with:
          files: |
            dist/*
            dist/*.asc
            dist/*.sig
            dist/*.cert

ステップ 3：デプロイパイプラインで署名を検証する

# Verify GPG signature
gpg --import signing-key.pub
gpg --verify artifact.tar.gz.asc artifact.tar.gz

# Verify Sigstore keyless signature
cosign verify-blob artifact.tar.gz \
  --signature artifact.tar.gz.sig \
  --certificate artifact.tar.gz.cert \
  --certificate-identity [email protected] \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

# Verify checksums
sha256sum --check checksums.sha256

ステップ 4：来歴情報を付けて npm パッケージに署名する

{
  "scripts": {
    "prepublishOnly": "npm run build && npm run test"
  },
  "publishConfig": {
    "provenance": true
  }
}

# Publish npm package with provenance attestation
npm publish --provenance

主な概念

用語	定義
コード署名	発行者の身元とアーティファクトの整合性を検証するために、ソフトウェアアーティファクトに署名する暗号学的なプロセス
分離署名	アーティファクトとは別のファイルに保存され、独立して配布できる署名
鍵レス署名	長期間有効な鍵の代わりに、OIDC ID に紐づく短期間有効な証明書を使用する Sigstore の方式
来歴情報	アーティファクトがどのように、どこで、誰によってビルドされたかを説明するメタデータ
透明性ログ	公開監査のためにすべての署名イベントを記録する追記専用ログ（Rekor）
信頼チェーン	署名者の身元への信頼を確立する、ルート CA から署名証明書までの階層的なチェーン
SLSA	ソフトウェアアーティファクトのサプライチェーンレベル — サプライチェーンセキュリティのレベルを定義するフレームワーク

ツールとシステム

• GPG/PGP：アーティファクトの署名と検証に使う従来型の非対称暗号ツール
• Sigstore (cosign)：OIDC ID と透明性ログを使用する最新の鍵レス署名インフラストラクチャ
• Rekor：すべての署名イベントを改変不可能な形で記録する Sigstore の透明性ログ
• Fulcio：OIDC ID に紐づく短期間有効な証明書を発行する Sigstore の認証局
• notation：OCI レジストリ向けの Microsoft のアーティファクト署名ツール（Project Notary v2）

よくあるシナリオ

シナリオ：署名付きリリースパイプラインの確立

背景：オープンソースプロジェクトで、ユーザーが真正性を検証し、改ざんを検出できるよう、リリースアーティファクトに署名する必要があります。

アプローチ：

1. GitHub Actions で Sigstore の鍵レス署名を使用します（鍵管理の負担がありません）
2. OIDC ID を使用して、すべてのリリースバイナリに cosign sign-blob で署名します
3. 一括検証用のチェックサムファイルを生成して署名します
4. 署名、証明書、チェックサムをリリースアーティファクトと一緒にアップロードします
5. プロジェクトの README に検証手順を記載します
6. Homebrew のフォーミュラまたは apt リポジトリに検証ステップを追加します

注意点：GPG 鍵が侵害された場合、すべてのアーティファクトの失効と再署名が必要です。Sigstore の鍵レス署名では一時的な鍵を使用するため、この問題を回避できます。CI システムが侵害された場合、CI/CD のシークレットに保存された長期間有効な署名鍵はサプライチェーンのリスクになります。

出力形式

Artifact Signing Report
========================
Pipeline: Build and Sign v2.3.0
Date: 2026-02-23
Signing Method: Sigstore Keyless + GPG

SIGNED ARTIFACTS:
  app-v2.3.0-linux-amd64.tar.gz
    GPG:      PASS ([email protected], EdDSA/Ed25519)
    Sigstore: PASS (Rekor entry: 24658135, Fulcio cert issued)
    SHA256:   a1b2c3d4...

  app-v2.3.0-darwin-arm64.tar.gz
    GPG:      PASS
    Sigstore: PASS (Rekor entry: 24658136)
    SHA256:   e5f6g7h8...

  checksums.sha256
    GPG:      PASS (detached signature)

TRANSPARENCY LOG:
  Entries recorded: 3
  Log index range: 24658135-24658137
  Verification: https://search.sigstore.dev