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:

1. 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).

2. 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).

3. 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.
4. 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

Upload endpoint changes

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

• In addition to the current top-level content and gpg_signature fields, the index SHALL accept attestations as an additional multipart form field.
• The new attestations field SHALL be a JSON array.
• The attestations array SHALL have one or more items, each a JSON object representing an individual attestation.
• Each attestation object MUST be verifiable by the index. If the index fails to verify any attestation in attestations, it MUST reject the upload. The format of attestation objects is defined under Attestation objects and the process for verifying attestations is defined under Attestation verification.

Index changes

Attestation objects

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

@dataclass
class Attestation:
    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.
    """


@dataclass
class Envelope:
    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.
    """

@dataclass
class VerificationMaterial:
    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 in transparency_entries is provided in Appendix 2: Data models for Transparency Log Entries. Attestation objects SHOULD include one or more transparency log entries, and MAY include additional keys for other sources of signed time (such as an RFC 3161 Time Stamping Authority or a Roughtime server).

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

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

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

Provenance objects

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

These provenance objects will be available via both the Simple Index and 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:

@dataclass
class Publisher:
    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.
    """

@dataclass
class AttestationBundle:
    publisher: Publisher
    """
    The publisher associated with this set of attestations.
    """

    attestations: list[Attestation]
    """
    The set of attestations included in this bundle.
    """

@dataclass
class Provenance:
    version: Literal[1]
    """
    The provenance object's version, which is always 1.
    """

    attestation_bundles: list[AttestationBundle]
    """
    One or more attestation "bundles".
    """

• version is 1. Like attestation objects, provenance objects are versioned, and this PEP only defines version 1.
• attestation_bundles is a required JSON array, containing one or more “bundles” of attestations. Each bundle corresponds to a signing identity (such as a Trusted Publishing identity), and contains one or more attestation objects.

  As noted in the Publisher model, each AttestationBundle.publisher object is specific to its Trusted Publisher but must include at minimum:

  • A kind key, which MUST be a JSON string that uniquely identifies the kind of Trusted Publisher.
  • A claims key, which MUST be a JSON object containing any context-specific claims retained by the index during Trusted Publisher authentication.

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

  Each array of attestation objects is a superset of the attestations array supplied by the uploaded through the attestations field at upload time, as described in Upload endpoint changes and Changes to provenance objects.

Attestation verification

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

• version is 1. The verifier MUST reject any other version.
• verification_material.certificate is a valid signing certificate, as issued by an a priori trusted authority (such as a root of trust already present within the verifying client).
• verification_material.certificate identifies an appropriate signing subject, such as the machine identity of the Trusted Publisher that published the package.
• envelope.statement is a valid in-toto v1 Statement, with a subject and digest that MUST match the distribution’s filename and contents. For the distribution’s filename, matching MUST be performed by parsing using the appropriate source distribution or wheel filename format, as the statement’s subject may be equivalent but normalized.
• envelope.signature is a valid signature for envelope.statement corresponding to verification_material.certificate, as reconstituted via the v1 DSSE signature protocol.

In addition to the above required steps, a verifier MAY additionally verify verification_material.transparency_entries on a policy basis, e.g. requiring at least one transparency log entry or a threshold of entries. When verifying transparency entries, the verifier MUST confirm that the inclusion time for each entry lies within the signing certificate’s validity period.

Cryptographic agility in attestations

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

• All algorithms are specified in a single suite, rather than a geometric collection of parameters. This makes it impossible (for example) for an attacker 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 algorithmic suite specified for their version. If a specific suite is considered insecure in the future, clients may choose to blanket reject or qualify verifications of attestations that contain that suite.

Index trust

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

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