sigstore-python

sigstore 是一个用于生成和验证 Sigstore 签名的 Python 工具。您可以使用它来签名和验证 Python 软件包分发，或任何其他内容！

索引

• 特性
• 安装
  • GitHub Actions
• 使用方法
  • 签名
  • 验证
    • 通用身份
    • GitHub Actions 中的签名
  • 高级使用
• 示例用途
  • 使用环境凭证进行签名
  • 使用电子邮件身份进行签名
  • 使用显式身份令牌进行签名
  • 对签名和证书进行验证
  • 验证 GitHub Actions 中的签名
• 许可
• 社区
• 贡献
• 行为准则
• 安全
• SLSA 原因

特性

• 支持使用 Sigstore 进行无密钥签名生成和验证
• 支持使用 "环境" OpenID Connect 身份 进行签名
• 全面的 CLI 和相应的 可导入的 Python API

安装

sigstore 需要 Python 3.8 或更高版本，并且可以直接通过 pip 安装

python -m pip install sigstore

可选地，要启用哈希检查模式安装 sigstore 和所有依赖项，请运行以下命令

python -m pip install -r https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txt

这将安装位于 此处 的需求文件，该文件保持最新。

GitHub Actions

sigstore-python 有 官方 GitHub Action！

您可以从 GitHub Marketplace 安装它，或将它手动添加到您的 CI

jobs:
  sigstore-python:
    steps:
      - uses: sigstore/gh-action-sigstore-python@v0.2.0
        with:
          inputs: foo.txt

有关更多详细信息和使用示例，请参阅 操作文档。

使用方法

有关 Python API 使用，请参阅我们的 文档。

您可以将 sigstore 作为独立程序运行，或通过 python -m

sigstore --help
python -m sigstore --help

顶级

usage: sigstore [-h] [-v] [-V] [--staging | --trust-config FILE] COMMAND ...

a tool for signing and verifying Python package distributions

positional arguments:
  COMMAND              the operation to perform
    attest             sign one or more inputs using DSSE
    sign               sign one or more inputs
    verify             verify one or more inputs
    get-identity-token
                       retrieve and return a Sigstore-compatible OpenID
                       Connect token
    plumbing           developer-only plumbing operations

optional arguments:
  -h, --help           show this help message and exit
  -v, --verbose        run with additional debug logging; supply multiple
                       times to increase verbosity (default: 0)
  -V, --version        show program's version number and exit
  --staging            Use sigstore's staging instances, instead of the
                       default production instances (default: False)
  --trust-config FILE  The client trust configuration to use (default: None)

签名

usage: sigstore sign [-h] [-v] [--identity-token TOKEN] [--oidc-client-id ID]
                     [--oidc-client-secret SECRET]
                     [--oidc-disable-ambient-providers] [--oidc-issuer URL]
                     [--oauth-force-oob] [--no-default-files]
                     [--signature FILE] [--certificate FILE] [--bundle FILE]
                     [--output-directory DIR] [--overwrite]
                     FILE [FILE ...]

positional arguments:
  FILE                  The file to sign

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         run with additional debug logging; supply multiple
                        times to increase verbosity (default: 0)

OpenID Connect options:
  --identity-token TOKEN
                        the OIDC identity token to use (default: None)
  --oidc-client-id ID   The custom OpenID Connect client ID to use during
                        OAuth2 (default: sigstore)
  --oidc-client-secret SECRET
                        The custom OpenID Connect client secret to use during
                        OAuth2 (default: None)
  --oidc-disable-ambient-providers
                        Disable ambient OpenID Connect credential detection
                        (e.g. on GitHub Actions) (default: False)
  --oidc-issuer URL     The OpenID Connect issuer to use (conflicts with
                        --staging) (default: https://oauth2.sigstore.dev/auth)
  --oauth-force-oob     Force an out-of-band OAuth flow and do not
                        automatically start the default web browser (default:
                        False)

Output options:
  --no-default-files    Don't emit the default output files
                        ({input}.sigstore.json) (default: False)
  --signature FILE, --output-signature FILE
                        Write a single signature to the given file; does not
                        work with multiple input files (default: None)
  --certificate FILE, --output-certificate FILE
                        Write a single certificate to the given file; does not
                        work with multiple input files (default: None)
  --bundle FILE         Write a single Sigstore bundle to the given file; does
                        not work with multiple input files (default: None)
  --output-directory DIR
                        Write default outputs to the given directory
                        (conflicts with --signature, --certificate, --bundle)
                        (default: None)
  --overwrite           Overwrite preexisting signature and certificate
                        outputs, if present (default: False)

使用 DSSE 封装进行签名

usage: sigstore attest [-h] [-v] --predicate FILE --predicate-type TYPE
                       [--identity-token TOKEN] [--oidc-client-id ID]
                       [--oidc-client-secret SECRET]
                       [--oidc-disable-ambient-providers] [--oidc-issuer URL]
                       [--oauth-force-oob] [--bundle FILE] [--overwrite]
                       FILE [FILE ...]

positional arguments:
  FILE                  The file to sign

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         run with additional debug logging; supply multiple
                        times to increase verbosity (default: 0)

DSSE options:
  --predicate FILE      Path to the predicate file (default: None)
  --predicate-type TYPE
                        Specify a predicate type
                        (https://slsa.dev/provenance/v0.2,
                        https://slsa.dev/provenance/v1) (default: None)

OpenID Connect options:
  --identity-token TOKEN
                        the OIDC identity token to use (default: None)
  --oidc-client-id ID   The custom OpenID Connect client ID to use during
                        OAuth2 (default: sigstore)
  --oidc-client-secret SECRET
                        The custom OpenID Connect client secret to use during
                        OAuth2 (default: None)
  --oidc-disable-ambient-providers
                        Disable ambient OpenID Connect credential detection
                        (e.g. on GitHub Actions) (default: False)
  --oidc-issuer URL     The OpenID Connect issuer to use (conflicts with
                        --staging) (default: https://oauth2.sigstore.dev/auth)
  --oauth-force-oob     Force an out-of-band OAuth flow and do not
                        automatically start the default web browser (default:
                        False)

Output options:
  --bundle FILE         Write a single Sigstore bundle to the given file; does
                        not work with multiple input files (default: None)
  --overwrite           Overwrite preexisting bundle outputs, if present
                        (default: False)

验证

通用身份

这是使用 sigstore 最常见的验证方式，因此您可能希望使用它：您可以使用它来验证签名是否由特定身份（例如 hamilcar@example.com）生成，并由特定 OIDC 提供商（例如 https://github.com/login/oauth）证实。

usage: sigstore verify identity [-h] [-v] [--certificate FILE]
                                [--signature FILE] [--bundle FILE] [--offline]
                                --cert-identity IDENTITY --cert-oidc-issuer
                                URL
                                FILE_OR_DIGEST [FILE_OR_DIGEST ...]

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         run with additional debug logging; supply multiple
                        times to increase verbosity (default: 0)

Verification inputs:
  --certificate FILE, --cert FILE
                        The PEM-encoded certificate to verify against; not
                        used with multiple inputs (default: None)
  --signature FILE      The signature to verify against; not used with
                        multiple inputs (default: None)
  --bundle FILE         The Sigstore bundle to verify with; not used with
                        multiple inputs (default: None)
  FILE_OR_DIGEST        The file path or the digest to verify. The digest
                        should start with the 'sha256:' prefix.

Verification options:
  --offline             Perform offline verification; requires a Sigstore
                        bundle (default: False)
  --cert-identity IDENTITY
                        The identity to check for in the certificate's Subject
                        Alternative Name (default: None)
  --cert-oidc-issuer URL
                        The OIDC issuer URL to check for in the certificate's
                        OIDC issuer extension (default: None)

GitHub Actions 中的签名

如果您的签名来自 GitHub Actions（例如，使用其 环境凭证 的工作流程），则可以使用 sigstore verify github 子命令进行更精确的验证，比 sigstore verify identity 允许的更精确

usage: sigstore verify github [-h] [-v] [--certificate FILE]
                              [--signature FILE] [--bundle FILE] [--offline]
                              [--cert-identity IDENTITY] [--trigger EVENT]
                              [--sha SHA] [--name NAME] [--repository REPO]
                              [--ref REF]
                              FILE_OR_DIGEST [FILE_OR_DIGEST ...]

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         run with additional debug logging; supply multiple
                        times to increase verbosity (default: 0)

Verification inputs:
  --certificate FILE, --cert FILE
                        The PEM-encoded certificate to verify against; not
                        used with multiple inputs (default: None)
  --signature FILE      The signature to verify against; not used with
                        multiple inputs (default: None)
  --bundle FILE         The Sigstore bundle to verify with; not used with
                        multiple inputs (default: None)
  FILE_OR_DIGEST        The file path or the digest to verify. The digest
                        should start with the 'sha256:' prefix.

Verification options:
  --offline             Perform offline verification; requires a Sigstore
                        bundle (default: False)
  --cert-identity IDENTITY
                        The identity to check for in the certificate's Subject
                        Alternative Name (default: None)
  --trigger EVENT       The GitHub Actions event name that triggered the
                        workflow (default: None)
  --sha SHA             The `git` commit SHA that the workflow run was invoked
                        with (default: None)
  --name NAME           The name of the workflow that was triggered (default:
                        None)
  --repository REPO     The repository slug that the workflow was triggered
                        under (default: None)
  --ref REF             The `git` ref that the workflow was invoked with
                        (default: None)

高级使用

配置自定义信任根（“BYO PKI”）

除了默认和“测试”的 Sigstore 实例之外，sigstore 还支持“BYO PKI”设置，其中用户维护自己的 Sigstore 实例服务。

这些通过 --trust-config 标志支持，该标志接受符合 Sigstore protobuf 规范 中 ClientTrustConfig 消息的 JSON 格式文件。该文件配置整个 Sigstore 实例状态，包括用于访问 CA 和工件透明度服务的 URI 以及自身的加密信任根。

要使用自定义客户端配置，请在任何 sigstore 命令前加上 --trust-config

$ sigstore --trust-config custom.trustconfig.json sign foo.txt
$ sigstore --trust-config custom.trustconfig.json verify identity foo.txt ...

示例用途

sigstore 支持各种工作流和用途。以下提供了一些常见示例。

使用环境凭证进行签名

对于支持 OpenID Connect 的环境，sigstore 原生支持环境凭证检测。这包括许多流行的 CI 平台和云提供商。有关支持环境的完整列表，请参阅 此处。

使用环境 OpenID Connect 凭证对单个文件（foo.txt）进行签名，并将捆绑包保存到 foo.txt.sigstore

$ python -m sigstore sign foo.txt

使用电子邮件身份进行签名

sigstore 可以使用 OAuth2 + OpenID 流建立电子邮件身份，允许您请求签名证书，证明您对该电子邮件的控制权。

使用OAuth2流程对单个文件（foo.txt）进行签名，并将签名包保存到foo.txt.sigstore

$ python -m sigstore sign foo.txt

默认情况下，sigstore会尝试进行环境凭据检测，这可能会抢占OAuth2流程。要强制使用OAuth2流程，您可以显式禁用环境检测

$ python -m sigstore sign --oidc-disable-ambient-providers foo.txt

使用显式身份令牌进行签名

如果无法使用环境凭据或OAuth2流程，您可以直接将预先创建的身份令牌传递给sigstore sign

$ python -m sigstore sign --identity-token YOUR-LONG-JWT-HERE foo.txt

请注意，传递自定义身份令牌并不能绕过Fulcio的要求，即Fulcio支持的标识提供者和令牌中预期的声明。

对签名和证书进行验证

默认情况下，sigstore verify identity将尝试在正在验证的文件所在的同一目录中找到<filename>.sigstore

# looks for foo.txt.sigstore
$ python -m sigstore verify identity foo.txt \
    --cert-identity 'hamilcar@example.com' \
    --cert-oidc-issuer 'https://github.com/login/oauth'

可以一次性验证多个文件

# looks for {foo,bar}.txt.sigstore
$ python -m sigstore verify identity foo.txt bar.txt \
    --cert-identity 'hamilcar@example.com' \
    --cert-oidc-issuer 'https://github.com/login/oauth'

验证摘要而不是文件

sigstore-python支持直接验证摘要，而不需要将工件本身提供。摘要应以前缀sha256:开始

$ python -m sigstore verify identity sha256:ce8ab2822671752e201ea1e19e8c85e73d497e1c315bfd9c25f380b7625d1691 \
    --cert-identity 'hamilcar@example.com' \
    --cert-oidc-issuer 'https://github.com/login/oauth'
    --bundle 'foo.txt.sigstore.json'

验证 GitHub Actions 中的签名

sigstore verify github可用于验证来自GitHub Actions的签名特定的声明。sigstore-python通过GitHub Actions进行签名，因此下面的示例是验证给定sigstore-python发布的实际示例。

当使用sigstore verify github时，您必须传递--cert-identity或--repository，或者两者都传递。与sigstore verify identity不同，--cert-oidc-issuer不是必需的（因为它被推断为GitHub Actions）。

使用--cert-identity进行验证

$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \
    --bundle sigstore-0.10.0-py3-none-any.whl.bundle \
    --cert-identity https://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0

使用--repository进行验证

$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \
    --bundle sigstore-0.10.0-py3-none-any.whl.bundle \
    --repository sigstore/sigstore-python

可以像这样验证额外的GitHub Actions特定声明

$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \
    --bundle sigstore-0.10.0-py3-none-any.whl.bundle \
    --cert-identity https://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0 \
    --trigger release \
    --sha 66581529803929c3ccc45334632ccd90f06e0de4 \
    --name Release \
    --repository sigstore/sigstore-python \
    --ref refs/tags/v0.10.0

许可

sigstore采用Apache 2.0许可证。

社区

sigstore-python是作为Sigstore项目的一部分开发的。

我们还使用Slack频道！点击这里获取邀请链接。

贡献

有关详细信息，请参阅贡献文档。

行为准则

与该项目互动的每个人都应遵循sigstore行为准则。

安全

如果您发现任何安全问题，请参阅sigstore的安全流程。

SLSA 原因

此项目在其发布时发出SLSA起源证明！这使您能够验证下载的工件的真实性，并确保二进制代码确实来自此源代码。

要这样做，请按照此处的说明操作。