sigstore-python

⚠️ This project is not ready for general-purpose use! ⚠️

sigstore is a tool for signing and verifying Python package distributions.

Features

• Support for signing Python package distributions using an OpenID Connect identity
• Support for publishing signatures to a Rekor instance
• Support for verifying signatures on Python package distributions

Installation

sigstore requires Python 3.7 or newer, and can be installed directly via pip:

python -m pip install sigstore

Optionally, to install sigstore and all its dependencies with hash-checking mode enabled, run the following:

python -m pip install -r <(curl -s https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txt)

This installs the requirements file located here, which is kept up-to-date.

Usage

You can run sigstore as a standalone program, or via python -m:

sigstore --help
python -m sigstore --help

Top-level:

usage: sigstore [-h] [-V] {sign,verify} ...

a tool for signing and verifying Python package distributions

positional arguments:
  {sign,verify}

options:
  -h, --help     show this help message and exit
  -V, --version  show program's version number and exit

Signing:

usage: sigstore sign [-h] [--identity-token TOKEN] [--oidc-client-id ID]
                     [--oidc-client-secret SECRET]
                     [--oidc-disable-ambient-providers] [--output]
                     [--output-signature FILE] [--output-certificate FILE]
                     [--overwrite] [--fulcio-url URL] [--rekor-url URL]
                     [--ctfe FILE] [--rekor-root-pubkey FILE]
                     [--oidc-issuer URL] [--staging]
                     FILE [FILE ...]

positional arguments:
  FILE                  The file to sign

options:
  -h, --help            show this help message and exit

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)

Output options:
  --output              Write signature and certificate results to default
                        files ({input}.sig and {input}.crt) (default: False)
  --output-signature FILE
                        Write a single signature to the given file; conflicts
                        with --output and does not work with multiple input
                        files (default: None)
  --output-certificate FILE
                        Write a single certificate to the given file;
                        conflicts with --output and does not work with
                        multiple input files (default: None)
  --overwrite           Overwrite preexisting signature and certificate
                        outputs, if present (default: False)

Sigstore instance options:
  --fulcio-url URL      The Fulcio instance to use (conflicts with --staging)
                        (default: https://fulcio.sigstore.dev)
  --rekor-url URL       The Rekor instance to use (conflicts with --staging)
                        (default: https://rekor.sigstore.dev)
  --ctfe FILE           A PEM-encoded public key for the CT log (conflicts
                        with --staging) (default: ctfe.pub (embedded))
  --rekor-root-pubkey FILE
                        A PEM-encoded root public key for Rekor itself
                        (conflicts with --staging) (default: rekor.pub
                        (embedded))
  --oidc-issuer URL     The OpenID Connect issuer to use (conflicts with
                        --staging) (default: https://oauth2.sigstore.dev/auth)
  --staging             Use sigstore's staging instances, instead of the
                        default production instances (default: False)

Verifying:

usage: sigstore verify [-h] --certificate FILE --signature FILE
                       [--cert-email EMAIL] [--cert-oidc-issuer URL]
                       [--rekor-url URL] [--staging]
                       FILE

positional arguments:
  FILE                  The file to verify

options:
  -h, --help            show this help message and exit

Verification inputs:
  --certificate FILE, --cert FILE
                        The PEM-encoded certificate to verify against
                        (default: None)
  --signature FILE      The signature to verify against (default: None)

Extended verification options:
  --cert-email EMAIL    The email address 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)

Sigstore instance options:
  --rekor-url URL       The Rekor instance to use (conflicts with --staging)
                        (default: https://rekor.sigstore.dev)
  --staging             Use sigstore's staging instances, instead of the
                        default production instances (default: False)

Ambient credential detection

For environments that support OIDC natively, sigstore supports automatic ambient credential detection:

• GitHub:
  • Actions: requires setting the id-token permission, see https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect. An example is here.
• Google Cloud:
  • Compute Engine: automatic
  • Cloud Build: requires setting GOOGLE_SERVICE_ACCOUNT_NAME to an appropriately configured service account name, see https://cloud.google.com/iam/docs/creating-short-lived-service-account-credentials#sa-credentials-direct. An example is here
• GitLab: planned, see sigstore#31
• CircleCI: planned, see sigstore#31

Licensing

sigstore is licensed under the Apache 2.0 License.

Contributing

See the contributing docs for details.

Code of Conduct

Everyone interacting with this project is expected to follow the sigstore Code of Conduct.

Security

Should you discover any security issues, please refer to sigstore's security process.

Info

sigstore-python is developed as part of the sigstore project.

We also use a slack channel! Click here for the invite link.