設計考量

本 PEP 在評估自身提案與 Python 封裝領域中相關先前工作時，確立了以下設計考量：

1. 索引的可存取性：Python 套件的數位認證理想情況下應能作為「分離」資源，直接從索引本身檢索。

   這不僅簡化了相容性問題（無需修改分發格式本身），也簡化了潛在安裝用戶端的行為（允許它們在解壓縮之前檢索每個認證，而無需進行串流解壓縮）。

2. 索引本身的驗證：除了支援安裝用戶端進行驗證外，每個數位認證「理想上」應能以某種形式由索引本身進行驗證。

   這不僅提高了上傳至索引的認證整體品質（例如防止使用者意外上傳錯誤或無效的認證），也使索引本身的 UI 與 UX 能進一步優化（例如為每個上傳的套件提供「來源證明」檢視）。

3. 通用適用性：數位認證應適用於上傳至索引的「任何」套件，無論其格式（sdist 或 wheel）或內部內容為何。
4. 中繼資料支援：本 PEP 使用「數位認證」而非僅僅是「數位簽名」，旨在強調在加密包中包含額外中繼資料的理想性。

   例如，為了防止分發名稱與其內容之間的領域分離，本 PEP 使用來自 in-toto 專案的「聲明 (Statements)」，將分發的內容（透過 SHA-256 摘要）綁定至其檔名。

先前的工作

上傳端點變更

目前的上傳 API 尚未標準化。然而，我們對其提出以下變更：

• 除了目前頂層的 content 與 gpg_signature 欄位外，索引**應 (SHALL)** 接受 attestations 作為額外的多部分 (multipart) 表單欄位。
• 新的 attestations 欄位**應 (SHALL)** 為 JSON 陣列。
• attestations 陣列**應 (SHALL)** 包含一或多個項目，每個項目為代表個別認證的 JSON 物件。
• 每個認證物件**必須 (MUST)** 能由索引進行驗證。若索引無法驗證 attestations 中的任何認證，則**必須 (MUST)** 拒絕該次上傳。認證物件的格式定義於認證物件，而認證驗證流程定義於認證驗證。

索引變更

認證物件 (Attestation objects)

認證物件是一個具有多個必要鍵的 JSON 物件；只要提供了所有明確列出的鍵，應用程式或簽署者可以包含額外的鍵。認證物件的必要佈局以下方虛擬碼表示。

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

transparency_entries 中每個物件的完整資料模型提供於附錄 2：透明度記錄條目的資料模型。認證物件**應 (SHOULD)** 包含一或多個透明度記錄條目，並**可 (MAY)** 為其他已簽署時間來源包含額外鍵（例如 RFC 3161 時間戳記授權單位或 Roughtime 伺服器）。

認證物件具有版本編號；本 PEP 指定版本為 1。每個版本均綁定至單一加密套件，以最大限度地減少不必要的加密靈活性。在第 1 版中，套件如下：

• 憑證指定為 X.509 憑證，並符合 RFC 5280 中的設定檔。
• 訊息簽名演算法為 ECDSA，公鑰使用 P-256 曲線，加密摘要函數為 SHA-256。

未來的 PEP 可能會透過選擇新的版本編號來變更此套件（以及認證物件的整體形狀）。

來源證明物件 (Provenance objects)

索引將提供已上傳的認證以及以 JSON 序列化物件形式提供的中繼資料，協助進行驗證。

這些「來源證明物件」將透過上述 Simple Index 與 JSON-based Simple API 提供，並具有以下佈局：

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

或以虛擬碼表示：

@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 為 1。如同認證物件，來源證明物件具有版本控制，且本 PEP 僅定義第 1 版。
• attestation_bundles 為**必要** JSON 陣列，包含一或多個認證「套件 (bundles)」。每個套件對應一個簽署身分（如受信任發佈身分），並包含一或多個認證物件。如 Publisher 模型中所述，每個 AttestationBundle.publisher 物件皆為其受信任發佈者所特有，但必須至少包含：
  • 一個 kind 鍵，其**必須 (MUST)** 為唯一識別受信任發佈者類型的 JSON 字串。
  • 一個 claims 鍵，其**必須 (MUST)** 為包含索引在驗證受信任發佈者期間所保留任何情境特定聲明的 JSON 物件。

  發佈者物件中的所有其他鍵均為發佈者專用。發佈者物件的完整說明範例提供於附錄 1：受信任發佈者表示範例。

  認證物件的每個陣列皆是上傳時透過 attestations 欄位所提供之 attestations 陣列的超集，詳見上傳端點變更與對來源證明物件的變更。

認證驗證

針對分發檔案驗證認證物件需要驗證以下各項：

• version 為 1。驗證程式**必須 (MUST)** 拒絕任何其他版本。
• verification_material.certificate 為有效的簽署憑證，由「事先」信任的權威機構簽發（例如驗證用戶端中已存在的信任根）。
• verification_material.certificate 識別出適當的簽署主體，例如發佈該套件的受信任發佈者機器身分。
• envelope.statement 為有效的 in-toto v1 聲明，其主體與摘要**必須 (MUST)** 與分發檔案的檔名與內容相符。針對分發檔案的檔名，匹配**必須 (MUST)** 透過使用適當的原始碼分發或 wheel 檔名格式進行解析，因為聲明的主體可能是等效但經過正規化的。
• envelope.signature 為對應至 verification_material.certificate 之 envelope.statement 的有效簽名，透過 v1 DSSE 簽名協定重組。

除了上述必要步驟外，驗證程式**可 (MAY)** 額外基於政策驗證 verification_material.transparency_entries，例如要求至少一個透明度記錄條目或滿足一定閾值的條目。驗證透明度記錄時，驗證程式**必須 (MUST)** 確認每個條目的包含時間皆位於簽署憑證的有效期限內。

認證中的加密靈活性

演算法靈活性是加密方案中常見的可利用漏洞來源。本 PEP 透過以下兩種方式限制演算法靈活性：

• 所有演算法均指定在單一套件中，而非參數的幾何集合。這使得攻擊者不可能（例如）選擇強大的簽名演算法搭配脆弱的雜湊函數，從而損害整體方案。
• 認證物件具有版本控制，且僅能包含該版本指定的加密套件。若未來某個特定套件被認為不安全，用戶端可選擇全面拒絕或限定驗證包含該套件的認證。

索引信任

本 PEP **不會**增加（或減少）對索引本身的信任：索引依然被有效地信任以誠實地傳遞未經修改的套件分發，因為有能力修改套件內容的不誠實索引同樣可以不誠實地修改或省略套件認證。因此，本 PEP 對索引信任的預設與早期機制（如 PGP 與 wheel 簽名）所隱含的預設相同。

本 PEP 不排除未來索引信任機制的發展，例如 PEP 458 及/或 PEP 480。