返回更新列表
新发布Aug 6, 2026

cosign v3.1.3

容器和二进制的代码签名与透明度

分享

Cosign logo

cosign

使用 Sigstore 对 OCI 容器(及其他制品)进行签名!

Go Report Card e2e-tests CII Best Practices OpenSSF Scorecard

Cosign 旨在让签名成为隐形的基础设施。

Cosign 支持:

  • 使用 Sigstore 公益 Fulcio 证书颁发机构和 Rekor 透明日志进行“无密钥签名”(默认)
  • 硬件和 KMS 签名
  • 使用 cosign 生成的加密私钥/公钥对进行签名
  • 在 OCI 注册表中进行容器签名、验证和存储。
  • 自带 PKI

信息

Cosign 是作为 sigstore 项目的一部分开发的。 我们还使用一个 slack 频道! 点击此处获取邀请链接。

安装

有关 Homebrew、Arch、Nix、GitHub Action 和 Kubernetes 的安装,请参阅安装文档。

有关 Linux、macOS 和 Windows 的二进制文件,请参阅 GitHub 发布资源。

🚨 如果你正在从我们的 GCS 存储桶下载 cosign 的发布版本——请查看有关 2023 年 7 月 31 日弃用通知的更多信息 🚨

开发者安装

如果你有 Go 1.22+,你可以设置一个开发环境:

$ git clone https://github.com/sigstore/cosign
$ cd cosign
$ go install ./cmd/cosign
$ $(go env GOPATH)/bin/cosign

贡献

如果您有兴趣为 cosign 做出贡献,请阅读贡献文档。

Cosign 未来的开发将聚焦于下一个主要版本,该版本将基于 sigstore-go。维护者将专注于 sigstore-go 内的功能开发。欢迎对 sigstore-go 做出贡献,尤其是围绕自带密钥和签名方面。 请查看问题跟踪器以寻找适合新手的问题。

Cosign 2.x 是一个稳定版本,将继续定期接收功能更新和错误修复。范围较小、规模较小的 PR 最有可能被快速审查。

显著修改或破坏 API 的 PR 将不被接受。规模较大但未引入破坏性变更的 PR 可能会被接受,但其优先级将低于 sigstore-go 中的 PR。

Dockerfile

以下是如何通过 ghcr.io/sigstore/cosign/cosign 镜像在 Dockerfile 中安装和使用 cosign:

FROM ghcr.io/sigstore/cosign/cosign:v2.4.1 as cosign-bin

# Source: https://github.com/chainguard-images/images/tree/main/images/static
FROM cgr.dev/chainguard/static:latest
COPY --from=cosign-bin /ko-app/cosign /usr/local/bin/cosign
ENTRYPOINT [ "cosign" ]

快速开始

本节展示如何:

  • 使用默认的基于身份的“无密钥签名”方法对容器镜像进行签名(更多信息请参阅文档)
  • 验证容器镜像
  • 在 Sigstore Cosign 快速入门中探索更广泛的无密钥 blob 签名/验证流程

对容器进行签名并将签名存储到注册表中

请注意,你应始终基于镜像的摘要(@sha256:...)而非标签(:latest)进行签名,否则你可能会签署并非你本意的内容!

 cosign sign $IMAGE

Generating ephemeral keys...
Retrieving signed certificate...

	Note that there may be personally identifiable information associated with this signed artifact.
	This may include the email address associated with the account with which you authenticate.
	This information will be used for signing this artifact and will be stored in public transparency logs and cannot be removed later.

By typing 'y', you attest that you grant (or have permission to grant) and agree to have this information stored permanently in transparency logs.
Are you sure you would like to continue? [y/N] y
Your browser will now be opened to:
https://oauth2.sigstore.dev/auth/auth?access_type=online&client_id=sigstore&code_challenge=OrXitVKUZm2lEWHVt1oQWR4HZvn0rSlKhLcltglYxCY&code_challenge_method=S256&nonce=2KvOWeTFxYfxyzHtssvlIXmY6Jk&redirect_uri=http%3A%2F%2Flocalhost%3A57102%2Fauth%2Fcallback&response_type=code&scope=openid+email&state=2KvOWfbQJ1caqScgjwibzK2qJmb
Successfully verified SCT...
tlog entry created with index: 12086900
Pushing signature to: $IMAGE

Cosign 会提示你通过 OIDC 进行身份验证,你需要使用自己的电子邮件地址登录。 在底层,cosign 会向 Fulcio 证书颁发机构申请代码签名证书。 证书的主题将与您登录时使用的电子邮件地址相匹配。 随后,Cosign 会将签名和证书存储到 Rekor 透明日志中,并将签名与你要签名的镜像一起上传到 OCI 注册表。

验证容器

要验证镜像,你需要通过 --certificate-identity 和 --certificate-oidc-issuer 标志传入预期的证书主题和证书颁发者:

cosign verify $IMAGE --certificate-identity=$IDENTITY --certificate-oidc-issuer=$OIDC_ISSUER

你也可以为证书身份和颁发者标志传入正则表达式,即 --certificate-identity-regexp 和 --certificate-oidc-issuer-regexp。

使用公钥验证容器

如果找到至少一个与公钥匹配的镜像 cosign 格式签名,此命令返回 0。 有关其他签名格式的信息和注意事项,请参阅下面的详细用法。

任何有效的载荷都会以 json 格式打印到 stdout。 请注意,这些已签名载荷包含容器镜像的摘要,这正是我们能够确信这些“分离”签名覆盖了正确镜像的方式。

$ cosign verify --key cosign.pub $IMAGE_URI:1h
The following checks were performed on these signatures:
  - The cosign claims were validated
  - The signatures were verified against the specified public key
{"Critical":{"Identity":{"docker-reference":""},"Image":{"Docker-manifest-digest":"sha256:87ef60f558bad79beea6425a3b28989f01dd417164150ab3baab98dcbf04def8"},"Type":"cosign container image signature"},"Optional":null}

在隔离环境中验证容器

注意: 大多数验证工作流需要定期从 TUF 仓库请求服务密钥。 要使用公共实例对签名进行隔离验证,你需要从生产 TUF 仓库获取 受信任根 文件。该文件的内容会随时变更,恕不另行通知。由于不使用 TUF,你需要 自行构建机制来保持该文件的隔离副本处于最新状态。

Cosign 可以通过验证 Sigstore bundle 来完成完全离线验证,cosign sign 会将该 bundle 附加到注册表中的镜像上。 该 bundle 包含签名过程中生成的验证材料,例如证书、带有包含证明的透明度日志条目,以及任何 RFC 3161 时间戳。 借助这些材料以及受信任根的本地副本,验证无需网络访问。

要在隔离环境中验证镜像,镜像和签名必须可在本地文件系统上获取。

可以使用 cosign save 将镜像保存到本地(注意,此步骤必须在有网络连接的情况下完成):

cosign initialize # This will pull in the latest TUF root
cosign save $IMAGE_NAME --dir ./path/to/dir

现在,在隔离网络环境中,可以验证这个本地镜像:

# --trusted-root points to the default location of the trusted root
cosign verify \
  --certificate-identity $CERT_IDENTITY \
  --certificate-oidc-issuer $CERT_OIDC_ISSUER \
  --trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json \
  --local-image ./path/to/dir

你需要传入 $CERT_IDENTITY 和 $CERT_OIDC_ISSUER 的预期值,才能正确验证此镜像。 如果你使用密钥对进行签名,只要本地存在公钥材料,同样的命令即可生效:

cosign verify --key cosign.pub --trusted-root ~/.sigstore/root/tuf-repo-cdn.sigstore.dev/targets/trusted_root.json --local-image ./path/to/dir

基于身份的数据块签名与验证

使用无密钥数据块签名(不带 --key 的 cosign sign-blob),并针对预期的签名者身份进行验证:

$ cosign sign-blob artifact --bundle artifact.sigstore.json --yes
$ cosign verify-blob artifact \
  --bundle artifact.sigstore.json \
  --certificate-identity "https://github.com/ORG/REPO/.github/workflows/release.yml@refs/heads/main" \
  --certificate-oidc-issuer "https://token.actions.githubusercontent.com"

故障排除

如果您在使用 Cosign 时遇到问题,请首先确认您使用的是较新的版本:Cosign 项目积极支持最新版本以及 v2 系列中的上一个版本。

常见问题及解决方法

  1. 验证失败并提示 failed to verify timestamps: threshold not met for verified log entry integrated timestamps: 0 < 1:您可能正在验证一个需要 RFC3161 时间戳支持的签名
    • 升级到最新的 Cosign,或
    • 使用 Cosign 2.6.x 时,使用 --use-signed-timestamps
  2. 验证失败并提示 no signatures found:您可能正在验证一个需要 Rekor v2 透明日志支持的镜像签名
    • 升级到最新的 Cosign
  3. 签名失败并出现 HTTP 错误:使用 Cosign 签名依赖于多个 Sigstore 服务。如果其中任何服务发生故障,失败后重试可能是一种有用的变通方法——同时也欢迎针对具体故障提交 issue

我的问题属于其他情况

请提交一个 issue,或在 slack 频道 中提问。

处理其他工件

OCI 注册表不仅可用于存储容器镜像! Cosign 还包含一些实用工具,可使用 OCI 协议发布通用工件,包括二进制文件、脚本和配置文件。

本节展示如何利用这些工具构建一个易于使用、向后兼容的工件分发系统,并与 Sigstore 的其余部分良好集成。

更多信息请参阅文档。

Blob

您可以使用 cosign upload blob 发布工件:

$ echo "my first artifact" > artifact
$ BLOB_SUM=$(shasum -a 256 artifact | cut -d' ' -f 1) && echo "$BLOB_SUM"
c69d72c98b55258f9026f984e4656f0e9fd3ef024ea3fac1d7e5c7e6249f1626
$ BLOB_NAME=my-artifact-$(uuidgen | head -c 8 | tr 'A-Z' 'a-z')
$ BLOB_URI=ttl.sh/$BLOB_NAME:1h

分类