| Name | sigstore JSON |
| Version |
3.5.1
JSON |
| download |
| home_page | None |
| Summary | A tool for signing Python package distributions |
| upload_time | 2024-10-25 14:59:53 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
sigstore-python
===============
<!--- @begin-badges@ --->
[](https://pypi.org/project/sigstore)
[](https://securityscorecards.dev/viewer/?uri=github.com/sigstore/sigstore-python)
[](https://slsa.dev/)
[](https://sigstore.github.io/sigstore-python)
<!--- @end-badges@ --->
`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!
## Index
* [Features](#features)
* [Installation](#installation)
* [GitHub Actions](#github-actions)
* [Usage](#usage)
* [Signing](#signing)
* [Verifying](#verifying)
* [Generic identities](#generic-identities)
* [Signatures from GitHub Actions](#signatures-from-github-actions)
* [Advanced usage](#advanced-usage)
* [Example uses](#example-uses)
* [Signing with ambient credentials](#signing-with-ambient-credentials)
* [Signing with an email identity](#signing-with-an-email-identity)
* [Signing with an explicit identity token](#signing-with-an-explicit-identity-token)
* [Verifying against a bundle](#verifying-against-a-bundle)
* [Offline verification](#offline-verification)
* [Verifying a digest instead of a file](#verifying-a-digest-instead-of-a-file)
* [Verifying signatures from GitHub Actions](#verifying-signatures-from-github-actions)
* [Licensing](#licensing)
* [Community](#community)
* [Contributing](#contributing)
* [Code of Conduct](#code-of-conduct)
* [Security](#security)
* [SLSA Provenance](#slsa-provenance)
## Features
* Support for keyless signature generation and verification with [Sigstore](https://www.sigstore.dev/)
* Support for signing with ["ambient" OpenID Connect identities](https://github.com/sigstore/sigstore-python#signing-with-ambient-credentials)
* A comprehensive [CLI](https://github.com/sigstore/sigstore-python#usage) and corresponding
[importable Python API](https://sigstore.github.io/sigstore-python)
## Installation
`sigstore` requires Python 3.9 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 requirements file located [here](https://github.com/sigstore/sigstore-python/blob/main/install/requirements.txt), which is kept up-to-date.
### 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@v3.0.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.
## Usage
For Python API usage, see our [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@ -->
```
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)
```
<!-- @end-sigstore-help@ -->
### Signing
<!-- @begin-sigstore-sign-help@ -->
```
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@ -->
### Signing with DSSE envelopes
<!-- @begin-sigstore-attest-help@ -->
```
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)
```
<!-- @end-sigstore-attest-help@ -->
### Verifying
#### 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`).
<!-- @begin-sigstore-verify-identity-help@ -->
```
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)
```
<!-- @end-sigstore-verify-identity-help@ -->
#### Signatures from GitHub Actions
If your signatures are coming from GitHub Actions (e.g., a workflow
that uses its [ambient credentials](#signing-with-ambient-credentials)),
then you can use the `sigstore verify github` subcommand to verify
claims more precisely than `sigstore verify identity` allows:
<!-- @begin-sigstore-verify-github-help@ -->
```
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)
```
<!-- @end-sigstore-verify-github-help@ -->
## Advanced usage
### 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 ...
```
## Example uses
`sigstore` supports a wide variety of workflows and usages. Some common ones are
provided below.
### Signing with ambient credentials
For environments that support OpenID Connect, `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.json`:
```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.json`:
```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.
### Verifying against a bundle
By default, `sigstore verify identity` will attempt to find a `<filename>.sigstore.json`
or `<filename>.sigstore` in the same directory as the file being verified:
```console
# looks for foo.txt.sigstore.json
$ 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.json
$ python -m sigstore verify identity foo.txt bar.txt \
--cert-identity 'hamilcar@example.com' \
--cert-oidc-issuer 'https://github.com/login/oauth'
```
### Offline verification
> [!IMPORTANT]
> Because `--offline` disables trust root updates, `sigstore-python` falls back
> to the latest cached trust root or, if none exists, the trust root baked
> into `sigstore-python` itself. Like with any other offline verification,
> this means that users may miss trust root changes (such as new root keys,
> or revocations) unless they separately keep the trust root up-to-date.
>
> Users who need to operationalize offline verification may wish to do this
> by distributing their own trust configuration; see
> [Configuring a custom root of trust](#configuring-a-custom-root-of-trust-byo-pki).
During verification, there are two kinds of network access that `sigstore-python`
*can* perform:
1. When verifying against "detached" materials (e.g. separate `.crt` and `.sig`
files), `sigstore-python` can perform an online transparency log lookup.
2. By default, during all verifications, `sigstore-python` will attempt to
refresh the locally cached root of trust via a TUF update.
When performing bundle verification (i.e. `.sigstore` or `.sigstore.json`),
(1) does not apply. However, (2) can still result in online accesses.
To perform **fully** offline verification, pass `--offline` to your
`sigstore verify` subcommand:
```bash
$ python -m sigstore verify identity foo.txt \
--offline \
--cert-identity 'hamilcar@example.com' \
--cert-oidc-issuer 'https://github.com/login/oauth'
```
Alternatively, users may choose to bypass TUF entirely by passing
an entire trust configuration to `sigstore-python` via `--trust-config`:
```bash
$ python -m sigstore --trust-config public.trustconfig.json verify identity ...
```
This will similarly result in fully offline operation, as the trust
configuration contains a full trust root.
### Verifying a digest instead of a file
`sigstore-python` supports verifying digests directly, without requiring the artifact to be
present. The digest should be prefixed with the `sha256:` string:
```console
$ 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'
```
### 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
```
## Licensing
`sigstore` is licensed under the Apache 2.0 License.
## Community
`sigstore-python` is developed as part of the [Sigstore](https://sigstore.dev) project.
We also use a [Slack channel](https://sigstore.slack.com)!
Click [here](https://join.slack.com/t/sigstore/shared_invite/zt-mhs55zh0-XmY3bcfWn4XEyMqUUutbUQ) for the invite link.
## Contributing
See [the contributing docs](https://github.com/sigstore/.github/blob/main/CONTRIBUTING.md) for details.
## Code of Conduct
Everyone interacting with this project is expected to follow the
[sigstore Code of Conduct](https://github.com/sigstore/.github/blob/main/CODE_OF_CONDUCT.md).
## Security
Should you discover any security issues, please refer to sigstore's [security
process](https://github.com/sigstore/.github/blob/main/SECURITY.md).
### 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).
Raw data
{
"_id": null,
"home_page": null,
"name": "sigstore",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Sigstore Authors <sigstore-dev@googlegroups.com>",
"download_url": "https://files.pythonhosted.org/packages/61/21/56261dca07b560131b03d8659f6ba39cf30dc2af96269f3982098aa6bb83/sigstore-3.5.1.tar.gz",
"platform": null,
"description": "sigstore-python\n===============\n\n<!--- @begin-badges@ --->\n\n[](https://pypi.org/project/sigstore)\n[](https://securityscorecards.dev/viewer/?uri=github.com/sigstore/sigstore-python)\n[](https://slsa.dev/)\n\n[](https://sigstore.github.io/sigstore-python)\n<!--- @end-badges@ --->\n\n`sigstore` is a Python tool for generating and verifying Sigstore signatures.\nYou can use it to sign and verify Python package distributions, or anything\nelse!\n\n## Index\n\n* [Features](#features)\n* [Installation](#installation)\n * [GitHub Actions](#github-actions)\n* [Usage](#usage)\n * [Signing](#signing)\n * [Verifying](#verifying)\n * [Generic identities](#generic-identities)\n * [Signatures from GitHub Actions](#signatures-from-github-actions)\n * [Advanced usage](#advanced-usage)\n* [Example uses](#example-uses)\n * [Signing with ambient credentials](#signing-with-ambient-credentials)\n * [Signing with an email identity](#signing-with-an-email-identity)\n * [Signing with an explicit identity token](#signing-with-an-explicit-identity-token)\n * [Verifying against a bundle](#verifying-against-a-bundle)\n * [Offline verification](#offline-verification)\n * [Verifying a digest instead of a file](#verifying-a-digest-instead-of-a-file)\n * [Verifying signatures from GitHub Actions](#verifying-signatures-from-github-actions)\n* [Licensing](#licensing)\n* [Community](#community)\n* [Contributing](#contributing)\n* [Code of Conduct](#code-of-conduct)\n* [Security](#security)\n* [SLSA Provenance](#slsa-provenance)\n\n## Features\n\n* Support for keyless signature generation and verification with [Sigstore](https://www.sigstore.dev/)\n* Support for signing with [\"ambient\" OpenID Connect identities](https://github.com/sigstore/sigstore-python#signing-with-ambient-credentials)\n* A comprehensive [CLI](https://github.com/sigstore/sigstore-python#usage) and corresponding\n [importable Python API](https://sigstore.github.io/sigstore-python)\n\n## Installation\n\n`sigstore` requires Python 3.9 or newer, and can be installed directly via `pip`:\n\n```console\npython -m pip install sigstore\n```\n\nOptionally, 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:\n\n```console\npython -m pip install -r https://raw.githubusercontent.com/sigstore/sigstore-python/main/install/requirements.txt\n```\n\nThis installs the requirements file located [here](https://github.com/sigstore/sigstore-python/blob/main/install/requirements.txt), which is kept up-to-date.\n\n### GitHub Actions\n\n`sigstore-python` has [an official GitHub Action](https://github.com/sigstore/gh-action-sigstore-python)!\n\nYou can install it from the\n[GitHub Marketplace](https://github.com/marketplace/actions/gh-action-sigstore-python), or\nadd it to your CI manually:\n\n```yaml\njobs:\n sigstore-python:\n steps:\n - uses: sigstore/gh-action-sigstore-python@v3.0.0\n with:\n inputs: foo.txt\n```\n\nSee the\n[action documentation](https://github.com/sigstore/gh-action-sigstore-python/blob/main/README.md)\nfor more details and usage examples.\n\n## Usage\n\nFor Python API usage, see our [documentation](https://sigstore.github.io/sigstore-python/).\n\nYou can run `sigstore` as a standalone program, or via `python -m`:\n\n```console\nsigstore --help\npython -m sigstore --help\n```\n\nTop-level:\n\n<!-- @begin-sigstore-help@ -->\n```\nusage: sigstore [-h] [-v] [-V] [--staging | --trust-config FILE] COMMAND ...\n\na tool for signing and verifying Python package distributions\n\npositional arguments:\n COMMAND the operation to perform\n attest sign one or more inputs using DSSE\n sign sign one or more inputs\n verify verify one or more inputs\n get-identity-token\n retrieve and return a Sigstore-compatible OpenID\n Connect token\n plumbing developer-only plumbing operations\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose run with additional debug logging; supply multiple\n times to increase verbosity (default: 0)\n -V, --version show program's version number and exit\n --staging Use sigstore's staging instances, instead of the\n default production instances (default: False)\n --trust-config FILE The client trust configuration to use (default: None)\n```\n<!-- @end-sigstore-help@ -->\n\n\n### Signing\n\n<!-- @begin-sigstore-sign-help@ -->\n```\nusage: sigstore sign [-h] [-v] [--identity-token TOKEN] [--oidc-client-id ID]\n [--oidc-client-secret SECRET]\n [--oidc-disable-ambient-providers] [--oidc-issuer URL]\n [--oauth-force-oob] [--no-default-files]\n [--signature FILE] [--certificate FILE] [--bundle FILE]\n [--output-directory DIR] [--overwrite]\n FILE [FILE ...]\n\npositional arguments:\n FILE The file to sign\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose run with additional debug logging; supply multiple\n times to increase verbosity (default: 0)\n\nOpenID Connect options:\n --identity-token TOKEN\n the OIDC identity token to use (default: None)\n --oidc-client-id ID The custom OpenID Connect client ID to use during\n OAuth2 (default: sigstore)\n --oidc-client-secret SECRET\n The custom OpenID Connect client secret to use during\n OAuth2 (default: None)\n --oidc-disable-ambient-providers\n Disable ambient OpenID Connect credential detection\n (e.g. on GitHub Actions) (default: False)\n --oidc-issuer URL The OpenID Connect issuer to use (conflicts with\n --staging) (default: https://oauth2.sigstore.dev/auth)\n --oauth-force-oob Force an out-of-band OAuth flow and do not\n automatically start the default web browser (default:\n False)\n\nOutput options:\n --no-default-files Don't emit the default output files\n ({input}.sigstore.json) (default: False)\n --signature FILE, --output-signature FILE\n Write a single signature to the given file; does not\n work with multiple input files (default: None)\n --certificate FILE, --output-certificate FILE\n Write a single certificate to the given file; does not\n work with multiple input files (default: None)\n --bundle FILE Write a single Sigstore bundle to the given file; does\n not work with multiple input files (default: None)\n --output-directory DIR\n Write default outputs to the given directory\n (conflicts with --signature, --certificate, --bundle)\n (default: None)\n --overwrite Overwrite preexisting signature and certificate\n outputs, if present (default: False)\n```\n<!-- @end-sigstore-sign-help@ -->\n\n\n### Signing with DSSE envelopes\n\n<!-- @begin-sigstore-attest-help@ -->\n```\nusage: sigstore attest [-h] [-v] --predicate FILE --predicate-type TYPE\n [--identity-token TOKEN] [--oidc-client-id ID]\n [--oidc-client-secret SECRET]\n [--oidc-disable-ambient-providers] [--oidc-issuer URL]\n [--oauth-force-oob] [--bundle FILE] [--overwrite]\n FILE [FILE ...]\n\npositional arguments:\n FILE The file to sign\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose run with additional debug logging; supply multiple\n times to increase verbosity (default: 0)\n\nDSSE options:\n --predicate FILE Path to the predicate file (default: None)\n --predicate-type TYPE\n Specify a predicate type\n (https://slsa.dev/provenance/v0.2,\n https://slsa.dev/provenance/v1) (default: None)\n\nOpenID Connect options:\n --identity-token TOKEN\n the OIDC identity token to use (default: None)\n --oidc-client-id ID The custom OpenID Connect client ID to use during\n OAuth2 (default: sigstore)\n --oidc-client-secret SECRET\n The custom OpenID Connect client secret to use during\n OAuth2 (default: None)\n --oidc-disable-ambient-providers\n Disable ambient OpenID Connect credential detection\n (e.g. on GitHub Actions) (default: False)\n --oidc-issuer URL The OpenID Connect issuer to use (conflicts with\n --staging) (default: https://oauth2.sigstore.dev/auth)\n --oauth-force-oob Force an out-of-band OAuth flow and do not\n automatically start the default web browser (default:\n False)\n\nOutput options:\n --bundle FILE Write a single Sigstore bundle to the given file; does\n not work with multiple input files (default: None)\n --overwrite Overwrite preexisting bundle outputs, if present\n (default: False)\n```\n<!-- @end-sigstore-attest-help@ -->\n\n### Verifying\n\n#### Generic identities\n\nThis is the most common verification done with `sigstore`, and therefore\nthe one you probably want: you can use it to verify that a signature was\nproduced by a particular identity (like `hamilcar@example.com`), as attested\nto by a particular OIDC provider (like `https://github.com/login/oauth`).\n\n<!-- @begin-sigstore-verify-identity-help@ -->\n```\nusage: sigstore verify identity [-h] [-v] [--certificate FILE]\n [--signature FILE] [--bundle FILE] [--offline]\n --cert-identity IDENTITY --cert-oidc-issuer\n URL\n FILE_OR_DIGEST [FILE_OR_DIGEST ...]\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose run with additional debug logging; supply multiple\n times to increase verbosity (default: 0)\n\nVerification inputs:\n --certificate FILE, --cert FILE\n The PEM-encoded certificate to verify against; not\n used with multiple inputs (default: None)\n --signature FILE The signature to verify against; not used with\n multiple inputs (default: None)\n --bundle FILE The Sigstore bundle to verify with; not used with\n multiple inputs (default: None)\n FILE_OR_DIGEST The file path or the digest to verify. The digest\n should start with the 'sha256:' prefix.\n\nVerification options:\n --offline Perform offline verification; requires a Sigstore\n bundle (default: False)\n --cert-identity IDENTITY\n The identity to check for in the certificate's Subject\n Alternative Name (default: None)\n --cert-oidc-issuer URL\n The OIDC issuer URL to check for in the certificate's\n OIDC issuer extension (default: None)\n```\n<!-- @end-sigstore-verify-identity-help@ -->\n\n#### Signatures from GitHub Actions\n\nIf your signatures are coming from GitHub Actions (e.g., a workflow\nthat uses its [ambient credentials](#signing-with-ambient-credentials)),\nthen you can use the `sigstore verify github` subcommand to verify\nclaims more precisely than `sigstore verify identity` allows:\n\n<!-- @begin-sigstore-verify-github-help@ -->\n```\nusage: sigstore verify github [-h] [-v] [--certificate FILE]\n [--signature FILE] [--bundle FILE] [--offline]\n [--cert-identity IDENTITY] [--trigger EVENT]\n [--sha SHA] [--name NAME] [--repository REPO]\n [--ref REF]\n FILE_OR_DIGEST [FILE_OR_DIGEST ...]\n\noptional arguments:\n -h, --help show this help message and exit\n -v, --verbose run with additional debug logging; supply multiple\n times to increase verbosity (default: 0)\n\nVerification inputs:\n --certificate FILE, --cert FILE\n The PEM-encoded certificate to verify against; not\n used with multiple inputs (default: None)\n --signature FILE The signature to verify against; not used with\n multiple inputs (default: None)\n --bundle FILE The Sigstore bundle to verify with; not used with\n multiple inputs (default: None)\n FILE_OR_DIGEST The file path or the digest to verify. The digest\n should start with the 'sha256:' prefix.\n\nVerification options:\n --offline Perform offline verification; requires a Sigstore\n bundle (default: False)\n --cert-identity IDENTITY\n The identity to check for in the certificate's Subject\n Alternative Name (default: None)\n --trigger EVENT The GitHub Actions event name that triggered the\n workflow (default: None)\n --sha SHA The `git` commit SHA that the workflow run was invoked\n with (default: None)\n --name NAME The name of the workflow that was triggered (default:\n None)\n --repository REPO The repository slug that the workflow was triggered\n under (default: None)\n --ref REF The `git` ref that the workflow was invoked with\n (default: None)\n```\n<!-- @end-sigstore-verify-github-help@ -->\n\n## Advanced usage\n\n### Configuring a custom root of trust (\"BYO PKI\")\n\nApart from the default and \"staging\" Sigstore instances, `sigstore` also\nsupports \"BYO PKI\" setups, where a user maintains their own Sigstore\ninstance services.\n\nThese are supported via the `--trust-config` flag, which accepts a\nJSON-formatted file conforming to the `ClientTrustConfig` message\nin the [Sigstore protobuf specs](https://github.com/sigstore/protobuf-specs).\nThis file configures the entire Sigstore instance state, *including* the URIs\nused to access the CA and artifact transparency services as well as the\ncryptographic root of trust itself.\n\nTo use a custom client config, prepend `--trust-config` to any `sigstore`\ncommand:\n\n```console\n$ sigstore --trust-config custom.trustconfig.json sign foo.txt\n$ sigstore --trust-config custom.trustconfig.json verify identity foo.txt ...\n```\n\n## Example uses\n\n`sigstore` supports a wide variety of workflows and usages. Some common ones are\nprovided below.\n\n### Signing with ambient credentials\n\nFor environments that support OpenID Connect, `sigstore` supports ambient credential\ndetection. This includes many popular CI platforms and cloud providers. See the full list of\nsupported environments [here](https://github.com/di/id#supported-environments).\n\nSign a single file (`foo.txt`) using an ambient OpenID Connect credential,\nsaving the bundle to `foo.txt.sigstore.json`:\n\n```console\n$ python -m sigstore sign foo.txt\n```\n\n### Signing with an email identity\n\n`sigstore` can use an OAuth2 + OpenID flow to establish an email identity,\nallowing you to request signing certificates that attest to control over\nthat email.\n\nSign a single file (`foo.txt`) using the OAuth2 flow, saving the\nbundle to `foo.txt.sigstore.json`:\n\n```console\n$ python -m sigstore sign foo.txt\n```\n\nBy default, `sigstore` attempts to do\n[ambient credential detection](#signing-with-ambient-credentials), which may preempt\nthe OAuth2 flow. To force the OAuth2 flow, you can explicitly disable ambient detection:\n\n```console\n$ python -m sigstore sign --oidc-disable-ambient-providers foo.txt\n```\n\n### Signing with an explicit identity token\n\nIf you can't use an ambient credential or the OAuth2 flow, you can pass a pre-created\nidentity token directly into `sigstore sign`:\n\n```console\n$ python -m sigstore sign --identity-token YOUR-LONG-JWT-HERE foo.txt\n```\n\nNote that passing a custom identity token does not circumvent Fulcio's requirements,\nnamely the Fulcio's supported identity providers and the claims expected within the token.\n\n### Verifying against a bundle\n\nBy default, `sigstore verify identity` will attempt to find a `<filename>.sigstore.json`\nor `<filename>.sigstore` in the same directory as the file being verified:\n\n```console\n# looks for foo.txt.sigstore.json\n$ python -m sigstore verify identity foo.txt \\\n --cert-identity 'hamilcar@example.com' \\\n --cert-oidc-issuer 'https://github.com/login/oauth'\n```\n\nMultiple files can be verified at once:\n\n```console\n# looks for {foo,bar}.txt.sigstore.json\n$ python -m sigstore verify identity foo.txt bar.txt \\\n --cert-identity 'hamilcar@example.com' \\\n --cert-oidc-issuer 'https://github.com/login/oauth'\n```\n\n### Offline verification\n\n> [!IMPORTANT]\n> Because `--offline` disables trust root updates, `sigstore-python` falls back\n> to the latest cached trust root or, if none exists, the trust root baked\n> into `sigstore-python` itself. Like with any other offline verification,\n> this means that users may miss trust root changes (such as new root keys,\n> or revocations) unless they separately keep the trust root up-to-date.\n>\n> Users who need to operationalize offline verification may wish to do this\n> by distributing their own trust configuration; see\n> [Configuring a custom root of trust](#configuring-a-custom-root-of-trust-byo-pki).\n\nDuring verification, there are two kinds of network access that `sigstore-python`\n*can* perform:\n\n1. When verifying against \"detached\" materials (e.g. separate `.crt` and `.sig`\n files), `sigstore-python` can perform an online transparency log lookup.\n2. By default, during all verifications, `sigstore-python` will attempt to\n refresh the locally cached root of trust via a TUF update.\n\nWhen performing bundle verification (i.e. `.sigstore` or `.sigstore.json`),\n(1) does not apply. However, (2) can still result in online accesses.\n\nTo perform **fully** offline verification, pass `--offline` to your\n`sigstore verify` subcommand:\n\n```bash\n$ python -m sigstore verify identity foo.txt \\\n --offline \\\n --cert-identity 'hamilcar@example.com' \\\n --cert-oidc-issuer 'https://github.com/login/oauth'\n```\n\nAlternatively, users may choose to bypass TUF entirely by passing\nan entire trust configuration to `sigstore-python` via `--trust-config`:\n\n```bash\n$ python -m sigstore --trust-config public.trustconfig.json verify identity ...\n```\n\nThis will similarly result in fully offline operation, as the trust\nconfiguration contains a full trust root.\n\n### Verifying a digest instead of a file\n\n`sigstore-python` supports verifying digests directly, without requiring the artifact to be\npresent. The digest should be prefixed with the `sha256:` string:\n\n```console\n$ python -m sigstore verify identity sha256:ce8ab2822671752e201ea1e19e8c85e73d497e1c315bfd9c25f380b7625d1691 \\\n --cert-identity 'hamilcar@example.com' \\\n --cert-oidc-issuer 'https://github.com/login/oauth'\n --bundle 'foo.txt.sigstore.json'\n```\n\n### Verifying signatures from GitHub Actions\n\n`sigstore verify github` can be used to verify claims specific to signatures coming from GitHub\nActions. `sigstore-python` signs releases via GitHub Actions, so the examples below are working\nexamples of how you can verify a given `sigstore-python` release.\n\nWhen using `sigstore verify github`, you must pass `--cert-identity` or `--repository`, or both.\nUnlike `sigstore verify identity`, `--cert-oidc-issuer` is **not** required (since it's\ninferred to be GitHub Actions).\n\nVerifying with `--cert-identity`:\n\n```console\n$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \\\n --bundle sigstore-0.10.0-py3-none-any.whl.bundle \\\n --cert-identity https://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0\n```\n\nVerifying with `--repository`:\n\n```console\n$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \\\n --bundle sigstore-0.10.0-py3-none-any.whl.bundle \\\n --repository sigstore/sigstore-python\n```\n\nAdditional GitHub Actions specific claims can be verified like so:\n\n```console\n$ python -m sigstore verify github sigstore-0.10.0-py3-none-any.whl \\\n --bundle sigstore-0.10.0-py3-none-any.whl.bundle \\\n --cert-identity https://github.com/sigstore/sigstore-python/.github/workflows/release.yml@refs/tags/v0.10.0 \\\n --trigger release \\\n --sha 66581529803929c3ccc45334632ccd90f06e0de4 \\\n --name Release \\\n --repository sigstore/sigstore-python \\\n --ref refs/tags/v0.10.0\n```\n\n## Licensing\n\n`sigstore` is licensed under the Apache 2.0 License.\n\n## Community\n\n`sigstore-python` is developed as part of the [Sigstore](https://sigstore.dev) project.\n\nWe also use a [Slack channel](https://sigstore.slack.com)!\nClick [here](https://join.slack.com/t/sigstore/shared_invite/zt-mhs55zh0-XmY3bcfWn4XEyMqUUutbUQ) for the invite link.\n\n## Contributing\n\nSee [the contributing docs](https://github.com/sigstore/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Code of Conduct\n\nEveryone interacting with this project is expected to follow the\n[sigstore Code of Conduct](https://github.com/sigstore/.github/blob/main/CODE_OF_CONDUCT.md).\n\n## Security\n\nShould you discover any security issues, please refer to sigstore's [security\nprocess](https://github.com/sigstore/.github/blob/main/SECURITY.md).\n\n### SLSA Provenance\nThis project emits a SLSA provenance on its release! This enables you to verify the integrity\nof the downloaded artifacts and ensured that the binary's code really comes from this source code.\n\nTo do so, please follow the instructions [here](https://github.com/slsa-framework/slsa-github-generator#verification-of-provenance).\n\n",
"bugtrack_url": null,
"license": null,
"summary": "A tool for signing Python package distributions",
"version": "3.5.1",
"project_urls": {
"Documentation": "https://sigstore.github.io/sigstore-python/",
"Homepage": "https://pypi.org/project/sigstore/",
"Issues": "https://github.com/sigstore/sigstore-python/issues",
"Source": "https://github.com/sigstore/sigstore-python"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fdf9ffa0b32438061e838224f7a52bfa09feda294076a03832d3802e9eba2bb7",
"md5": "d04e7f1e96a26ce610414a9041b0a226",
"sha256": "e7023aef4e574120712c16c6bb151f4caee55791c4677fe30c92ef4e50800204"
},
"downloads": -1,
"filename": "sigstore-3.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d04e7f1e96a26ce610414a9041b0a226",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 98599,
"upload_time": "2024-10-25T14:59:51",
"upload_time_iso_8601": "2024-10-25T14:59:51.015981Z",
"url": "https://files.pythonhosted.org/packages/fd/f9/ffa0b32438061e838224f7a52bfa09feda294076a03832d3802e9eba2bb7/sigstore-3.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "612156261dca07b560131b03d8659f6ba39cf30dc2af96269f3982098aa6bb83",
"md5": "202102533c93028ad8c31c6a2a24ba8c",
"sha256": "88f73c8edf1662ff9b86ef6fe0870bb6af4ac99ff808b84995e6a41957b7b3d2"
},
"downloads": -1,
"filename": "sigstore-3.5.1.tar.gz",
"has_sig": false,
"md5_digest": "202102533c93028ad8c31c6a2a24ba8c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 83836,
"upload_time": "2024-10-25T14:59:53",
"upload_time_iso_8601": "2024-10-25T14:59:53.439531Z",
"url": "https://files.pythonhosted.org/packages/61/21/56261dca07b560131b03d8659f6ba39cf30dc2af96269f3982098aa6bb83/sigstore-3.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-25 14:59:53",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sigstore",
"github_project": "sigstore-python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "sigstore"
}
