Design Considerations

This PEP identifies the following design considerations when evaluatingboth its own proposed changes and previous work in the same or adjacentareas of Python packaging:

1. Index accessibility: digital attestations for Python packagesare ideally retrievable directly from the index itself, as “detached”resources.

   This both simplifies some compatibility concerns (by avoidingthe need to modify the distribution formats themselves) and also simplifiesthe behavior of potential installing clients (by allowing them toretrieve each attestation before its corresponding package without needingto do streaming decompression).

2. Verification by the index itself: in addition to enabling verificationby installing clients, each digital attestation isideally verifiablein some form by the index itself.

   This both increases the overall qualityof attestations uploaded to the index (preventing, for example, usersfrom accidentally uploading incorrect or invalid attestations) and alsoenables UI and UX refinements on the index itself (such as a “provenance”view for each uploaded package).

3. General applicability: digital attestations should be applicable toany and every package uploaded to the index, regardless of its format(sdist or wheel) or interior contents.
4. Metadata support: this PEP refers to “digital attestations” rather thanjust “digital signatures” to emphasize the ideal presence of additionalmetadata within the cryptographic envelope.

   For example, to prevent domain separation between a distribution’s name andits contents, this PEP uses ‘Statements’from thein-toto project to bind the distribution’scontents (via SHA-256 digest) to its filename.

Previous Work

Upload endpoint changes

The current upload API is not standardized. However, we propose the followingchanges to it:

• In addition to the current top-levelcontent andgpg_signature fields,the indexSHALL acceptattestations as an additional multipart formfield.
• The newattestations fieldSHALL be a JSON array.
• Theattestations arraySHALL have one or more items, each a JSON objectrepresenting an individual attestation.
• Each attestation objectMUST be verifiable by the index. If the index failsto verify any attestation inattestations, itMUST reject the upload.The format of attestation objects is defined underAttestation objectsand the process for verifying attestations is defined underAttestation verification.

Index changes

Attestation objects

An attestation object is a JSON object with several required keys; applicationsor signers may include additional keys so long as all explicitlylisted keys are provided. The required layout of an attestationobject is provided as pseudocode below.

@dataclassclassAttestation:version:Literal[1]"""    The attestation object's version, which is always 1.    """verification_material:VerificationMaterial"""    Cryptographic materials used to verify `envelope`.    """envelope:Envelope"""    The enveloped attestation statement and signature.    """@dataclassclassEnvelope:statement:bytes"""    The attestation statement.    This is represented as opaque bytes on the wire (encoded as base64),    but it MUST be an JSON in-toto v1 Statement.    """signature:bytes"""    A signature for the above statement, encoded as base64.    """@dataclassclassVerificationMaterial:certificate:str"""    The signing certificate, as `base64(DER(cert))`.    """transparency_entries:list[object]"""    One or more transparency log entries for this attestation's signature    and certificate.    """

A full data model for each object intransparency_entries is provided inAppendix 2: Data models for Transparency Log Entries. Attestation objectsSHOULD include one or moretransparency log entries, andMAY include additional keys for othersources of signed time (such as anRFC 3161 Time Stamping Authority or aRoughtime server).

Attestation objects are versioned; this PEP specifies version 1. Each versionis tied to a single cryptographic suite to minimize unnecessary cryptographicagility. In version 1, the suite is as follows:

• Certificates are specified as X.509 certificates, and comply with theprofile inRFC 5280.
• The message signature algorithm is ECDSA, with the P-256 curve for public keysand SHA-256 as the cryptographic digest function.

Future PEPs may change this suite (and the overall shape of the attestationobject) by selecting a new version number.

Provenance objects

The index will serve uploaded attestations along with metadata that can assistin verifying them in the form of JSON serialized objects.

Theseprovenance objects will be available via both the Simple Indexand JSON-based Simple API as described above, and will have the following layout:

{"version":1,"attestation_bundles":[{"publisher":{"kind":"important-ci-service","claims":{},"vendor-property":"foo","another-property":123},"attestations":[{/* attestation 1 ... */},{/* attestation 2 ... */}]}]}

or, as pseudocode:

@dataclassclassPublisher:kind:string"""    The kind of Trusted Publisher.    """claims:object|None"""    Any context-specific claims retained by the index during Trusted Publisher    authentication.    """_rest:object"""    Each publisher object is open-ended, meaning that it MAY contain additional    fields beyond the ones specified explicitly above. This field signals that,    but is not itself present.    """@dataclassclassAttestationBundle:publisher:Publisher"""    The publisher associated with this set of attestations.    """attestations:list[Attestation]"""    The set of attestations included in this bundle.    """@dataclassclassProvenance:version:Literal[1]"""    The provenance object's version, which is always 1.    """attestation_bundles:list[AttestationBundle]"""    One or more attestation "bundles".    """

• version is1. Like attestation objects, provenance objects areversioned, and this PEP only defines version1.
• attestation_bundles is arequired JSON array, containing oneor more “bundles” of attestations. Each bundle corresponds to asigning identity (such as a Trusted Publishing identity), and containsone or more attestation objects.

  As noted in thePublisher model,eachAttestationBundle.publisher object is specific to its Trusted Publisherbut must include at minimum:

  • Akind key, whichMUST be a JSON string that uniquely identifies thekind of Trusted Publisher.
  • Aclaims key, whichMUST be a JSON object containing any context-specificclaims retained by the index during Trusted Publisher authentication.

  All other keys in the publisher object are publisher-specific. A fullillustrative example of a publisher object is provided inAppendix 1: Example Trusted Publisher Representation.

  Each array of attestation objects is a superset of theattestationsarray supplied by the uploaded through theattestations field at uploadtime, as described inUpload endpoint changes andChanges to provenance objects.

Attestation verification

Verifying an attestation object against a distribution file requires verification of each of thefollowing:

• version is1. The verifierMUST reject any other version.
• verification_material.certificate is a valid signing certificate, asissued by ana priori trusted authority (such as a root of trust alreadypresent within the verifying client).
• verification_material.certificate identifies an appropriate signingsubject, such as the machine identity of the Trusted Publisher that publishedthe package.
• envelope.statement is a valid in-toto v1 Statement, with a subjectand digest thatMUST match the distribution’s filename and contents.For the distribution’s filename, matchingMUST be performed by parsingusing the appropriate source distribution or wheel filename format, asthe statement’s subject may be equivalent but normalized.
• envelope.signature is a valid signature forenvelope.statementcorresponding toverification_material.certificate,as reconstituted via thev1 DSSE signature protocol.

In addition to the above required steps, a verifierMAY additionally verifyverification_material.transparency_entries on a policy basis, e.g. requiringat least one transparency log entry or a threshold of entries. When verifyingtransparency entries, the verifierMUST confirm that the inclusion time foreach entry lies within the signing certificate’s validity period.

Cryptographic agility in attestations

Algorithmic agility is a common source of exploitable vulnerabilitiesin cryptographic schemes. This PEP limits algorithmic agility in two ways:

• All algorithms are specified in a single suite, rather than a geometriccollection of parameters. This makes it impossible (for example) for anattacker to select a strong signature algorithm with a weak hash function,compromising the scheme as a whole.
• Attestation objects are versioned, and may only contain the algorithmicsuite specified for their version. If a specific suiteis considered insecure in the future, clients may choose to blanket rejector qualify verifications of attestations that contain that suite.

Index trust

This PEP doesnot increase (or decrease) trust in the index itself:the index is still effectively trusted to honestly deliver unmodified packagedistributions, since a dishonest index capable of modifying packagecontents could also dishonestly modify or omit package attestations.As a result, this PEP’s presumption of index trust is equivalent to theunstated presumption with earlier mechanisms, like PGP and wheel signatures.

This PEP does not preclude or exclude future index trust mechanisms, suchasPEP 458 and/orPEP 480.