Adding information on Python Language Client

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

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
+---

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/[email protected]
+        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.

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

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:
+
+<!-- @begin-sigstore-help@ -->
+```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)
+```
+<!-- @end-sigstore-help@ -->
+
+### 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).

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 ...
+```

content/en/language_clients/python/signing.md

@@ -0,0 +1,110 @@
+---
+type: docs
+category: Python
+menuTitle: Signing
+title: Signing
+weight: 10
+---
+
+<!-- @begin-sigstore-sign-help@ -->
+```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)
+```
+<!-- @end-sigstore-sign-help@ -->
+
+## 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.