|
| 1 | +--- |
| 2 | +title: PyPI now supports digital attestations |
| 3 | +description: Announcing support for PEP 740 on the Python Package Index |
| 4 | +authors: |
| 5 | + - di |
| 6 | +date: 2024-11-14 |
| 7 | +tags: |
| 8 | + - publishing |
| 9 | + - security |
| 10 | + - oidc |
| 11 | +--- |
| 12 | + |
| 13 | +PyPI package maintainers can now publish signed digital attestations when |
| 14 | +publishing, in order to further increase trust in the supply-chain security of |
| 15 | +their projects. Additionally, a new API is available for consumers and |
| 16 | +installers to verify published attestations. |
| 17 | + |
| 18 | +Many projects have already begun publishing attestations, with more than 20,000 |
| 19 | +attestations already published. |
| 20 | + |
| 21 | +This finalizes PyPI's support for [PEP 740], and follows directly from previous |
| 22 | +work to add support for [Trusted Publishing], as well as the [deprecation and |
| 23 | +removal of PGP signatures]. |
| 24 | + |
| 25 | +<!-- more --> |
| 26 | + |
| 27 | +### Why not plain signatures? |
| 28 | + |
| 29 | +PyPI's support for digital attestations has three key advantages over regular |
| 30 | +cryptographic signatures, such as those provided by PGP: |
| 31 | + |
| 32 | +* **Attestations are signed by an identity, not a key pair:** |
| 33 | + Similar to our recent support for Trusted Publishing, PyPI's support for |
| 34 | + digital attestations relies upon Open ID Connect (OIDC) identities. By signing |
| 35 | + attestations with identities, and not a public/private key pair, we mitigate the |
| 36 | + potential for an individual's key loss or compromise, one of the most common failure cases for |
| 37 | + PGP signing. |
| 38 | +* **Attestations provide a verifiable link to an upstream source repository:** |
| 39 | + By signing with the identity of the upstream source repository, such as in the |
| 40 | + case of an upload of a project built with GitHub Actions, PyPI's support for |
| 41 | + digital attestations defines a strong and verifiable association between a file |
| 42 | + on PyPI and the source repository, workflow, and even the commit hash that |
| 43 | + produced and uploaded the file. Additionally, publishing attestations to a |
| 44 | + transparency log helps mitigate against both compromise of PyPI and compromise |
| 45 | + of the projects themselves. |
| 46 | +* **Attestations are verified when uploaded, and must be verifiable to be uploaded:** |
| 47 | + Upon review of the state of historical PGP signatures published to PyPI, [we |
| 48 | + found that many signatures were not verifiable], either by PyPI or by end |
| 49 | + users. With support for PEP 740, PyPI only permits attestations with a |
| 50 | + verifiable signature to be uploaded and redistributed by the index. This |
| 51 | + ensures that all attestations are verifiable and useful for all PyPI users. |
| 52 | + |
| 53 | +Much more detail is provided in a corresponding blog post by Trail of Bits: |
| 54 | +[Attestations: a new generation of signatures on PyPI]. |
| 55 | + |
| 56 | +### How to view a file's attestations |
| 57 | +For consumers and package installers wanting to perform verification, PyPI |
| 58 | +currently provides two ways to access digital attestations associated with a |
| 59 | +given file on PyPI: |
| 60 | + |
| 61 | +* **A new Integrity API for PyPI** |
| 62 | + The [Integrity API](https://docs.pypi.org/api/integrity/) provides programmatic |
| 63 | + access to PyPI's implementation of PEP 740. Operating on individual files, it |
| 64 | + collects all published attestations for a given file and returns them as a |
| 65 | + single response. |
| 66 | + |
| 67 | +* **A new web UI for viewing per-file attributes** |
| 68 | + Similarly, we have introduced a new page on PyPI's web UI, displaying details |
| 69 | + for individual files, including the presence of any attestations about the |
| 70 | + file. You can see an example here: |
| 71 | + <https://pypi.org/project/sampleproject/#sampleproject-4.0.0.tar.gz> |
| 72 | + |
| 73 | +### Get started today |
| 74 | + |
| 75 | +The generation and publication of attestations happens by default, and no |
| 76 | +changes are necessary for projects that meet all of these conditions: |
| 77 | + |
| 78 | +1. publish from GitHub Actions; |
| 79 | +2. via [Trusted Publishing]; and |
| 80 | +3. use the [pypa/gh-action-pypi-publish] action to publish. |
| 81 | + |
| 82 | +Support for automatic attestation generation and publication from other Trusted |
| 83 | +Publisher environments [is planned]. While not recommended, maintainers can also |
| 84 | +[manually generate and publish attestations]. |
| 85 | + |
| 86 | +### Acknowledgements |
| 87 | + |
| 88 | +Support for work on PEP 740's authoring and design was provided by the |
| 89 | +[Sovereign Tech Agency] and the Google Open Source Security Team. |
| 90 | + |
| 91 | +Funding for the implementation of PEP 740 was provided by the Google Open |
| 92 | +Source Security Team, and much of the development work on PyPI and related |
| 93 | +tools was performed by [Trail of Bits], with special thanks to contributors |
| 94 | +[William Woodruff] and [Facundo Tuesca]. |
| 95 | + |
| 96 | +Thanks to the the [Sigstore project] for their work popularizing identity-based signing, hosting a public-good transparency log, and continued support of the [Python client for Sigstore]. |
| 97 | + |
| 98 | +Many thanks to [Sviatoslav Sydorenko] as well for his support and ongoing |
| 99 | +maintenence of the [pypa/gh-action-pypi-publish] action, as well his support |
| 100 | +for implementing PEP 740 in the action. |
| 101 | + |
| 102 | +--- |
| 103 | + |
| 104 | +_Dustin Ingram is a maintainer of the Python Package Index._ |
| 105 | + |
| 106 | +[PEP 740]: https://peps.python.org/pep-0740/ |
| 107 | +[Trusted Publishing]: https://docs.pypi.org/trusted-publishers/ |
| 108 | +[deprecation and removal of PGP signatures]: https://blog.pypi.org/posts/2023-05-23-removing-pgp/ |
| 109 | +[pypa/gh-action-pypi-publish]: https://github.com/pypa/gh-action-pypi-publish |
| 110 | +[Attestations: a new generation of signatures on PyPI]: https://blog.trailofbits.com/2024/11/14/attestations-a-new-generation-of-signatures-on-pypi/ |
| 111 | +[Integrity API]: https://docs.pypi.org/api/integrity/ |
| 112 | +[we announced last year]: 2023-04-20-introducing-trusted-publishers.md |
| 113 | +[we found that many signatures were not verifiable]: https://blog.yossarian.net/2023/05/21/PGP-signatures-on-PyPI-worse-than-useless |
| 114 | +[manually generate and publish attestations]: https://docs.pypi.org/attestations/producing-attestations/#the-manual-way |
| 115 | +[Sovereign Tech Agency]: https://www.sovereign.tech/tech/python-package-index |
| 116 | +[is planned]: https://github.com/pypi/warehouse/issues/17001 |
| 117 | +[Trail of Bits]: https://www.trailofbits.com/ |
| 118 | +[William Woodruff]: https://github.com/woodruffw |
| 119 | +[Facundo Tuesca]: https://github.com/facutuesca |
| 120 | +[Sigstore project]: https://www.sigstore.dev/ |
| 121 | +[Python client for Sigstore]: https://pypi.org/project/sigstore/ |
| 122 | +[Sviatoslav Sydorenko]: https://github.com/webknjaz |
0 commit comments