Skip to content

Commit

Permalink
docs: add details of how to verify provenance JSON files (pypi#17391)
Browse files Browse the repository at this point in the history
Signed-off-by: Facundo Tuesca <facundo.tuesca@trailofbits.com>
  • Loading branch information
facutuesca authored Jan 13, 2025
1 parent f6161cc commit 0d0a56e
Showing 1 changed file with 27 additions and 0 deletions.
27 changes: 27 additions & 0 deletions docs/user/attestations/consuming-attestations.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,31 @@ and simple JSON APIs.

For a full API reference, see the [Integrity API documentation].

## Internals

Since a distribution file can have multiple attestations, and PyPI serves
these attestations as a single JSON file, this JSON file groups the
attestations into a single [provenance object]. This object contains
bundles of attestations grouped by the Trusted Publisher identity used
to sign them.

To manually verify a PyPI artifact against its provenance object,
the [`pypi-attestations`][pypi-attestations] CLI tool can be used:

```bash
export WHEEL_DIRECT_URL=https://files.pythonhosted.org/packages/d7/73/c16e5f3f0d37c60947e70865c255a58dc408780a6474de0523afd0ec553a/sampleproject-4.0.0-py3-none-any.whl

pypi-attestations verify pypi --repository https://github.com/pypa/sampleproject $WHEEL_DIRECT_URL
```

This downloads the wheel from PyPI and its corresponding provenance JSON
(using the Integrity API), checks that the Trusted Publishers specified
in the provenance match the `--repository` argument passed by the user,
and finally cryptographically verifies the wheel against the included
attestations.


[Integrity API documentation]: /api/integrity/
[provenance object]: https://packaging.python.org/en/latest/specifications/index-hosted-attestations/#provenance-objects
[pypi-attestations]: https://pypi.org/project/pypi-attestations/

0 comments on commit 0d0a56e

Please sign in to comment.