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;
• Changes to the PEP 503 and PEP 691 “simple” APIs, allowing clients to retrieve both digital attestations and Trusted Publishing metadata for individual release files.

This PEP does not recommend a specific digital attestation format, nor does it 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). They also impose additional targeting requirements: the release consistency requirement (mentioned below) means that the attacker cannot upload any attestation, but only one of a type already seen for a particular release. In the future, this could be further “ratcheted” down by allowing project maintainers to disable releases without attestations entirely.

• Release consistency: 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 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.

  Additionally, the index does not have an “all or none” requirement for PGP signatures, meaning that there is no consistency requirement between distributions within a release (and that maintainers may accidentally forget to upload signatures when adding additional release distributions).

While this PEP does not recommend a specific digital attestation format, it does recognize the utility of Trusted Publishing as a pre-existing, “zero-configuration” source of strong provenance for Python packages. Consequently this PEP includes a proposed scheme for exposing each release file’s Trusted Publisher metadata, with the expectation that a future digital attestation format will likely make use of it.

Specification

{
    "publisher": {
      "type": "important-ci-service",
      "claims": {},
      "vendor-property": "foo",
      "another-property": 123
    },
    "attestations": {
      "some-attestation": {/* ... */},
      "another-attestation": {/* ... */}
    }
}

Security Implications

This PEP is “mechanical” in nature; it provides only the plumbing for future digital attestations on package indices, without specifying their concrete cryptographic details.

As such, we do not identify any positive or negative security implications for this PEP.

Recommendations

This PEP does not recommend specific attestation formats. It does, however, make the following recommendations to package indices seeking to create new or implement pre-existing attestation formats:

1. Consult the living PyPA specifications first, and determine if any currently defined attestation formats suit your purpose.
2. If no suitable attestation format is defined under the PyPA specifications, consider submitting it to the PyPA specifications for longevity and reuse purposes.

When designing a new attestation format, we make the following recommendations:

1. Pick a short, but unique name for your attestation format; this name will serve as the attestation’s identifier in the upload and index APIs.

   When appropriate for an attestation format, we recommend using : as a domain separator. For example, an attestation format that provides publish provenance using Sigstore might have the name sigstore:publish.

2. Prefer parsimony in your format: avoid optional fields and functionality, avoid unnecessary cryptographic agility and message malleability, and ensure that verifying the attestation communicates something meaningful beyond a basic integrity check (since the index itself already supplies cryptographic digests for this purpose).

Appendix 1: Example Uploaded Attestations

This appendix provides a fictional example of the attestations field submitted on file upload, with two fictional attestations (publish and timestamp):

{
    "publish": {
        "mediaType": "application/vnd.dev.sigstore.bundle+json;version=0.2",
        "verificationMaterial": { /* omitted for brevity */ },
        "messageSignature": {
            "messageDigest": {
                "algorithm": "some-hash-algo",
                "digest": "digest-here"
            },
            "signature": "signature-here"
        }
    },
    "timestamp": {
        "cms": "some-long-blob-here"
    }
}

The payloads of these fictional attestations are purely illustrative.

Appendix 2: Example Trusted Publisher Representation

This appendix provides a fictional example of a publisher key within a PEP 691 project.files[].provenance listing:

"publisher": {
    "type": "GitHub",
    "claims": {
        "ref": "refs/tags/v1.0.0",
        "sha": "da39a3ee5e6b4b0d3255bfef95601890afd80709"
    },
    "repository_name": "HolyGrail",
    "repository_owner": "octocat",
    "repository_owner_id": "1",
    "workflow_filename": "publish.yml",
    "environment": null
}

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.