私密状态令牌开发者指南

过去，第三方 Cookie 一直用来存储和传递信息 用户状态的相关信息，例如登录状态、设备的相关信息 以及是否了解其用户且可信。例如， 用户使用 SSO 登录，无论用户是否具有特定类型的兼容 或用户是否为已知且可信的用户。包含 不再支持第三方 Cookie 其中许多用例都需要通过其他方式提供支持。

私密状态令牌提供了一种在整个网络上分享信息的方法， 一种可保护隐私的方法， 共享。

私密状态令牌（以前称为“信任令牌”）可信任用户的 真实性可在不同的情境之间传达，同时帮助网站 打击欺诈行为并区分机器人与真人，而无需被动跟踪。

本文档简要介绍了实现私密状态的技术详情 令牌 (PST)。有关更高级的概述，请参阅 PST 概览。

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

私密状态令牌的工作原理是什么？

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

• Issuers（颁发者）- 这些实体具有关于用户的某种信号（例如 例如用户是否为机器人），并将信号嵌入到 存储在用户设备上的令牌（详见以下部分）。
• 兑换者 - 这些实体可能没有关于用户的信号，但 需要了解一些相关信息（例如，用户是否为聊天机器人） 并要求兑换发卡机构提供的令牌以了解 可信度。

每次 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 的有效期，具体如下： 这将定义您可以在 这种情况。

请务必先了解以下关键行为和变量，然后再 制定策略：

变量 / 行为	说明	潜在用量
令牌密钥元数据	每个令牌可以有且只能使用一个加密密钥 在 PST 中，每个颁发者最多只能使用 6 个密钥。	使用此变量的一种可能方法是定义信任范围 添加到令牌中（例如，密钥 1 = 高信任度，而密钥 6 = 不信任）。
令牌失效日期	令牌失效日期与密钥失效日期相同。	密钥至少可以每 60 天轮替一次，使用 无效键也会被视为无效。
令牌兑换速率限制	每台设备和每个发卡机构最多只能进行两次令牌兑换 48 小时。	取决于您的使用所需的估算兑换次数 每 48 小时检测到一次充电盒。
每个顶级来源的发卡机构数量上限	目前，每个顶级来源的发卡机构数量上限为两个。	仔细定义每个页面的颁发者。
设备上每个颁发者的令牌数	目前，特定设备上每个发卡机构的令牌数量上限 500。	确保每个发卡机构的令牌数量少于 500 个。 在尝试提出问题时，请务必处理您网页中的错误 词元。
密钥承诺轮替	每个 PST 颁发者都必须公开具有密钥的端点 可每 60 天更改一次的承诺，并加快任何轮替的速度 则会被忽略。	如果您的密钥将在 60 天内过期，则必须执行此操作 请在该日期之前更新您的关键承诺，以免服务中断 （请参阅详细信息）。
兑换记录有效期	可以定义 RR 的有效期，以确定到期时间 日期。由于系统会缓存 RR，以避免不必要的新兑换调用 发布信息，这对于确保 兑换信号	由于兑换率限制为每 48 小时包含两个令牌， 请务必指定 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 >存储 >私密状态 令牌（使用演示应用查看已发放/兑换的令牌） 由演示发行商提供

为采用做好准备

成为发卡机构

发卡机构在 PST 中发挥着重要作用。它们为词元分配值，以确定 判断用户是否为聊天机器人。如果您想以发卡机构的身份开始使用 PST，您 需要完成 发卡机构注册流程。

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

颁发者服务器

发放者和兑换者是 PST 的主要操作者；是关键所在 适用于美国太平洋标准时间 (PST) 的工具。虽然我们已经介绍了一些有关令牌的详细信息， GitHub 文档中，我们希望 提供有关 PST 服务器的更多详情。要设为 PST 的发卡机构，您需要 首先要设置签发服务器

部署您的环境：发卡机构服务器

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

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

与所有面向 Web 的应用一样，我们建议您添加一道额外的保护屏障， 发送到发卡机构服务器

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

2. 令牌颁发者：颁发者加密组件不需要任何 但考虑到该组件的性能要求， 我们以 C 语言实现为例，它使用 Boring SSL 库来管理令牌。 您可在发行商代码示例和安装详情 GitHub 上

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

颁发者服务器的技术要求

根据协议，您需要在 您的发卡银行服务器：

• 密钥提交（例如 /.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 应用）和令牌兑换者（负责在兑换流程中验证签名和令牌的加密组件）。

兑换器服务器的技术要求

根据协议，您需要为 您的兑换服务器：

• /.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"
      }
    });

请参阅代码示例。

兑换令牌后，您可以 另一个提取调用：

    // 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，
• 您拥有并控制它 ：如有必要，您可以快速停用 无需复杂的审批即可实现
• 不超过一个颁发者：限制令牌数量，以便 从而简化测试
• 兑换者不超过两位：您需要在以下位置简化问题排查流程： 出现的问题。

“权限”政策

为了正常运行，PST API 必须可供顶级网页和使用该 API 的所有子资源使用。

令牌请求操作由 private-state-token-issuance 指令控制。操作 token-redemption 和 send-redemption-record 由 private-state-token-redemption 指令控制。默认情况下，这些指令的许可名单会设为 self。这意味着该功能仅适用于顶级网页（以及同源 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 允许属性。

了解如何使用“权限”政策控制 Privacy Sandbox 功能或更深入地了解权限政策。

问题排查

您可以在 Chrome 开发者工具的“Network”和“Application”标签页中检查 PST。

在“网络”标签页上：

针对 PST 的开发者工具检查：前往网络 >私密状态令牌，用于获取某一特定页面的令牌和颁发者的所有相关信息。

在“Application”标签页上：

针对 PST 的开发者工具检查：前往“Application”（应用）>私密状态令牌，用于获取一个特定页面的令牌和颁发者的所有相关信息。

了解详情 DevTools 集成。

注意 ：最终用户可以从存储空间中删除 PST，因此不应使用 用来定义设备是否可信。您应该始终 可以考虑将太平洋标准时间 (PST) 用作判断风险的额外信号 决策。

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

为了让您的发卡机构和兑换者服务器有效运行，我们建议您 实施以下最佳实践，以确保您不会遇到任何 访问、安全、日志记录或流量验证。

• 您的端点必须使用 TLS 1.3 或 1.2 采用强加密。
• 您的基础架构必须准备好应对不断变化的流量 （包括高峰）。
• 确保您的密钥受到保护且安全可靠，与您的访问权限保持一致 控制政策、关键管理策略和业务连续性计划。
• 向您的堆栈添加可观测性指标，以确保您拥有 以了解迁移后的用量、瓶颈和性能问题 进入生产阶段

更多信息

1. 查看开发者文档：
   1. 请先阅读 概览 以快速了解 PST 及其功能。
   2. 观看 PST 简介视频。
   3. 试用 PST 演示。
   4. 另请阅读 API explainer，以了解详情 提供详细信息
   5. 详细了解当前 规范。
2. 通过 GitHub 贡献力量 问题或 W3C 调用。
3. 要更好地了解某个术语，请查看 Privacy Sandbox 术语表。
4. 详细了解 Chrome 概念，例如“源试用”或 “Chrome 旗帜”，请查看以下网址中提供的短视频和文章： goo.gle/cc。