Designüberlegungen

Diese PEP identifiziert die folgenden Design-Erwägungen bei der Bewertung sowohl ihrer eigenen vorgeschlagenen Änderungen als auch früherer Arbeiten in denselben oder angrenzenden Bereichen der Python-Paketierung:

1. Index-Zugänglichkeit: Digitale Bestätigungen für Python-Pakete sind idealerweise direkt aus dem Index selbst als "abgelöste" Ressourcen abrufbar.

   Dies vereinfacht einige Kompatibilitätsprobleme (indem die Notwendigkeit, die Distributionsformate selbst zu ändern, vermieden wird) und vereinfacht auch das Verhalten potenzieller installierender Clients (indem ihnen ermöglicht wird, jede Bestätigung vor dem entsprechenden Paket abzurufen, ohne Entpacken-Streaming zu benötigen).

2. Verifizierung durch den Index selbst: Zusätzlich zur Ermöglichung der Verifizierung durch installierende Clients ist jede digitale Bestätigung *idealerweise* in irgendeiner Form vom Index selbst verifizierbar.

   Dies erhöht sowohl die Gesamtqualität der an den Index hochgeladenen Bestätigungen (z. B. verhindert es, dass Benutzer versehentlich falsche oder ungültige Bestätigungen hochladen) als auch ermöglicht es UI- und UX-Verbesserungen auf dem Index selbst (wie eine "Herkunfts"-Ansicht für jedes hochgeladene Paket).

3. Allgemeine Anwendbarkeit: Digitale Bestätigungen sollten für *jedes und jedes* Paket, das an den Index hochgeladen wird, unabhängig von seinem Format (sdist oder wheel) oder seinem internen Inhalt anwendbar sein.
4. Metadatenunterstützung: Diese PEP bezieht sich auf "digitale Bestätigungen" und nicht nur auf "digitale Signaturen", um die ideale Präsenz zusätzlicher Metadaten innerhalb der kryptografischen Hülle zu betonen.

   Um beispielsweise die Domain-Trennung zwischen dem Namen einer Distribution und ihrem Inhalt zu verhindern, verwendet diese PEP "Statements" aus dem in-toto Projekt, um den Inhalt der Distribution (über den SHA-256-Digest) an ihren Dateinamen zu binden.

Vorangegangene Arbeiten

Änderungen am Upload-Endpunkt

Die aktuelle Upload-API ist nicht standardisiert. Wir schlagen jedoch die folgenden Änderungen vor:

• Zusätzlich zu den aktuellen Top-Level-Feldern content und gpg_signature soll der Index ein zusätzliches Multipart-Formularfeld namens attestations akzeptieren.
• Das neue Feld attestations soll ein JSON-Array sein.
• Das Array attestations soll ein oder mehrere Elemente enthalten, von denen jedes ein JSON-Objekt darstellt, das eine einzelne Bestätigung enthält.
• Jedes Bestätigungsobjekt MUSS vom Index verifizierbar sein. Wenn der Index eine Bestätigung in attestations nicht verifizieren kann, MUSS der Upload abgelehnt werden. Das Format von Bestätigungsobjekten ist unter Bestätigungsobjekte definiert und der Prozess zur Verifizierung von Bestätigungen ist unter Bestätigungsprüfung definiert.

Indexänderungen

Bestätigungsobjekte

Ein Bestätigungsobjekt ist ein JSON-Objekt mit mehreren erforderlichen Schlüsseln; Anwendungen oder Unterzeichner können zusätzliche Schlüssel einfügen, solange alle explizit aufgeführten Schlüssel vorhanden sind. Das erforderliche Layout eines Bestätigungsobjekts ist unten als Pseudocode angegeben.

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

Ein vollständiges Datenmodell für jedes Objekt in transparency_entries ist in Anhang 2: Datenmodelle für Transparency Log Entries enthalten. Bestätigungsobjekte sollten ein oder mehrere Transparency Log Entries enthalten und können zusätzliche Schlüssel für andere Quellen signierter Zeit enthalten (wie eine RFC 3161 Time Stamping Authority oder einen Roughtime Server).

Bestätigungsobjekte sind versioniert; diese PEP spezifiziert Version 1. Jede Version ist an eine einzige kryptografische Suite gebunden, um unnötige kryptografische Agilität zu minimieren. In Version 1 ist die Suite wie folgt:

• Zertifikate werden als X.509-Zertifikate spezifiziert und entsprechen dem Profil in RFC 5280.
• Der Nachrichten-Signatur-Algorithmus ist ECDSA, mit der P-256-Kurve für öffentliche Schlüssel und SHA-256 als kryptografische Digest-Funktion.

Zukünftige PEPs können diese Suite (und die Gesamtform des Bestätigungsobjekts) durch Auswahl einer neuen Versionsnummer ändern.

Herkunftsobjekte

Der Index stellt hochgeladene Bestätigungen zusammen mit Metadaten, die bei deren Überprüfung helfen können, in Form von JSON-serialisierten Objekten bereit.

Diese *Herkunftsobjekte* sind über die Simple Index- und die JSON-basierte Simple API wie oben beschrieben verfügbar und haben das folgende Layout:

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

oder, als 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 ist 1. Wie Bestätigungsobjekte sind auch Herkunftsobjekte versioniert, und diese PEP definiert nur Version 1.
• attestation_bundles ist ein erforderliches JSON-Array, das ein oder mehrere "Bundles" von Bestätigungen enthält. Jedes Bundle entspricht einer Signaturidentität (wie z. B. einer Trusted Publishing-Identität) und enthält ein oder mehrere Bestätigungsobjekte.

  Wie im Publisher-Modell angegeben, ist jedes AttestationBundle.publisher-Objekt spezifisch für seinen Trusted Publisher, muss aber mindestens Folgendes enthalten:

  • Einen Schlüssel kind, der eine JSON-Zeichenkette sein muss, die die Art des Trusted Publishers eindeutig identifiziert.
  • Einen Schlüssel claims, der ein JSON-Objekt sein muss, das alle kontextspezifischen Ansprüche enthält, die der Index während der Authentifizierung des Trusted Publishers gespeichert hat.

  Alle anderen Schlüssel im Publisher-Objekt sind vom Publisher spezifisch. Ein vollständiges illustratives Beispiel eines Publisher-Objekts ist in Anhang 1: Beispiel für die Darstellung vertrauenswürdiger Publisher enthalten.

  Jedes Array von Bestätigungsobjekten ist eine Obermenge des Arrays attestations, das beim Upload über das Feld attestations bereitgestellt wurde, wie in Änderungen am Upload-Endpunkt und Änderungen an Herkunftsobjekten beschrieben.

Bestätigungsprüfung

Die Verifizierung eines Bestätigungsobjekts gegen eine Distributionsdatei erfordert die Verifizierung jeder der folgenden Elemente:

• version ist 1. Der Verifier muss jede andere Version ablehnen.
• verification_material.certificate ist ein gültiges Signaturzertifikat, wie es von einer *a priori* vertrauenswürdigen Autorität ausgestellt wurde (wie z. B. einer Root of Trust, die bereits innerhalb des verifizierenden Clients vorhanden ist).
• verification_material.certificate identifiziert ein geeignetes Signatursubjekt, wie z. B. die Maschinenidentität des Trusted Publishers, der das Paket veröffentlicht hat.
• envelope.statement ist ein gültiges in-toto v1 Statement, mit einem Subjekt und Digest, die mit dem Dateinamen und Inhalt der Distribution übereinstimmen müssen. Für den Dateinamen der Distribution muss die Übereinstimmung durch Parsen mit dem entsprechenden Format für Source Distribution- oder Wheel Distribution-Dateinamen erfolgen, da das Subjekt der Erklärung gleichwertig, aber normalisiert sein kann.
• envelope.signature ist eine gültige Signatur für envelope.statement, die zu verification_material.certificate passt, wie sie über das v1 DSSE-Signaturprotokoll rekonstruiert wurde.

Zusätzlich zu den oben genannten erforderlichen Schritten kann ein Verifier zusätzlich verification_material.transparency_entries auf Policy-Basis überprüfen, z. B. indem er mindestens einen Transparency Log Entry oder eine Schwelle von Einträgen verlangt. Bei der Überprüfung von Transparenzeinträgen muss der Verifier bestätigen, dass die Aufnahmezeit für jeden Eintrag innerhalb des Gültigkeitszeitraums des Signaturzertifikats liegt.

Kryptografische Agilität in Bestätigungen

Algorithmus-Agilität ist eine häufige Quelle für ausnutzbare Schwachstellen in kryptografischen Schemata. Diese PEP schränkt die Algorithmus-Agilität auf zwei Arten ein:

• Alle Algorithmen sind in einer einzigen Suite spezifiziert, anstatt einer geometrischen Sammlung von Parametern. Dies macht es beispielsweise unmöglich, dass ein Angreifer einen starken Signaturalgorithmus mit einer schwachen Hash-Funktion wählt und damit das gesamte Schema kompromittiert.
• Bestätigungsobjekte sind versioniert und dürfen nur die für ihre Version spezifizierte algorithmische Suite enthalten. Wenn eine bestimmte Suite zukünftig als unsicher gilt, können Clients wählen, Bestätigungen, die diese Suite enthalten, pauschal abzulehnen oder einzuschränken.

Indexvertrauen

Diese PEP erhöht (oder verringert) das Vertrauen in den Index selbst nicht: Der Index wird immer noch effektiv als vertrauenswürdig angesehen, um unveränderte Paketdistributionen ehrlich zu liefern, da ein unehrlicher Index, der Paketdateien modifizieren könnte, auch Paketbestätigungen unehrlich modifizieren oder weglassen könnte. Infolgedessen ist die Annahme des Indexvertrauens dieser PEP gleichwertig mit der unausgesprochenen Annahme bei früheren Mechanismen wie PGP- und Wheel-Signaturen.

Diese PEP schließt zukünftige Index-Vertrauensmechanismen wie PEP 458 und/oder PEP 480 nicht aus oder schließt sie aus.