Package: sigstore
sigstore-pythonsigstoreis a Python tool for generating and verifying Sigstore signatures.
You can use it to sign and verify Python package distributions, or anything
else!IndexFeaturesInstallationGitHub ActionsUsageSigningVerifyingGeneric identitiesSignatures from GitHub ActionsExample usesSigning with ambient credentialsSigning with an email identitySigning with an explicit identity tokenVerifying against a signature and certificateVerifying signatures from GitHub ActionsLicensingCommunityContributingCode of ConductSecuritySLSA ProvenanceFeaturesSupport for keyless signature generation and verification withSigstoreSupport for signing with"ambient" OpenID Connect identitiesA comprehensiveCLIand correspondingimportable Python APIInstallationsigstorerequires Python 3.8 or newer, and can be installed directly viapip:python -m pip install sigstoreOptionally, to installsigstoreand all its dependencies withhash-checking modeenabled, run the following:python -m pip install -r https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txtThis installs the requirements file locatedhere, which is kept up-to-date.GitHub Actionssigstore-pythonhasan official GitHub Action!You can install it from theGitHub Marketplace, or
add it to your CI manually:jobs:sigstore-python:steps:-uses:sigstore/gh-action-sigstore-python@v0.2.0with:inputs:foo.txtSee theaction documentationfor more details and usage examples.UsageFor Python API usage, see ourdocumentation.You can runsigstoreas a standalone program, or viapython -m:sigstore --helppython -m sigstore --helpTop-level:usage: sigstore [-h] [-v] [-V] [--staging] [--rekor-url URL]
                [--rekor-root-pubkey FILE]
                COMMAND ...

a tool for signing and verifying Python package distributions

positional arguments:
  COMMAND               the operation to perform
    sign                sign one or more inputs
    verify              verify one or more inputs
    get-identity-token  retrieve and return a Sigstore-compatible OpenID
                        Connect token

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         run with additional debug logging; supply multiple
                        times to increase verbosity
  -V, --version         show program's version number and exit

Sigstore instance options:
  --staging             Use sigstore's staging instances, instead of the
                        default production instances (default: False)
  --rekor-url URL       The Rekor instance to use (conflicts with --staging)
                        (default: https://rekor.sigstore.dev)
  --rekor-root-pubkey FILE
                        A PEM-encoded root public key for Rekor itself
                        (conflicts with --staging) (default: None)Signingusage: 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] [--staging]
                     [--rekor-url URL] [--rekor-root-pubkey FILE]
                     [--fulcio-url URL] [--ctfe FILE]
                     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

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)
                        (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)

Sigstore instance options:
  --staging             Use sigstore's staging instances, instead of the
                        default production instances. This option will be
                        deprecated in favor of the global `--staging` option
                        in a future release. (default: False)
  --rekor-url URL       The Rekor instance to use (conflicts with --staging).
                        This option will be deprecated in favor of the global
                        `--rekor-url` option in a future release. (default:
                        None)
  --rekor-root-pubkey FILE
                        A PEM-encoded root public key for Rekor itself
                        (conflicts with --staging). This option will be
                        deprecated in favor of the global `--rekor-root-
                        pubkey` option in a future release. (default: None)
  --fulcio-url URL      The Fulcio instance to use (conflicts with --staging)
                        (default: https://fulcio.sigstore.dev)
  --ctfe FILE           A PEM-encoded public key for the CT log (conflicts
                        with --staging) (default: None)VerifyingGeneric identitiesThis is the most common verification done withsigstore, and therefore
the one you probably want: you can use it to verify that a signature was
produced by a particular identity (likehamilcar@example.com), as attested
to by a particular OIDC provider (likehttps://github.com/login/oauth).usage: sigstore verify identity [-h] [-v] [--certificate FILE]
                                [--signature FILE] [--bundle FILE]
                                --cert-identity IDENTITY [--offline]
                                --cert-oidc-issuer URL [--staging]
                                [--rekor-url URL] [--rekor-root-pubkey FILE]
                                [--certificate-chain FILE]
                                FILE [FILE ...]

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

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                  The file to verify

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

Sigstore instance options:
  --staging             Use sigstore's staging instances, instead of the
                        default production instances. This option will be
                        deprecated in favor of the global `--staging` option
                        in a future release. (default: False)
  --rekor-url URL       The Rekor instance to use (conflicts with --staging).
                        This option will be deprecated in favor of the global
                        `--rekor-url` option in a future release. (default:
                        None)
  --rekor-root-pubkey FILE
                        A PEM-encoded root public key for Rekor itself
                        (conflicts with --staging). This option will be
                        deprecated in favor of the global `--rekor-root-
                        pubkey` option in a future release. (default: None)
  --certificate-chain FILE
                        Path to a list of CA certificates in PEM format which
                        will be needed when building the certificate chain for
                        the Fulcio signing certificate (default: None)Signatures from GitHub ActionsIf your signatures are coming from GitHub Actions (e.g., a workflow
that uses itsambient credentials),
then you can use thesigstore verify githubsubcommand to verify
claims more precisely thansigstore verify identityallows:usage: sigstore verify github [-h] [-v] [--certificate FILE]
                              [--signature FILE] [--bundle FILE]
                              --cert-identity IDENTITY [--offline]
                              [--trigger EVENT] [--sha SHA] [--name NAME]
                              [--repository REPO] [--ref REF] [--staging]
                              [--rekor-url URL] [--rekor-root-pubkey FILE]
                              [--certificate-chain FILE]
                              FILE [FILE ...]

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

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                  The file to verify

Verification options:
  --cert-identity IDENTITY
                        The identity to check for in the certificate's Subject
                        Alternative Name (default: None)
  --offline             Perform offline verification; requires a Sigstore
                        bundle (default: False)
  --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)

Sigstore instance options:
  --staging             Use sigstore's staging instances, instead of the
                        default production instances. This option will be
                        deprecated in favor of the global `--staging` option
                        in a future release. (default: False)
  --rekor-url URL       The Rekor instance to use (conflicts with --staging).
                        This option will be deprecated in favor of the global
                        `--rekor-url` option in a future release. (default:
                        None)
  --rekor-root-pubkey FILE
                        A PEM-encoded root public key for Rekor itself
                        (conflicts with --staging). This option will be
                        deprecated in favor of the global `--rekor-root-
                        pubkey` option in a future release. (default: None)
  --certificate-chain FILE
                        Path to a list of CA certificates in PEM format which
                        will be needed when building the certificate chain for
                        the Fulcio signing certificate (default: None)Example usessigstoresupports a wide variety of workflows and usages. Some common ones are
provided below.Signing with ambient credentialsFor environments that support OpenID Connect, nativelysigstoresupports ambient credential
detection. This includes many popular CI platforms and cloud providers. See the full list of
supported environmentshere.Sign a single file (foo.txt) using an ambient OpenID Connect credential,
saving the bundle tofoo.txt.sigstore:$python-msigstoresignfoo.txtSigning with an email identitysigstorecan use an OAuth2 + OpenID flow to establish an email identity,
allowing you to request signing certificates that attest to control over
that email.Sign a single file (foo.txt) using the OAuth2 flow, saving the
bundle tofoo.txt.sigstore:$python-msigstoresignfoo.txtBy default,sigstoreattempts to doambient credential detection, which may preempt
the OAuth2 flow. To force the OAuth2 flow, you can explicitly disable ambient detection:$python-msigstoresign--oidc-disable-ambient-providersfoo.txtSigning with an explicit identity tokenIf you can't use an ambient credential or the OAuth2 flow, you can pass a pre-created
identity token directly intosigstore sign:$python-msigstoresign--identity-tokenYOUR-LONG-JWT-HEREfoo.txtNote that passing a custom identity token does not circumvent Fulcio's requirements,
namely the Fulcio's supported identity providers and the claims expected within the token.Verifying against a signature and certificateBy default,sigstore verify identitywill attempt to find a<filename>.sigstorein the
same directory as the file being verified:#looksforfoo.txt.sigstore$python-msigstoreverifyidentityfoo.txt\--cert-identity'hamilcar@example.com'\--cert-oidc-issuer'https://github.com/login/oauth'Multiple files can be verified at once:#looksfor{foo,bar}.txt.sigstore$python-msigstoreverifyidentityfoo.txtbar.txt\--cert-identity'hamilcar@example.com'\--cert-oidc-issuer'https://github.com/login/oauth'Verifying signatures from GitHub Actionssigstore verify githubcan be used to verify claims specific to signatures coming from GitHub
Actions.sigstore-pythonsigns releases via GitHub Actions, so the examples below are working
examples of how you can verify a givensigstore-pythonrelease.As withsigstore verify identity, the--cert-identityflag is required. However, since we know
that the signature was generated with an GitHub Actions ambient credential, the OIDC issuer is
inferred.$python-msigstoreverifygithubsigstore-0.10.0-py3-none-any.whl\--bundlesigstore-0.10.0-py3-none-any.whl.bundle\--cert-identityhttps://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0Additionally, GitHub Actions specific claims can be verified like so:$python-msigstoreverifygithubsigstore-0.10.0-py3-none-any.whl\--bundlesigstore-0.10.0-py3-none-any.whl.bundle\--cert-identityhttps://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0\--triggerrelease\--sha66581529803929c3ccc45334632ccd90f06e0de4\--nameRelease\--repositorysigstore/sigstore-python\--refrefs/tags/v0.10.0Licensingsigstoreis licensed under the Apache 2.0 License.Communitysigstore-pythonis developed as part of theSigstoreproject.We also use aSlack channel!
Clickherefor the invite link.ContributingSeethe contributing docsfor details.Code of ConductEveryone interacting with this project is expected to follow thesigstore Code of Conduct.SecurityShould you discover any security issues, please refer to sigstore'ssecurity
process.SLSA ProvenanceThis project emits a SLSA provenance on its release! This enables you to verify the integrity
of the downloaded artifacts and ensured that the binary's code really comes from this source code.To do so, please follow the instructionshere.