设计考虑

本 PEP 在评估其自身提出的变更以及 Python 打包相同或相邻领域的先前工作时，确定了以下设计考虑：

1. 索引可访问性：Python 包的数字证明理想情况下可以直接从索引本身作为“分离”资源检索。

   这既简化了一些兼容性问题（通过避免修改分发格式本身的需求），也简化了潜在安装客户端的行为（通过允许它们在相应的包之前检索每个证明，而无需进行流式解压）。

2. 索引本身的验证：除了启用安装客户端的验证外，每个数字证明 理想情况下 可以由索引本身以某种形式进行验证。

   这既提高了上传到索引的证明的整体质量（例如，防止用户意外上传不正确或无效的证明），也使索引本身能够进行 UI 和 UX 改进（例如，每个上传包的“来源”视图）。

3. 普遍适用性：数字证明应适用于上传到索引的 任何 包，无论其格式（sdist 或 wheel）或内部内容如何。
4. 元数据支持：本 PEP 提到“数字证明”而不是仅仅“数字签名”，以强调加密信封中理想情况下存在的附加元数据。

   例如，为了防止分发名称与其内容之间的域分离，本 PEP 使用 in-toto 项目的“声明”将分发内容（通过 SHA-256 摘要）绑定到其文件名。

前期工作

上传端点变更

当前的上传 API 未标准化。但是，我们建议对其进行以下更改：

• 除了当前的顶级 content 和 gpg_signature 字段外，索引 应 接受 attestations 作为附加的多部分表单字段。
• 新的 attestations 字段 应 是一个 JSON 数组。
• attestations 数组 应 包含一个或多个项目，每个项目都是一个表示单个证明的 JSON 对象。
• 每个证明对象 必须 可由索引验证。如果索引未能验证 attestations 中的任何证明，它 必须 拒绝上传。证明对象的格式在证明对象中定义，验证证明的过程在证明验证中定义。

索引变更

证明对象

证明对象是一个具有多个必需键的 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：透明日志条目的数据模型中提供。证明对象 应 包含一个或多个透明日志条目，并且 可以 包含其他签名的额外键（例如 RFC 3161 时间戳机构或 Roughtime 服务器）。

证明对象是版本化的；本 PEP 指定版本 1。每个版本都绑定到一个单一的加密套件，以最大限度地减少不必要的加密灵活性。在版本 1 中，套件如下：

• 证书指定为 X.509 证书，并符合 RFC 5280 中的配置文件。
• 消息签名算法是 ECDSA，公钥使用 P-256 曲线，SHA-256 作为加密摘要函数。

未来的 PEP 可以通过选择新的版本号来更改此套件（以及证明对象的整体形状）。

来源对象

索引将提供上传的证明以及可以帮助验证它们的元数据，以 JSON 序列化对象的形式。

这些 来源对象 将通过简单索引和基于 JSON 的简单 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 数组，包含一个或多个证明“包”。每个包对应一个签名身份（例如可信发布身份），并包含一个或多个证明对象。

  如 Publisher 模型中所述，每个 AttestationBundle.publisher 对象都特定于其可信发布者，但必须至少包含：

  • 一个 kind 键，它 必须 是一个唯一标识可信发布者类型的 JSON 字符串。
  • 一个 claims 键，它 必须 是一个 JSON 对象，包含在可信发布者身份验证期间由索引保留的任何特定上下文的声明。

  发布者对象中的所有其他键都是发布者特定的。发布者对象的完整示例在附录1：可信发布者表示示例中提供。

  证明对象数组是上传时通过 attestations 字段提供的 attestations 数组的超集，如上传端点变更和来源对象的变更中所述。

证明验证

针对分发文件验证证明对象需要验证以下各项：

• version 为 1。验证器 必须 拒绝任何其他版本。
• verification_material.certificate 是一个有效的签名证书，由 预先 信任的机构（例如验证客户端中已存在的信任根）颁发。
• verification_material.certificate 标识了适当的签名主题，例如发布该包的可信发布者的机器身份。
• envelope.statement 是一个有效的 in-toto v1 Statement，其主题和摘要 必须 与分发的文件名和内容匹配。对于分发的文件名，匹配 必须 通过使用适当的源分发或 wheel 文件名格式进行解析来执行，因为声明的主题可能等效但已规范化。
• envelope.signature 是 envelope.statement 的有效签名，对应于 verification_material.certificate，通过 v1 DSSE 签名协议重新构建。

除了上述必需步骤外，验证器 可以 根据策略额外验证 verification_material.transparency_entries，例如要求至少一个透明日志条目或达到某个条目阈值。在验证透明条目时，验证器 必须 确认每个条目的包含时间落在签名证书的有效期内。

证明中的加密灵活性

算法灵活性是密码方案中可利用漏洞的常见来源。本 PEP 从两个方面限制了算法灵活性：

• 所有算法都在一个套件中指定，而不是一组几何参数。这使得攻击者无法（例如）选择一个具有弱哈希函数的强签名算法，从而损害整个方案。
• 证明对象是版本化的，并且只能包含为其版本指定的算法套件。如果将来某个特定套件被认为不安全，客户端可以选择全面拒绝或限定包含该套件的证明的验证。

索引信任

本 PEP 不会 增加（或减少）对索引本身的信任：索引仍然被有效地信任以诚实地交付未经修改的包分发，因为一个能够修改包内容的不诚实索引也可能不诚实地修改或省略包证明。因此，本 PEP 对索引信任的假设等同于早期机制（如 PGP 和 wheel 签名）中未说明的假设。

本 PEP 不排除或阻碍未来的索引信任机制，例如 PEP 458 和/或 PEP 480。