设计考虑

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

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

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

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

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

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

   例如，为了防止分发名称与其内容之间存在域分离，本 PEP 使用来自in-toto 项目的“Statements”将分发的内容（通过 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 数组，包含一个或多个证明“捆绑包”。每个捆绑包对应一个签名身份（例如受信任的发布者身份），并包含一个或多个证明对象。

  如“发布者”模型中所述，每个 AttestationBundle.publisher 对象特定于其受信任的发布者，但必须至少包含以下内容

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

  发布者对象中的所有其他键都是特定于发布者的。在附录 1：受信任的发布者表示示例中提供了发布者对象的完整说明性示例。

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

认证验证

验证证明对象相对于发行版文件的操作需要验证以下各项

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

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

认证中的加密灵活性

算法灵活性是加密方案中可利用漏洞的常见来源。本 PEP 通过两种方式限制算法灵活性

• 所有算法都指定在一个套件中，而不是一组几何参数。这使得攻击者无法（例如）选择具有弱散列函数的强签名算法，从而危及整个方案。

• 证明对象是版本化的，并且只能包含其版本指定的算法套件。如果将来某个特定套件被认为是不安全的，客户端可以选择全面拒绝或限定包含该套件的证明的验证。

索引信任

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

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