PEP 740 – Index support for digital attestations | peps.python.org
PEP 740 – Index support for digital attestations PEP 740 – Index support for digital attestations Author : William Woodruff <william at yossarian.net>, Facundo Tuesca <facundo.tuesca at trailofbits.com>, Dustin Ingram <di at python.org> Sponsor : Donald Stufft <donald at stufft.io> PEP-Delegate : Donald Stufft <donald at stufft.io> Discussions-To : Discourse thread Status : Final Type : Standards Track Topic : Packaging Created : 08-Jan-2024 Post-History : 02-Jan-2024 , 29-Jan-2024 Resolution : 17-Jul-2024 Table of Contents Abstract Rationale and Motivation Design Considerations Previous Work PGP signatures Wheel signatures Specification Upload endpoint changes Index changes Simple Index JSON-based Simple API Attestation objects Attestation statement and signature generation Provenance objects Changes to provenance objects Attestation verification Security Implications Cryptographic agility in attestations Index trust Recommendations Appendix 1: Example Trusted Publisher Representation Appendix 2: Data models for Transparency Log Entries Appendix 3: Simple JSON API size considerations Appendix 4: Example attestation statement Copyright Important This PEP is a historical document.
The up-to-date, canonical spec, Index hosted attestations , is maintained on the PyPA specs page . × See the PyPA specification update process for how to propose changes. Important This PEP is a historical document. The up-to-date, canonical documentation can now be found at PyPI - Digital Attestations . × See PEP 1 for how to propose changes. Abstract This PEP proposes a collection of changes related to the upload and distribution of digitally signed attestations and metadata used to verify them on a Python package repository, such as PyPI.
These changes have two subcomponents: Changes to the currently unstandardized PyPI upload API, allowing clients to upload digital attestations as attestation objects ; Changes to the HTML and JSON “simple” APIs , allowing clients to retrieve both digital attestations and Trusted Publishing metadata for individual release files as provenance objects . This PEP does not make a policy recommendation around mandatory digital attestations on release uploads or their subsequent verification by installing clients like pip .
Rationale and Motivation Desire for digital signatures on Python packages has been repeatedly expressed by both package maintainers and downstream users: Maintainers wish to demonstrate the integrity and authenticity of their package uploads; Individual downstream users wish to verify package integrity and authenticity without placing additional trust in their index’s honesty; “Bulk” downstream users (such as Operating System distributions) wish to perform similar verifications and potentially re-expose or countersign for their own downstream packaging ecosystems.
This proposal seeks to accommodate each of the above use cases. Additionally, this proposal identifies the following motivations: Verifiable provenance for Python package distributions: many Python packages currently contain unauthenticated provenance metadata, such as URLs for source hosts. A cryptographic attestation format could enable strong authenticated links between these packages and their source hosts, allowing both the index and downstream users to cryptographically verify that a package originates from its claimed source repository.
Raising attacker requirements: an attacker who seeks to take over a Python package can be described along sophistication (unsophisticated to sophisticated) and targeting dimensions (opportunistic to targeted). Digital attestations impose additional sophistication requirements: the attacker must be sufficiently sophisticated to access private signing material (or signing identities). Index verifiability: in the status quo, the only attestation provided by the index is an optional PGP signature per release file (see PGP signatures ).
These signatures are not (and cannot be) checked by the index either for well-formedness or for validity, since the index has no mechanism for identifying the right public key for the signature. This PEP overcomes this limitation by ensuring that provenance objects contain all of the metadata needed by the index to verify an attestation’s validity. This PEP proposes a generic attestation format, containing an attestation statement for signature generation , with the expectation that index providers adopt the format with a suitable source of identity for signature verification, such as Trusted Publishing.
Design Considerations This PEP identifies the following design considerations when evaluating both its own proposed changes and previous work in the same or adjacent areas of Python packaging: Index accessibility: digital attestations for Python packages are ideally retrievable directly from the index itself, as “detached” resources. This both simplifies some compatibility concerns (by avoiding the need to modify the distribution formats themselves) and also simplifies the behavior of potential installing clients (by allowing them to retrieve each attestation before its corresponding package without needing to do streaming decompression).
Verification by the index itself: in addition to enabling verification by installing clients, each digital attestation is ideally verifiable in some form by the index itself. This both increases the overall quality of attestations uploaded to the index (preventing, for example, users from accidentally uploading incorrect or invalid attestations) and also enables UI and UX refinements on the index itself (such as a “provenance” view for each uploaded package).
General applicability: digital attestations should be applicable to any and every package uploaded to the index, regardless of its format (sdist or wheel) or interior contents. Metadata support: this PEP refers to “digital attestations” rather than just “digital signatures” to emphasize the ideal presence of additional metadata within the cryptographic envelope. For example, to prevent domain separation between a distribution’s name and its contents, this PEP uses ‘ Statements ’ from the in-toto project to bind the distribution’s contents (via SHA-256 digest) to its filename.
Previous Work PGP signatures PyPI and other indices have historically supported PGP signatures on uploaded distributions. These could be supplied during upload, and could be retrieved by installing clients via the data-gpg-sig attribute in the PEP 503 API, the gpg-sig key on the PEP 691 API, or via an adjacent .asc -suffixed URL. PGP signature uploads have been disabled on PyPI since May 2023 , after an investigation determined that the majority of signatures (which, themselves, constituted a tiny percentage of overall uploads) could not be associated with a public key or otherwise meaningfully verified.
In their previously supported form on PyPI, PGP signatures satisfied considerations (1) and (3) above but not (2) (owing to the need for external keyservers and key distribution) or (4) (due to PGP signatures typically being constructed over just an input file, without any associated signed metadata). Wheel signatures PEP 427 (and its living PyPA counterpart ) specify the wheel format . This format includes accommodations for digital signatures embedded directly into the wheel, in either JWS or S/MIME format.
These signatures are specified over a PEP 376 RECORD, which is modified to include a cryptographic digest for each recorded file in the wheel. While wheel signatures are fully specified, they do not appear to be broadly used; the official wheel tooling deprecated signature generation and verification support in 0.32.0 , which was released in 2018. Additionally, wheel signatures do not satisfy any of the above considerations (due to the “attached” nature of the signatures, non-verifiability on the index itself, and support for wheels only).
Specification Upload endpoint changes The curr
The rest of this page is on the live site.