diff --git a/content/en/language_clients/language_client_overview.md b/content/en/language_clients/language_client_overview.md index 00268a0a..7bebe8db 100644 --- a/content/en/language_clients/language_client_overview.md +++ b/content/en/language_clients/language_client_overview.md @@ -9,7 +9,7 @@ Sigstore uses [cosign](../../cosign/signing/overview) to sign and verify package Sigstore has clients for the following language ecosystems: -- [Python](https://github.com/sigstore/sigstore-python#sigstore-python) +- [Python](./python/python_client_overview) - [Rust](https://github.com/sigstore/sigstore-rs#features) - [Ruby](https://github.com/sigstore/sigstore-ruby#sigstore) - [JavaScript](https://github.com/sigstore/sigstore-js#sigstore-js---) diff --git a/content/en/language_clients/python/_index.html b/content/en/language_clients/python/_index.html new file mode 100644 index 00000000..85098994 --- /dev/null +++ b/content/en/language_clients/python/_index.html @@ -0,0 +1,11 @@ +--- +type: docs +title: "Python" +description: "sigstore-python" +lead: "Python Language Client" +date: 2024-10-06T08:49:15+00:00 +lastmod: 2024-10-06T08:49:15+00:00 +draft: false +images: [] +weight: 15 +--- diff --git a/content/en/language_clients/python/github_action.md b/content/en/language_clients/python/github_action.md new file mode 100644 index 00000000..2d681fd7 --- /dev/null +++ b/content/en/language_clients/python/github_action.md @@ -0,0 +1,24 @@ +--- +type: docs +category: Python +menuTitle: GitHub Action +title: GitHub Action +weight: 50 +--- + +## GitHub Actions + +`sigstore-python` has [an official GitHub Action](https://github.com/sigstore/gh-action-sigstore-python)! + +You can install it from the [GitHub Marketplace](https://github.com/marketplace/actions/gh-action-sigstore-python), or add it to your CI manually: + +```yaml +jobs: + sigstore-python: + steps: + - uses: sigstore/gh-action-sigstore-python@v0.2.0 + with: + inputs: foo.txt +``` + +See the [action documentation](https://github.com/sigstore/gh-action-sigstore-python/blob/main/README.md) for more details and usage examples. diff --git a/content/en/language_clients/python/installation.md b/content/en/language_clients/python/installation.md new file mode 100644 index 00000000..763e514d --- /dev/null +++ b/content/en/language_clients/python/installation.md @@ -0,0 +1,21 @@ +--- +type: docs +category: Python +menuTitle: Installation +title: Installation +weight: 5 +--- + +`sigstore` requires Python 3.8 or newer, and can be installed directly via `pip`: + +```console +python -m pip install sigstore +``` + +Optionally, to install `sigstore` and all its dependencies with [hash-checking mode](https://pip.pypa.io/en/stable/topics/secure-installs/#hash-checking-mode) enabled, run the following: + +```console +python -m pip install -r https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txt +``` + +This installs the up-to-date [requirements file](https://github.com/sigstore/sigstore-python/blob/main/install/requirements.txt). diff --git a/content/en/language_clients/python/python_client_overview.md b/content/en/language_clients/python/python_client_overview.md new file mode 100644 index 00000000..97cef355 --- /dev/null +++ b/content/en/language_clients/python/python_client_overview.md @@ -0,0 +1,61 @@ +--- +type: docs +category: Python +menuTitle: Python Client Overview +title: Python Client Overview +weight: 1 +--- + +[`sigstore`](https://pypi.org/project/sigstore/) is a Python tool for generating and verifying Sigstore signatures. You can use it to sign and verify Python package distributions, or anything else! + +## Features + +* Supports keyless signature generation and verification +* Supports signing with ["ambient" OpenID Connect identities](../signing#signing-with-ambient-credentials) +* A comprehensive [CLI](#usage) and corresponding [importable Python API](https://sigstore.github.io/sigstore-python) +* An official [GitHub Action](../github_action) + +## Usage + +For Python API usage, see our [API documentation](https://sigstore.github.io/sigstore-python/). + +You can run `sigstore` as a standalone program, or via `python -m`: + +```console +sigstore --help +python -m sigstore --help +``` + +Top-level: + + +```console +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 + 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) +``` + + +### SLSA Provenance + +This 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 instructions [here](https://github.com/slsa-framework/slsa-github-generator#verification-of-provenance). diff --git a/content/en/language_clients/python/root_of_trust.md b/content/en/language_clients/python/root_of_trust.md new file mode 100644 index 00000000..e23a46db --- /dev/null +++ b/content/en/language_clients/python/root_of_trust.md @@ -0,0 +1,19 @@ +--- +type: docs +category: Python +menuTitle: Custom root of trust +title: Custom root of trust +weight: 30 +--- +## Configuring a custom root of trust ("BYO PKI") + +Apart from the default and "staging" Sigstore instances, `sigstore` also supports "BYO PKI" setups, where a user maintains their own Sigstore instance services. + +These are supported via the `--trust-config` flag, which accepts a JSON-formatted file conforming to the `ClientTrustConfig` message in the [Sigstore protobuf specs](https://github.com/sigstore/protobuf-specs). This file configures the entire Sigstore instance state, *including* the URIs used to access the CA and artifact transparency services as well as the cryptographic root of trust itself. + +To use a custom client config, prepend `--trust-config` to any `sigstore` command: + +```console +sigstore --trust-config custom.trustconfig.json sign foo.txt +sigstore --trust-config custom.trustconfig.json verify identity foo.txt ... +``` diff --git a/content/en/language_clients/python/signing.md b/content/en/language_clients/python/signing.md new file mode 100644 index 00000000..d707a1dd --- /dev/null +++ b/content/en/language_clients/python/signing.md @@ -0,0 +1,110 @@ +--- +type: docs +category: Python +menuTitle: Signing +title: Signing +weight: 10 +--- + + +```console +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) +``` + + +## Advanced signing use cases + +### Signing with ambient credentials + +For environments that support OpenID Connect, natively `sigstore` supports ambient credential +detection. This includes many popular CI platforms and cloud providers. See the full list of +supported environments [here](https://github.com/di/id#supported-environments). + +Sign a single file (`foo.txt`) using an ambient OpenID Connect credential, +saving the bundle to `foo.txt.sigstore`: + +```console +python -m sigstore sign foo.txt +``` + +### Signing with an email identity + +`sigstore` can 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 to `foo.txt.sigstore`: + +```console +python -m sigstore sign foo.txt +``` + +By default, `sigstore` attempts to do +[ambient credential detection](#signing-with-ambient-credentials), which may preempt +the OAuth2 flow. To force the OAuth2 flow, you can explicitly disable ambient detection: + +```console +python -m sigstore sign --oidc-disable-ambient-providers foo.txt +``` + +### Signing with an explicit identity token + +If you can't use an ambient credential or the OAuth2 flow, you can pass a pre-created +identity token directly into `sigstore sign`: + +```console +python -m sigstore sign --identity-token YOUR-LONG-JWT-HERE foo.txt +``` + +Note 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. diff --git a/content/en/language_clients/python/verifying.md b/content/en/language_clients/python/verifying.md new file mode 100644 index 00000000..9383899c --- /dev/null +++ b/content/en/language_clients/python/verifying.md @@ -0,0 +1,160 @@ +--- +type: docs +category: Python +menuTitle: Verifying +title: Verifying +weight: 20 +--- +### Generic identities + +This is the most common verification done with `sigstore`, and therefore +the one you probably want: you can use it to verify that a signature was +produced by a particular identity (like `hamilcar@example.com`), as attested +to by a particular OIDC provider (like `https://github.com/login/oauth`). + + +```console +usage: sigstore verify identity [-h] [-v] [--certificate FILE] + [--signature FILE] [--bundle FILE] [--offline] + --cert-identity IDENTITY --cert-oidc-issuer + URL + 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 (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 The file to verify + +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) +``` + + +### Signatures from GitHub Actions + +If your signatures are coming from GitHub Actions (e.g., a workflow +that uses its [ambient credentials](../signing#signing-with-ambient-credentials)), +then you can use the `sigstore verify github` subcommand to verify +claims more precisely than `sigstore verify identity` allows: + + +```console +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 [FILE ...] + +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 The file to verify + +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) +``` + + +## Advanced verification use cases + +### Verifying against a signature and certificate + +By default, `sigstore verify identity` will attempt to find a `.sigstore` in the +same directory as the file being verified: + +```console +# 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' +``` + +Multiple files can be verified at once: + +```console +# 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' +``` + +### Verifying signatures from GitHub Actions + +`sigstore verify github` can be used to verify claims specific to signatures coming from GitHub +Actions. `sigstore-python` signs releases via GitHub Actions, so the examples below are working +examples of how you can verify a given `sigstore-python` release. + +When using `sigstore verify github`, you must pass `--cert-identity` or `--repository`, or both. +Unlike `sigstore verify identity`, `--cert-oidc-issuer` is **not** required (since it's +inferred to be GitHub Actions). + +Verifying with `--cert-identity`: + +```console +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 +``` + +Verifying with `--repository`: + +```console +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 +``` + +Additional GitHub Actions specific claims can be verified like so: + +```console +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 +```