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 proposes that digital attestations be performed over HASH(name || HASH(contents)) rather than just HASH(contents).

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 `message_signature`.
    """

    message_signature: str
    """
    The attestation's signature, as `base64(raw-sig)`, where `raw-sig`
    is the raw bytes of the signing operation over the attestation payload.
    """

@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.

@dataclass
class AttestationPayload:
    distribution: str
    """
    The file name of the Python package distribution.
    """

    digest: str
    """
    The SHA-256 digest of the distribution's contents, as a hexadecimal string.
    """

<a href="https://example.com/...">sampleproject-1.2.0-py2.py3-none-any.whl</a><br/>

def build_payload(dist: Path) -> AttestationPayload:
    return AttestationPayload(
      distribution=dist.name,
      digest=sha256(dist.read_bytes()).hexdigest,
    )

attestation_payload = build_payload("sampleproject-1.2.0-py2.py3-none-any.whl")

# canonical_json is a fictitious module that performs RFC 8785 canonical
# JSON serialization.
encoded_payload = canonical_json.dumps(asdict(attestation_payload))

raw_signature = signing_key.sign(encoded_payload, ECDSA(SHA2_256()))
message_signature = b64encode(raw_signature)

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 PEP 503 Simple Index and PEP 691 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 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.
• message_signature can be verified by verification_material.certificate, using the reconstructed attestation payload as the cleartext input. The verifier MUST reconstruct the attestation payload itself.

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.

Flexible attestations

This PEP specifies a fixed attestation payload (defined in Attestation payload and signature generation), binding the contents of each uploaded file to its public name on the index. This payload format is fixed and inflexible to ease implementation, and to minimize additional mechanical changes to the index itself (e.g., needing to store and service detached attestation documents).

This PEP does not preclude or exclude future more flexible attestation payload formats, such as ones built on in-toto.