私密状态令牌开发者指南

过去，第三方 Cookie 一直用于存储和传达用户状态的相关信息，例如登录状态、所用设备的相关信息，或用户是否为已知且可信的用户。例如，用户是否已使用 SSO 登录、用户是否拥有某种类型的兼容设备，或者用户是否为已知且可信的用户。由于第三方 Cookie 支持已被弃用，因此许多此类用例都需要通过其他方式进行支持。

私密状态令牌提供了一种在网络上共享信息的方式，但通过控制实际可共享的数据量，可保护隐私。

借助私密状态令牌（以前称为信任令牌），您可以将对用户真实性的信任从一个情境传递到另一个情境，同时帮助网站打击欺诈行为并将机器人与真人区分开来，而无需进行被动跟踪。

本文档概述了实现私密状态令牌 (PST) 的技术详情。如需查看更概要的轮廓，请参阅 PST 概览。

PST 学习流程：此流程包含多个步骤，首先要了解 API 并定义自己的令牌策略（与产品或业务相关的更多活动）。之后，技术阶段将介绍如何在本地环境中实现演示，然后将其应用于实际用例。

私密状态令牌如何运作？

在 PST 中，需要了解的关键关系是发卡机构与兑换者之间的关系。 发卡机构和兑换机构可以是同一家公司。

• 签发者 - 这些实体拥有有关用户的一些信号（例如，该用户是否为聊天机器人），并将这些信号嵌入存储在用户设备上的令牌中（详见下文）。
• 兑换者 - 这些实体可能没有关于用户的信号，但需要了解用户的相关信息（例如，该用户是否为机器人），并请求从发行者处兑换令牌，以了解该用户的可信度。

每次 PST 互动都需要发卡机构和兑换机构通力合作，在网络上共享信号。这些信号是粗略值，不够详细，无法识别个人。

私密状态令牌是否适合我？

如果公司要做出信任决策，并希望相关信息在各种情境中都适用，则 PST 可能对他们有所助益。如需详细了解 PST 的潜在用例，请参阅我们关于 PST 用例的文档。

发放和兑换令牌

PST 实现分三个阶段进行：

1. 发放令牌
2. 兑换令牌
3. 兑换记录转发

在第一阶段，系统会向浏览器发出令牌（通常在经过某种验证后）。在第二阶段，另一个实体会发出兑换已发出的令牌的请求，以读取该令牌中的值。在最后阶段，兑换方会收到包含令牌中所含值的兑换记录 (RR)。然后，兑换方可以将该记录用作该用户的证明，以便用于各种用途。

顺序图：该图展示了 PST 在真实场景中的基本用法，其中两个网站想要交换有关特定 Chrome 实例的一些信号。这两个网站会在不同时间执行发放和兑换操作，并且能够在它们之间交换可信信号。

定义令牌策略

如需定义令牌策略，您需要了解 PST 的关键概念（令牌和兑换记录）、变量、行为和限制，以便考虑它们在您的用例中的潜在用途。

代币和兑换记录：二者之间有什么关系？

每台设备最多可针对每个顶级网站和签发者存储 500 个令牌。此外，每个令牌都包含元数据，用于指明签发者在签发令牌时使用的密钥。系统会在兑换过程中使用这些信息来决定是否兑换令牌。PST 数据由浏览器在用户设备上进行内部存储，并且只能由 PST API 访问。

兑换令牌后，系统会将兑换记录 (RR) 存储在设备上。 此存储空间可用作日后兑换的缓存。每台设备、每个网页和每个发卡机构每 48 小时只能兑换两枚代币。新的兑换调用将尽可能使用缓存的 RR，而不是导致向发卡机构发出请求。

1. 系统会发放新的令牌（每个发行方、网站和设备最多 500 个）。
2. 所有令牌都存储在设备端令牌存储区（类似于 Cookie 存储区）中。
3. 如果未找到有效的 RR，则可以在签发后生成新的 RR（每 48 小时最多 2 个）。
4. RR 在到期之前会被视为有效，并会用作本地缓存。
5. 新的兑换调用将命中本地缓存（不会生成新的 RR）。

定义用例后，您必须仔细定义 RR 的生命周期，因为这将决定您在用例中能够使用 RR 的次数。

在制定策略之前，请务必了解以下关键行为和变量：

变量 / 行为	说明	可能的用途
令牌键元数据	每个令牌只能使用一个且仅一个加密密钥进行签发，并且在 PST 中，每个签发者最多只能有 6 个密钥。	使用此变量的一个可能方法是根据加密密钥为令牌定义信任范围（例如，密钥 1 = 高信任，密钥 6 = 无信任）。
令牌失效日期	令牌到期日期与密钥到期日期相同。	密钥至少每 60 天轮替一次，并且使用无效密钥签发的所有令牌也被视为无效。
令牌兑换速率限制	每台设备和发卡机构每 48 小时只能兑换两次代币。	具体取决于您的用例每 48 小时所需的预计兑换次数。
每个顶级来源的发卡机构数量上限	每个顶级来源的发卡机构数量目前上限为 2 家。	仔细定义每个网页的发行者。
每台设备上的每个发卡机构的令牌数量	特定设备上每个发卡机构的令牌数量上限目前为 500 个。	请确保每个发卡机构的令牌数量不超过 500 个。 尝试发放令牌时，请务必处理网页中的错误。
密钥提交轮替	每个 PST 颁发者都必须公开一个端点，其中包含可每 60 天更改一次的密钥提交内容，系统会忽略任何更快的轮替。	如果您的密钥将在 60 天内过期，您必须在该日期之前更新密钥承诺，以免服务中断（详情请参阅此处）。
兑换记录生命周期	您可以定义 RR 的生命周期，以确定到期日期。由于 RR 会缓存以避免向发卡机构发出不必要的新兑换调用，因此请务必确保兑换信号足够新鲜。	由于每 48 小时的兑换速率限制为 2 个令牌，因此请务必定义 RR 的生命周期，以便至少在此时间段内成功执行兑换调用（应相应地设置 RR 生命周期）。建议将此生命周期设置为数周。

场景示例

场景 1：RR 生命周期短于 24 小时 (t=t)，并且在 48 小时内多次兑换。

在这种情况下，用户将无法在 28 小时内兑换新的令牌，并且所有 RR 都将过期。

场景 2：RR 生命周期为 24 小时，并且在 48 小时内多次兑换。

在此场景中，由于 RR 的有效期为 24 小时，因此在整个 48 小时内都可以兑换，没有任何限制。

场景 3：RR 生命周期为 48 小时，并且在 48 小时内多次兑换。

在此场景中，由于 RR 的生命周期为 48 小时，因此在整个 48 小时内都可以兑换，没有任何限制。

运行演示

在采用 PST 之前，我们建议您先通过演示进行设置。如需试用 PST 演示版，您需要使用标志运行 Chrome，以启用演示版签发者密钥承诺（请按照演示版页面上的说明操作）。

运行此演示时，您的浏览器会使用演示发行方和兑换方服务器提供和使用令牌。

技术问题

如需顺利运行演示版，请执行以下步骤：

• 请务必先停止所有 Chrome 实例，然后再使用标志运行 Chrome。
• 如果您是在 Windows 计算机上运行，请参阅 此指南，了解如何将参数传递给 Chrome 可执行二进制文件。
• 在使用演示版应用时，依次打开 Applications > Storage > Private State 令牌下的 Chrome 开发者工具，查看演示版颁发者签发/兑换的令牌。

为采用做好准备

成为发卡机构

在 PST 中，发卡机构发挥着关键作用。它们会为令牌分配值，以确定用户是否为机器人。如果您想以发卡机构的身份开始使用 PST，则需要完成发卡机构注册流程。

如需申请成为发卡机构，发卡机构网站的运营者必须使用“New PST Issuer”（新 PST 发卡机构）模板在 GitHub 代码库中创建新的问题。按照代码库中的指南填写问题。 端点通过验证后，将合并到此代码库中，Chrome 服务器端基础架构将开始提取这些密钥。

发卡服务器

签发者和兑换者是 PST 的关键参与者；服务器和令牌是 PST 的关键工具。虽然我们已经在 GitHub 文档中提供了一些有关令牌的详细信息，但我们还想详细介绍一下 PST 服务器。如需设置为 PST 的签发者，您需要先设置签发服务器。

部署环境：发卡服务器

如需实现令牌颁发方服务器，您需要构建自己的服务器端应用来公开 HTTP 端点。

发卡机构组件由两个主要模块组成：(1) 发卡机构服务器和 (2) 令牌发行方。

与所有面向 Web 的应用一样，我们建议为您的发卡服务器额外添加一层保护。

1. 发卡服务器：在我们的示例实现中，发卡服务器是使用 Express 框架托管发卡机构 HTTP 端点的 Node.js 服务器。您可以查看 GitHub 上的示例代码。

2. 令牌颁发方：颁发方加密组件不需要任何特定语言，但由于此组件的性能要求，我们将以 C 实现为例，该实现使用 Boring SSL 库来管理令牌。您可以在 GitHub 上找到发行商代码示例以及有关安装的更多信息

3. 密钥：令牌颁发方组件使用自定义 EC 密钥加密令牌。这些密钥必须受到保护并存储在安全的存储空间中。

发行商服务器的技术要求

根据该协议，您需要在发卡服务器中实现至少两个 HTTP 端点：

• 密钥提交（例如 /.well-known/private-state-token/key-commitment）：浏览器可通过此端点获取加密公钥详细信息，以确认您的服务器是否合法。
  • 示例代码
• 令牌发放（例如 /.well-known/private-state-token/issuance）：令牌发放端点，用于处理所有令牌请求。此端点将是令牌颁发方组件的集成点。
  • 示例代码

如前所述，由于此服务器预计会处理大量流量，因此我们建议您使用可扩缩的基础架构（例如在云环境中）部署该服务器，以便根据不断变化的需求调整后端。

向发卡服务器发送调用

实现对发卡机构堆栈的网站提取调用，以便发行新令牌。

 // issuer request
    await fetch("/.well-known/private-state-token/issuance", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-request"
      }
    });

查看代码示例。

注意 ：在本地运行颁发者服务器时，请确保为本地端点创建加密通道 (TLS)：请参阅如何使用 HTTPS 进行本地开发。如需详细了解 Sec 标头，请参阅相关文章。

赎回服务器

您需要构建自己的服务器端应用来实现令牌兑换服务。这样，您就可以读取发卡机构发送的令牌。以下步骤概述了如何兑换令牌以及如何读取与这些令牌关联的兑换记录。

您可以选择在同一服务器（或服务器群组）中运行发行方和兑换方。

PST 演示版组件：这些是兑换器服务器的主要组件。兑换服务器（Node.js 应用）和令牌兑换器（负责在兑换流程中验证签名和令牌的加密组件）。

兑换服务器的技术要求

根据该协议，您需要为兑换服务器实现至少两个 HTTP 端点：

• /.well-known/private-state-token/redemption：用于处理所有令牌兑换的端点。令牌兑换器组件将集成到此端点
  • 示例代码

向兑换服务器发送调用

如需兑换令牌，您需要实现对兑换器堆栈的网站提取调用，以兑换之前发出的令牌。

    // redemption request
    await fetch("/.well-known/private-state-token/redemption", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "token-redemption",
        refreshPolicy: "none"
      }
    });

请参阅代码示例。

兑换令牌后，您可以通过再次执行提取调用来发送兑换记录 (RR)：

    // attach redemption records from the issuers to the request
    await fetch("<DESTINATION_RESOURCE>", {
      method: "POST",
      privateToken: {
        version: 1,
        operation: "send-redemption-record",
        issuers: [<ISSUER_DOMAIN>]
      }
    });

请参阅代码示例。

部署您的实现

如需测试您的实现，请先前往发出调用的网页，然后确认令牌是否按照您的逻辑创建。在后端验证调用是否已按照规范进行。 然后，前往发出兑换调用的网页，并确认系统是否已按照您的逻辑创建了 RR。

实际部署

我们建议您选择符合您具体用例的目标网站：

• 月访问量较少（大约低于 100 万次/月）：您应先面向一小部分受众群体部署该 API
• 您拥有并控制该解决方案：如有必要，您可以快速停用该实现，而无需进行复杂的审批
• 发行者不得超过 1 个：为限制令牌数量以简化测试。
• 兑换者不得超过两人：您需要简化问题排查流程，以防出现问题。

“权限”政策

为了正常运行，顶级页面和使用该 API 的任何子资源都必须可以使用 PST API。

令牌请求操作由 private-state-token-issuance 指令控制。操作 token-redemption 和 send-redemption-record 由 private-state-token-redemption 指令控制。在 Chrome 132 及更高版本中，默认情况下，这些指令的许可名单设置为 *（所有来源）。这意味着，顶级网页、同源 iframe 和跨源 iframe 均可使用此功能，而无需进行显式委托。

您可以选择为您网站上的特定网页停用 PST 令牌的签发或兑换，只需在每个网页的 Permissions-Policy 标头中添加 private-state-token-issuance=() 和 private-state-token-redemption=() 即可。

您还可以使用 Permissions-Policy 标头来控制第三方对 PST 的访问权限。作为标头来源列表的参数，请使用 self 和您要允许访问该 API 的任何来源。例如，如需在除您自己的来源和 https://example.com 之外的所有浏览上下文中完全停用 PST，请设置以下 HTTP 响应标头：

Permissions-Policy:private-state-token-issuance=(self "https://example.com"),private-state-token-redemption=(self "https://example.com")

如需为所有跨源资源启用该 API，请将来源列表设置为 *。

注意： 即使默认政策为 *，iframe 元素仍需要在其 allow 属性中添加 private-state-token-issuance 和 private-state-token-redemption 指令，才能获得对该功能的访问权限。详细了解 iframe allow 属性。

了解如何使用权限政策控制隐私沙盒功能，或深入了解权限政策。

问题排查

您可以通过 Chrome 开发者工具的“网络”和“应用”标签页检查 PST。

在“Network”（网络）标签页中：

针对 PST 的 DevTools 检查：依次前往网络 > 私密状态令牌，即可获取与特定网页的令牌和签发者相关的所有信息。

在“应用”标签页中：

针对 PST 的 DevTools 检查：依次前往“应用”>“私密状态令牌”，即可获取与特定网页的令牌和签发者相关的所有信息。

详细了解此 DevTools 集成。

注意 ：最终用户可以从存储空间中删除 PST，因此不应仅使用 PST 来确定设备是否受信任。您应始终考虑将 PST 用作风险决策的额外信号。

客户端最佳实践

如果您网站的关键功能依赖于特定令牌颁发方，请优先考虑这些令牌颁发方。在加载任何其他脚本之前，请为这些首选发卡机构调用 hasPrivateToken(issuer)。这对于防止潜在的兑换失败至关重要。

每个顶级颁发机构的数量不得超过 2 个，第三方脚本可能还会尝试调用 hasPrivateToken(issuer) 以优先处理自己的首选颁发机构。因此，请提前保护您的主要发卡机构，确保您的网站能按预期运行。

  // Prioritize your critical token issuer.
  document.hasPrivateToken('https://critical-issuer.example')
    .then(hasToken => {
      if (hasToken) {
        // Use the token or perform actions based on its availability.
      } else {
        // Handle the case where the token is not available.
      }
    });

  // Load third-party scripts or secure another token issuer (up to two in total).

服务器最佳实践和问题排查

为了确保您的发卡方和兑换方服务器能够高效运行，我们建议您实施以下最佳实践，以确保 PST 不会遇到任何访问、安全、日志记录或流量问题。

• 您的端点必须使用 TLS 1.3 或 1.2 来应用强加密。
• 您的基础架构必须能够处理不稳定的流量（包括流量激增）。
• 确保您的密钥受到保护且安全无虞，并符合您的访问控制政策、密钥管理策略和业务连续性计划。
• 向堆栈添加可观测性指标，确保您能够在正式版发布后了解使用情况、瓶颈和性能问题。

更多信息

1. 查看开发者文档：
   1. 首先阅读概览，快速了解 PST 及其功能。
   2. 观看 PST 简介视频。
   3. 试用 PST 演示版。
   4. 您还可以参阅 API 说明文档，详细了解该 API。
   5. 详细了解该 API 的当前规范。
2. 通过 GitHub 问题或 W3C 通话参与讨论。
3. 如需更好地了解任何术语，请参阅 Privacy Sandbox 术语表。
4. 如需详细了解 Chrome 概念（例如“源试用”或“Chrome 标志”），请访问 goo.gle/cc，观看短视频和阅读相关文章。