数字凭证

摘要

本文档规定了一种 API，使用户代理能够中介出示和签发数字凭证，例如驾驶执照、政府签发的身份证件，或其他类型的数字凭证。该 API 构建于凭证管理 1 级之上，并被设计为不依赖于凭证格式。

本节为非规范性内容。

以下示例说明如何使用 API 来请求和颁发数字凭证。

在使用 API 之前，重要的是要检查用户代理是否支持必要的特性。可以使用以下代码完成此操作：

示例 1：检查 API 支持

if (typeof DigitalCredential !== "undefined") {
  // 支持该 API
} else {
  // 不支持该 API
}

userAgentAllowsProtocol() 静态方法可用于检查用户代理是否允许将特定协议用于数字凭证签发或出示。这对于在进行 API 调用之前，检查用户浏览器允许哪些协议很有用。在实现了 DigitalCredential 的浏览器上（可通过上面所示的 typeof 检查检测），随着用户代理逐步采用对协议的支持，协议标识符会被逐步添加到 DigitalCredentialProtocol 中，因此用未知协议标识符调用此方法会安全地返回 false，而不会抛出异常。注意，在未定义 DigitalCredential 的浏览器上调用此方法会抛出 ReferenceError，因此在使用此方法前，仍然需要上面所示的 typeof DigitalCredential !== "undefined" 保护。

示例 2：使用 userAgentAllowsProtocol() 静态方法

if (DigitalCredential.userAgentAllowsProtocol("example-protocol")) {
  // 支持 DC API。继续签发或出示。
} else {
  // 不支持 DC API。回退到例如
  // 传统的基于 HTML 表单的方法。
  showHTMLForm();
}

或者，可以检查对多个协议的支持，过滤掉不受支持的协议：

示例 3：使用 userAgentAllowsProtocol() 检查多个协议

const protocols = [
  "example-issuance-protocol",
  "another-issuance-protocol"
];
const supportedProtocols = protocols.filter(DigitalCredential.userAgentAllowsProtocol);
if (supportedProtocols.length > 0) {
  // 至少支持一个协议。继续签发。
} else {
  // 不支持任何协议。回退到其他签发方法。
}

由于协议标识符会被逐步添加到 DigitalCredentialProtocol 中，因此可以使用此方法优先选择较新的协议，同时在旧版浏览器上优雅地回退到较旧的协议：

示例 4：优先选择较新的协议，并回退到较旧协议

// 按偏好排序；在实现 DigitalCredential 的浏览器上，
// 未知协议会返回 false，而不是抛出异常。
const protocol = [
  "example-new-protocol",
  "example-legacy-protocol",
].find(DigitalCredential.userAgentAllowsProtocol);

if (protocol) {
  // 使用此浏览器支持的最佳协议。
} else {
  // 未找到受支持的协议。回退到其他方法。
}

以下示例展示了如何使用 API 请求数字凭证。该 API 的入口点是 navigator.credentials.get() 方法，它用于从用户代理请求数字凭证。如果用户代理支持出示，它允许用户通过数字凭证选择器选择数字凭证：

示例 5：请求数字凭证

<button>验证身份</button>
<script>
  const button = document.querySelector("button");
  button.addEventListener("click", async () => {
    const protocol = "example-request-protocol";
    // 检查 DC API 和协议支持
    if (!DigitalCredential.userAgentAllowsProtocol(protocol)) {
      // 浏览器不允许使用此协议。
      // 回退到其他验证方法。
      showTraditionalVerificationForm();
      return;
    }
    try {
      const credential = await navigator.credentials.get({
        digital: {
          requests: [{
            protocol,
            data: { /* 出示请求数据 */ }
          }]
        }
      });

      // 将其发回验证方服务器以进行解密和验证
      const response = await fetch("/verify-credential", {
        method: "POST",
        headers: {
          "Content-Type": "application/json"
        },
        body: JSON.stringify(credential)
      });

      // 检查响应
      if (!response.ok) {
        throw new Error("验证凭证失败");
      }

      // 渲染验证结果
      displayVerificationResult(await response.json());

    } catch (error) {
      console.error("请求数字凭证时出错：", error);
    }
  });
</script>

类似地，当站点需要颁发数字凭证时，数字凭证 API 在站点、用户代理和持有者之间协调数字凭证的颁发。

以下示例展示了如何使用数字凭证 API 请求颁发数字凭证。要颁发数字凭证，站点会调用 navigator.credentials.create() 方法，如果用户代理支持颁发，该方法将启动颁发流程：

示例 6：请求签发数字凭证

<button>请求签发数字凭证</button>
<script>
  const button = document.querySelector("button");
  button.addEventListener("click", async () => {
    const protocol = "example-issuance-protocol";
    // 检查 DC API 和协议支持
    if (!DigitalCredential.userAgentAllowsProtocol(protocol)) {
      // 浏览器不允许使用此协议。
      // 回退到其他签发方法。
      showTraditionalIssuanceForm();
      return;
    }
    try {
      const credential = await navigator.credentials.create({
        digital: {
          requests: [{
            protocol,
            data: { /* 签发请求数据 */ }
          }]
        }
      });
    } catch (error) {
      console.error("签发数字凭证时出错：", error);
    }
  });
</script>

本规范允许通过 "digital-credentials-get" 策略控制特性，使用该 API 从远程/第三方源出示凭证。这对于网站想要从托管在不同源上的验证服务请求数字凭证的场景很有用。Permissions Policy 可以设置在嵌入想要使用该 API 的网站的 iframe 上。下面是一个如何在 iframe 上设置 Permissions Policy 的示例：

示例 7：跨源请求数字凭证

<iframe src="https://verifier-service.example.com"
        allow="digital-credentials-get">
</iframe>

类似地，本规范允许通过 "digital-credentials-create" 策略控制特性，使用该 API 从远程/第三方源签发凭证。这对于网站想要使用不同源上的签发服务来请求签发数字凭证的场景很有用。Permissions Policy 可以设置在嵌入签发方界面的 iframe 上。下面是一个示例：

示例 8：跨源签发数字凭证

<iframe src="https://issuer.example.com"
        allow="digital-credentials-create">
</iframe>

本节为非规范性内容。

以下事项属于本规范的范围：

出示请求，包括用于出示数字凭证的机制。
针对签发请求的数字凭证。
用于确保在进行 API 调用时，在没有明确用户同意的情况下，网站不会得知关于持有者或其持有的任何数字凭证的任何信息的机制。
确保任何已安装的应用软件不会获知关于给定签发请求或出示请求的任何信息，除非持有者明确同意使用该软件。

以下事项不在范围内：

UI/UX 考量，但无障碍和隐私方面除外，这些方面会被处理，以确保在出示和签发过程中能够访问并保护用户数据。
用户代理之外的功能不在范围内，包括平台特定框架、原生操作系统 API、独立应用程序，以及用于存储、管理或处理数字凭证的硬件组件。这包括用于选择特定凭证并获得用户许可，以将请求转发给用户所选凭证管理器的用户界面和用户交互。
凭证管理器的实现，特别是其作为持有者软件（通常称为“数字钱包”）的角色，包括它们如何安全地存储或管理数字凭证，或如何向出示或签发它们的用户代理宣告能力，均不在范围内。唯一的例外是与此类软件之间传输签发请求数据和出示请求数据。

受支持的出示和签发协议表
标识符	规范
出示协议
`openid4vp-v1-unsigned`	OpenID for Verifiable Presentations 1.0 § A.3.1. 未签名请求
`openid4vp-v1-signed`	OpenID for Verifiable Presentations 1.0 § A.3.2. 已签名请求
`openid4vp-v1-multisigned`	OpenID for Verifiable Presentations 1.0 § A.3.2.2. JWS JSON 序列化（多签名请求）
`org-iso-mdoc`	ISO/IEC 18013-7:2025 符合 ISO 的驾驶执照，第 7 部分：移动驾驶执照（mDL）附加功能 § 附录 C
签发协议
`openid4vci-v1`	OpenID for Verifiable Credential Issuance 1.0 § 即将推出议题： API 集成 OpenID Foundation 正在开展与 Digital Credentials API 的集成工作。你可以在 OpenID4VCI#410 跟踪进展。

凭证请求协调器是一个由用户代理定义的组件，它通过顶级可遍历体中介数字凭证交互。每个顶级可遍历体都恰好有一个关联的协调器。该协调器确保在所有子可导航体中最多只有一个交互处于活动状态，编排出示或签发的端到端流程，并管理交互状态之间的转换。

凭证请求协调器维护一个活动 promise，用户代理将其初始化为 null。通过这个 Promise，协调器会把异步凭证请求工作流的状态反映给脚本，并在交互成功完成时以凭证响应兑现，或在处理失败、用户通过 UI 取消请求，或脚本通过 AbortSignal 中止操作时拒绝。

凭证请求协调器维护一个中止信号，用户代理将其初始化为 null。

凭证请求协调器维护一个中止算法，用户代理将其初始化为 null。

凭证请求协调器：

验证并转换出示或签发的输入和输出。
请求平台显示可用于当前请求的凭证和/或能够处理当前请求的持有者，供用户选择。凭证和持有者的可用性由请求参数、用户同意和平台策略的匹配决定。
根据交互结果管理兑现或拒绝活动 promise。

用户代理可以根据用户或平台策略，将部分或全部协调器职责委托给外部凭证管理器、平台组件或其他可信实体。

注

凭证请求协调器具有一组有限的交互状态，这些状态用于管理凭证请求的生命周期：

"idle"：: 当前没有正在进行的凭证请求。
"requesting"：: 一个凭证请求正在进行，并且用户界面已呈现。
"aborting"：: 活动交互正因错误、用户操作或信号中止而被取消；协调器正在清理，然后返回到 "idle"。

协调器初始化为idle 交互状态。

要在给定 Document document、一组序列 DigitalCredentialGetRequest 值或一组序列 DigitalCredentialCreateRequest 值 requests、一个 Promise promise，以及一个可选的 AbortSignal signal 的情况下准备凭证请求：

令 global 为 document 的相关全局对象。
如果凭证请求协调器不处于 "idle" 交互状态：
1. 在给定 global 的DOM 操作任务源上排入一个全局任务，以使用 "NotAllowedError" DOMException 拒绝 promise。
2. 返回。
断言：凭证请求协调器的活动 promise 为 null。
将凭证请求协调器的交互状态设置为 "requesting"。
将凭证请求协调器的活动 promise设置为 promise。
令 validatedRequests 为在给定 requests 时执行验证凭证请求的结果。如果该操作抛出一个异常 error，则：
1. 使用 error 和 promise拒绝凭证请求。
2. 返回。
如果 validatedRequests 为空，则：
1. 使用一个新创建的 TypeError 和 promise拒绝凭证请求。
2. 返回。
如果传入了 signal，则：
1. 断言：signal 未被中止。
  
  注
  
  预先中止的信号会在调用此算法之前，由请求 Credential和创建 Credential处理。
2. 将凭证请求协调器的中止信号设置为 signal。
3. 令 abortAlgorithm 为以下算法：
  1. 如果凭证请求协调器的活动 promise不是 promise，则返回。
  2. 给定 signal 的中止原因，中止凭证请求。
4. 将凭证请求协调器的中止算法设置为 abortAlgorithm。
5. 将 abortAlgorithm添加到 signal。
令 handled 为在给定 promise 和 global 时运行处理虚拟钱包行为的结果。
如果 handled 为 true，则返回。
使用 document、validatedRequests、promise 和 signal发起凭证请求。
如果 document 不再完全活动，则使用一个 "AbortError" DOMException中止凭证请求。

给定一个由 DigitalCredentialGetRequest 或 DigitalCredentialCreateRequest 对象组成的序列 requests，验证凭证请求：

令 validatedRequests 为一个新的空列表。
对 requests 中的每个 request：
1. 令 protocol 为在给定 request 的情况下运行转换请求协议的结果。
2. 如果 protocol 是失败，则继续。
3. 如果在给定 protocol 的情况下，用户代理允许协议返回 false，则继续。
4. 如果 request 是 DigitalCredentialGetRequest，则令 data 为 request 的 data；或者如果 request 是 DigitalCredentialCreateRequest，则令其为 request 的 data。
5. 将 data 序列化为 JSON 字符串。
6. 如果序列化导致一个异常，则抛出该异常。
7. 根据 request 的展示协议或签发协议或其他条件，验证 request 的展示请求数据或签发请求数据。验证要求是特定于协议的，并且不在本规范范围内：
  
  注：验证细节不在范围内
  
  验证包括确认 request 的展示请求数据或签发请求数据符合指定展示协议或签发协议的要求。请参阅具体展示协议或签发协议的规范以了解详细信息，包括验证失败的潜在原因，以及实现者在验证期间需要考虑的任何安全和隐私考量。
  
  Issue 472：用户代理请求验证和错误 spec substantive
  
  准备步骤最初声明：
  
  除了协议定义的要求之外，[=user agent=] 还可以根据本地策略、配置或不断演进的安全考量应用额外的验证条件。例如，[=user agent=] 可能会拒绝某个请求，如果该请求 (a) 寻求特定的凭证属性，(b) 使用或要求 [=user agent=] 被配置为不接受的密码算法（例如，作为算法敏捷性或向后量子方案过渡的一部分），或 (c) 依赖于未被 [=user agent=] 所配置的信任决策接受的证书或信任锚。
  
  最好对此进行扩展说明。
  1. 如果验证失败，则抛出一个适当的异常。
  2. 否则，将 request 追加到 validatedRequests。
返回 validatedRequests。

要在给定 JavaScript 值或 DOMException error 的情况下中止凭证请求：

如果凭证请求协调器的活动 promise为 null，则返回。
令 activePromise 为凭证请求协调器的活动 promise。
如果凭证请求协调器处于 "requesting" 交互状态：
1. 将凭证请求协调器的交互状态设置为 "aborting"。
2. 关闭数字凭证选择器。
  
  注
  
  关闭可能失败（例如，如果数字凭证选择器由于内存压力而被销毁），但协调器无论如何都会继续完成凭证请求。
使用 error 和 activePromise拒绝凭证请求。

要在给定一个（JavaScript 值）error 和一个 Promise promise 的情况下拒绝凭证请求：

断言：凭证请求协调器的活动 promise是 promise。
在给定 promise 的相关全局对象的DOM 操作任务源上排入一个全局任务，以执行以下步骤：
1. 如果凭证请求协调器的活动 promise不是 promise，则返回。
2. 令 signal 为凭证请求协调器的中止信号。
3. 令 abortAlgorithm 为凭证请求协调器的中止算法。
4. 如果 signal 不是 null 且 abortAlgorithm 不是 null：
  1. 从 signal 中移除 abortAlgorithm。
5. 将凭证请求协调器的中止信号设置为 null。
6. 将凭证请求协调器的中止算法设置为 null。
7. 使用 error拒绝 promise。
8. 将凭证请求协调器的活动 promise设置为 null。
9. 将凭证请求协调器的交互状态设置为 "idle"。

要在给定 Document document、一个已验证凭证请求 validatedRequests 的列表、一个 Promise promise，以及一个可选的 AbortSignal signal 的情况下发起凭证请求：

令 topLevelOrigin 为 document 的顶级可遍历体的活动文档的相关设置对象的源。
令 requestData 为新的请求上下文，其requests 为 validatedRequests，且top-level origin 为 topLevelOrigin。
并行：
1. 使用 requestData 显示数字凭证选择器，并等待以下结果之一：
  - 用户选择了能够满足请求的数字凭证或持有者。
  - 用户取消操作。
  - 平台遇到错误。
  议题 456：使用 CTAP 出示 discussion spec
  
  当时在和 @mohamedamir 讨论……我们应当在规范中说明，跨平台跨设备凭证交换应当（或建议）通过 CTAP 进行。
  
  我们不能强制要求（即 MUST），因为：
  - 这与操作系统或框架有关，因此超出了本规范范围……或者至少超出了浏览器在未实现整个交换栈时通常能做的范围。
  - 平台可以自由使用更高效或专有的协议，尤其是用于跨设备交换时。
  - 这能让规范面向未来，同时在当下提供最佳兼容性。
2. 如果 signal 不为 null 且 signal 已中止：
  1. 返回。
    
    注：中止已被处理
    
    由准备凭证请求步骤添加到 signal 的中止算法会处理数字凭证选择器的拆卸。
3. 如果用户取消操作或没有选中凭证：
  1. 令 error 为一个新创建的 "NotAllowedError" DOMException。
  2. 使用 error 和 promise拒绝凭证请求。
  3. 返回。
4. 如果平台返回特定于平台的错误：
  1. 令 error 按如下方式确定：
    
    用户代理或平台不允许该操作：
    
    一个新创建的 "NotAllowedError" DOMException。
    
    请求数据格式错误或无效：
    
    一个新创建的 TypeError。
    
    一个凭证请求已在进行中：
    
    一个新创建的 "InvalidStateError" DOMException。
    
    否则：
    
    一个新创建的 "OperationError" DOMException。
  2. 使用 error 和 promise拒绝凭证请求。
  3. 返回。
5. 如果用户选择了一个数字凭证：
  1. 令 protocol 为数字凭证选择器为此次交换返回的协议标识符。
    
    注：协议由平台确定
    
    数字凭证选择器或底层平台决定将 validatedRequests 中的哪一项转发给持有者，并返回该交换的协议标识符。用户代理不一定知道具体选中了哪一项。
  2. 令 responseData 为由持有者返回的字符串出示响应或字符串签发响应。
    
    注：为什么响应是字符串
    
    响应是字符串，因为用户代理负责在正确的 realm 中将其解析为 JavaScript 对象，验证其为有效 JSON，并确认解析后的值是对象，这是 data 属性所要求的。
  3. 在给定 document 的相关全局对象的DOM 操作任务源上排入一个全局任务，以执行以下步骤：
    1. 如果凭证请求协调器的活动 promise不是 promise，则返回。
    2. 令 parsedResponseDataOrError 为在给定 responseData 时将 JSON 字符串解析为 JavaScript 值的结果。
    3. 令 abortSignal 为凭证请求协调器的中止信号。
    4. 令 abortAlgorithm 为凭证请求协调器的中止算法。
    5. 如果 abortSignal 不是 null 且 abortAlgorithm 不是 null，则从 abortSignal 中移除 abortAlgorithm。
    6. 将凭证请求协调器的中止信号设置为 null。
    7. 将凭证请求协调器的中止算法设置为 null。
    8. 如果 parsedResponseDataOrError 是一个异常：
      1. 使用 parsedResponseDataOrError拒绝 promise。
    9. 否则，如果 parsedResponseDataOrError 不是对象：
      1. 使用一个新创建的 TypeError拒绝 promise。
    10. 否则：
      1. 令 credential 为一个新创建的 DigitalCredential 实例，其 data 被初始化为 parsedResponseDataOrError，且其 protocol 被初始化为 protocol。
      2. 使用 credential兑现 promise。
    11. 将凭证请求协调器的活动 promise设置为 null。
    12. 将凭证请求协调器的交互状态设置为 "idle"。

数字凭证 API 利用凭证管理第 1 级规范，允许用户代理协调颁发和出示数字凭证。

该 API 允许从用户代理请求数字凭证，用户代理随后向用户呈现数字凭证选择器，允许用户选择一个数字凭证来满足该请求。这是通过网站调用 navigator.credentials.get() 方法完成的，该方法运行凭证管理第 1 级的请求一个 Credential 算法。然后，该算法回调到本规范的 DigitalCredential 接口的 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 内部方法。

此外，该 API 还允许请求颁发数字凭证，这会在用户代理和/或持有者之间启动一个经协调的颁发流程。这是通过调用 navigator.credentials.create() 方法完成的，该方法运行凭证管理第 1 级的创建凭证算法。然后，该算法回调到本规范的 DigitalCredential 接口的 [[Create]](origin, options, sameOriginWithAncestors) 内部方法。

有关如何与凭证管理第 1 级规范集成的完整详情，请参见凭证管理集成。

WebIDLpartial dictionary CredentialRequestOptions {
  DigitalCredentialRequestOptions digital;
};

digital 成员允许配置数字凭证请求的选项。

WebIDLdictionary DigitalCredentialRequestOptions {
  required sequence<DigitalCredentialGetRequest> requests;
};

requests 指定出示协议和出示请求数据，用户代理可以将其与凭证管理器（例如数字钱包）进行匹配。

DigitalCredentialGetRequest 字典表示一个出示请求。它用于指定出示协议和一些出示请求数据，用户代理可以将其与凭证管理器（例如数字钱包）进行匹配。

WebIDLdictionary DigitalCredentialGetRequest {
  required DOMString protocol;
  required object data;
};

protocol 成员表示出示协议。

protocol 成员的值是 DigitalCredentialPresentationProtocol 中定义的协议标识符之一。

data 成员是由持有者的凭证管理器（例如数字身份钱包）处理的出示请求数据。

WebIDLpartial dictionary CredentialCreationOptions {
  DigitalCredentialCreationOptions digital;
};

digital 成员允许配置数字凭证签发的选项。

WebIDLdictionary DigitalCredentialCreationOptions {
  required sequence<DigitalCredentialCreateRequest> requests;
};

requests 指定签发协议和签发请求数据，用户代理可以将其转发给持有者。

DigitalCredentialCreateRequest 字典表示一个签发请求。它用于指定签发协议和一些签发请求数据，以在签发方和持有者之间传达签发请求。

WebIDLdictionary DigitalCredentialCreateRequest {
  required DOMString protocol;
  required object data;
};

protocol 成员表示签发协议。

protocol 成员的值是 DigitalCredentialIssuanceProtocol 中定义的协议标识符之一。

data 成员是由持有者的凭证管理器（例如数字身份钱包）处理的签发请求数据。

DigitalCredential 接口表示一个概念性的数字凭证。

DigitalCredential 接口强制所有操作进行用户中介，以确保用户控制和同意。

为了简化开发者在涉及 DigitalCredential 的 get() 调用中的体验，用户代理在 mediation 成员缺失或其值不是 "required" 时，不得抛出错误。类似地，在涉及 DigitalCredential 的 create() 调用中，用户代理在 mediation 成员缺失或其值不是 "required" 时不得抛出错误。这使 "required" 中介成为该 API 的隐式且不可覆盖的行为。

WebIDLtypedef (DigitalCredentialPresentationProtocol or DigitalCredentialIssuanceProtocol) DigitalCredentialProtocol;

[Exposed=Window, SecureContext]
interface DigitalCredential : Credential {
  [Default] object toJSON();
  readonly attribute DigitalCredentialProtocol protocol;
  [SameObject] readonly attribute object data;
  static boolean userAgentAllowsProtocol(DOMString protocol);
};

protocol 成员是用于请求该数字凭证的出示协议，或用于签发该数字凭证的签发协议。

data 成员是凭证的响应数据。它包含可解析为 JSON 的对象类型子集。

userAgentAllowsProtocol() 方法允许数字凭证验证方确定用户代理允许哪些出示协议和签发协议。

注

此方法不会传达底层 OS/平台对出示协议或签发协议的支持。

用户代理不得基于任何关于硬件可用性、软件存在或配置、凭证管理器或数字凭证的信息，或用户配置或偏好，改变响应值。如果响应值发生变化，用户代理将引入指纹识别风险，以及静默暴露关于用户行为或配置的其他细节的风险。响应值应当仅随用户代理主版本而变化，并指示浏览器是否支持将使用该协议的请求分发到底层平台或提供方。

要在给定一个 DOMString protocol 时，检查用户代理是否允许协议，执行以下步骤：

如果 protocol 不是 DigitalCredentialProtocol 的枚举值，返回 false。
如果用户代理允许 protocol，则返回 true，否则返回 false。

调用此方法时，用户代理必须返回在给定 protocol 时用户代理是否允许协议的结果。

数据结构（例如枚举）在本规范中支持 DigitalCredential。

请求上下文是一个结构，具有以下项：

requests: 一个经过验证的凭证请求列表。
top-level origin: 一个环境设置对象的源。

此枚举的值对应于5. 协议中列出的受支持出示协议。

WebIDLenum DigitalCredentialPresentationProtocol {
  "openid4vp-v1-unsigned",
  "openid4vp-v1-signed",
  "openid4vp-v1-multisigned",
  "org-iso-mdoc"
};

此枚举的值对应于5. 协议中列出的受支持签发协议。

WebIDLenum DigitalCredentialIssuanceProtocol {
  "openid4vci-v1",
};

调用时，[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 内部方法，如果用户代理不支持出示请求（例如，平台无法提供数字凭证选择器），则使用相同参数调用 Credential 的 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 内部方法的默认实现。否则：

如果存在，令 signal 为 options 的signal。
如果 signal 已中止，则返回一个以 signal 的中止原因拒绝的 promise。
令 global 为 this 的相关全局对象。
令 document 为 global 的关联 Document。
如果 document 不是具有用户注意的顶级可遍历体的完全活动后代，则返回一个以 "NotAllowedError" DOMException 拒绝的 promise。
令 requests 为 options 的 digital 的 requests 成员。
如果 global 没有瞬态激活，则返回一个以 "NotAllowedError" DOMException 拒绝的 promise。
消耗 global 的用户激活。
令 promise 为在 this 的相关 realm中的一个新 promise。
使用 document、requests、promise 和 signal准备凭证请求。
返回 promise。

调用时，[[Store]](credential, sameOriginWithAncestors) 必须使用相同参数调用 Credential 的 [[Store]](credential, sameOriginWithAncestors) 内部方法的默认实现。

调用时，[[Create]](origin, options, sameOriginWithAncestors) 内部方法，如果用户代理不支持签发请求，则使用相同参数调用 Credential 的[[Create]](origin, options, sameOriginWithAncestors) 内部方法的默认实现。否则：

如果存在，令 signal 为 options 的signal。
如果 signal 已中止，则返回一个以 signal 的中止原因拒绝的 promise。
令 global 为 this 的相关全局对象。
令 document 为 global 的关联 Document。
如果 document 不是具有用户注意的顶级可遍历体的完全活动后代，则返回一个以 "NotAllowedError" DOMException 拒绝的 promise。
令 requests 为 options 的 digital 的 requests 成员。
如果 global 没有瞬态激活，则返回一个以 "NotAllowedError" DOMException 拒绝的 promise。
消耗 global 的用户激活。
令 promise 为一个新 promise，位于 this 的相关 realm中。
使用 document、requests、promise 和 signal准备凭证请求。
返回 promise。

DigitalCredential 接口对象具有一个名为 [[type]] 的内部槽，其值为 "digital"。

DigitalCredential 接口对象具有一个名为 [[discovery]] 的内部槽，其值为 "remote"。

本节为非规范性内容。

数字凭证 API 是一项强大特性，需要获得最终用户的明确许可。此要求会在调用 CredentialsContainer 的 get() 方法时以规范性方式强制执行。

本节为非规范性内容。

以下各节描述了该 API 的安全属性、范围内威胁、安全所依赖的假设，以及应用缓解措施后仍然存在的残余威胁。本规范仅在中介凭证响应时，定义用户代理行为的要求。

注

其他依赖协议、凭证管理器实现、操作系统或传输安全的安全考量被描述为期望或前提条件，但除非已被规范性指定，否则本规范不对其作出规范性要求。

本规范的威胁模型包括对该 API 以及生态系统中相邻标准的威胁。

对于本规范，威胁分为两类：范围内威胁和范围外威胁。

范围内威胁是由 DC API 本身引入或处理的威胁。以下是本规范的范围内威胁：

请求篡改: 能够在不安全上下文中注入或修改页面内容的网络攻击者，试图在处理前篡改 DigitalCredentialGetRequest 或 DigitalCredentialCreateRequest。
API 泛洪: 恶意网站试图通过快速、重复发出请求来压垮 API，以耗尽系统资源、混淆用户、制造不必要的凭证交互，或造成提示疲劳从而降低用户体验。这包括在不合适的时间发出请求，例如在页面加载期间或没有有意义的用户上下文时。
未授权跨源访问: 恶意网站试图通过嵌入的第三方内容（例如 iframe）请求或签发数字凭证，而没有嵌入站点的明确许可，这可能导致凭证收集或未授权访问敏感用户数据。

范围外威胁是由协议、凭证管理器、OS 平台安全或传输层处理的威胁。即使“超出范围”，它们仍然相关，因为它们会影响凭证出示和签发的端到端安全性。以下内容定义了本规范的范围外威胁：

待编写……

以下缓解措施通过本规范中的规范性要求来处理范围内威胁。

Digital Credential API 的 WebIDL 接口仅在安全上下文中暴露，从而降低通过不安全上下文进行篡改的风险（例如，恶意脚本通过网络被注入）。请参阅 5 安全考量一节，该节属于安全上下文规范，以获取更多信息。

Digital Credentials API 通过两种机制减少API 泛洪：

瞬态激活： [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 和 [[Create]](origin, options, sameOriginWithAncestors) 方法都会消耗用户激活，防止没有用户交互的自动化请求或重复请求。
始终要求调解：该 API 使用户调解隐式为“required” （参见 DigitalCredential 接口），确保对于每个凭证操作，都通过平台的凭证选择器界面取得用户许可。

关于防止凭证请求被滥用的其他指导，请参阅 Credential Management Level 1 规范的 7 隐私考量一节。不过请注意，这些保护有其局限性，因为站点仍可能使用诱导性设计模式来鼓励不必要的用户交互，从而触发凭证请求。

Digital Credentials API 通过与权限策略集成（参见权限策略集成），减少跨源滥用。请求一个 Credential 和创建一个 Credential 算法分别作为 "digital-credentials-get" 和 "digital-credentials-create" 受策略控制的特性的策略执行点。这两个特性是有意分开的：站点可以启用 "digital-credentials-get" 而不启用 "digital-credentials-create"，反之亦然，从而将每个嵌入式上下文限制为仅具有其所需的能力。请参阅权限策略规范的权限策略一节，以了解此集成提供的其他安全属性。

本节为非规范性内容。

议题：隐私考量一节仍在编写中

随着本文档的发展，本节仍在编写中。

数字凭证 API 集成到一个复杂的生态系统中，该生态系统具有多个技术层和各种参与者（包括但不限于验证方、持有者和签发方），其中每一方都必须考虑用户隐私的不同方面。本规范不试图穷尽列出不同参与者的所有考量。我们希望将这些各方引向多种其他资源，这些资源能够更全面地探讨数字凭证威胁模型：

相反，这些考量聚焦于数字凭证 API 本身，并描述用户代理在实现该 API 时如何履行其用户代理职责，同时考虑到它所交互的生态系统的相关隐私属性。

数字凭证的隐私考量并非静态。它们会随着生态系统成熟而随时间演进，并可能受到生态系统中其他行为者的行为、栈中其他层的改进、对用户隐私的新威胁，以及不断变化的社会规范和法规的影响。

预计参与数字凭证 API 设计和实现的各个小组会主动监测不断演进的隐私格局，并参与该 API 的相应演进。

数字凭证 API 被设计为中介网站对数字凭证的请求，并且不依赖于凭证格式及其中包含的信息，也不依赖于用于交换它的协议。这一点以及其他关键设计选择，均源于为用户提供比现有替代方案（例如 [custom-schemes]）更安全、更私密的凭证交换体验这一目标，同时仍然兼容常见的交换协议以便采用。

该 API 提供了验证方与持有者之间的连接接口，即启动凭证出示协议以及用户切换到持有者应用以选择凭证的手段。过去为此目的使用过的解决方案包括二维码和自定义 URL 方案。正如在 Web 上出示凭证和身份出示中自定义方案的相关顾虑中所述，这些解决方案存在安全、隐私和无障碍方面的顾虑。

随着数字凭证技术的采用受到生态系统需求和监管要求的推动，Web 平台提供了一个前述较不理想技术的替代方案，它便于开发者使用，兼容现有的凭证展示协议，而且最重要的是，与前述替代方案相比，它为用户提供了更好的用户隐私、安全性和可访问性属性。

数字凭证 API 赋予用户代理代表用户进行中介的能力（例如以数字凭证选择器的形式），以便对请求进行上下文化，并防止立即暴露给持有者应用。它还对受支持协议施加某些最低要求，例如响应加密。

注

Digital Credentials API 服务于多种用例，这些用例具有不同程度的数据披露，并面向在不同上下文中具有不同偏好的各个用户。值得注意的是，由此 API 调解的凭证交换的隐私属性，可能会受到单个用户所处法律和监管环境的强制要求。

这意味着某些用户可能不希望，或不被允许，使用保护隐私程度最高的方式来交换凭证信息。尽管如此，用户代理仍需要为用户提供一种默认保护隐私的体验，并保护他们免受伤害。

由于这种偏好和用例的范围很广，用户代理可能难以判断用户是否有意暴露其个人信息，还是正被诱骗这样做。因此，用户代理有责任确保每个用户在交换开始之前，理解他们正在共享哪些数据，以及谁将参与信息交换。

因为数字凭证 API 位于涉及多个独立方的交换中心，所以这些各方用于交换用户信息的出示协议和凭证格式，对于用户代理保护用户隐私的目标至关重要。

议题 255：协议注册表：仅审查并不足够 privacy-tracker security-tracker registry privacy-considerations security-considerations

我认为协议有两项要求需要进一步阐述：

必须经过隐私审查 [...]

以及

必须经过安全审查 [...]

从技术上讲，一个说“该协议在各方面都很糟糕”的审查也满足这些标准。

如果有一组具体的隐私和安全要求需要协议满足，会更有用；这样的审查便能够说明某一标准是否已经达成。审查中可能会存在主观因素，但也应当有每个协议都需要达到的最低门槛。

这超出了当前纳入标准中的现有要求。我手头没有完整清单，但应该可以制定出一个清单。一旦制定完成，该清单应当纳入规范。例如，该协议是否依赖于回拨？该协议（或其传递的格式）是否保证出示的不可链接性？或者——鉴于不可链接性对某些用例并不适用——在什么条件下 API 要求协议提供不可链接性？协议包含哪些透明度便利措施？哪些隐蔽信道是可接受的？

选择性披露是数据最小化的一项基本技术，它允许持有者共享验证方所请求的最低必要信息。协议应当通过允许验证方指定所需的确切声明来促进选择性披露。

不可链接性是一种属性，它确保如果用户多次出示凭证中的属性，验证方无法将这些单独的出示相互关联，以推断它们涉及同一用户（验证方—验证方可链接性），或者确保验证方无法与签发方串通，将某个凭证从凭证管理器交换给签发方进行报告（验证方—签发方可链接性）。前者是一种可由持有者和签发方维持的属性，例如通过为各个验证方签发新的凭证。

虽然后者是可以实现的，例如通过零知识证明，但 API 的设计选择（例如加密响应）使得用户代理无法证明验证者-签发者不可链接性在实践中已经实现。尽管如此，仍要求协议尽可能限制可链接性。

请注意，不可链接性仅针对无法链接到特定用户身份的属性。名称、驾驶执照号码或电话号码等本质上可链接的属性，并不会从不可链接性中受益。

通过 Digital Credentials API，用户代理可以帮助验证者和凭证管理器交换不可链接的属性，但由于响应加密，它无法保证在验证者和凭证管理器之间没有传递可链接的信息。建议用户代理在其用户许可体验中考虑这一事实。

议题 279：可链接性和签发方参与作为协议要求 privacy-tracker

此 API 的不可链接性目标是哪一级？我们能否规范性地强制支持任何特定不可链接性特性？

“回传”是指这样的场景：数字凭证的展示或验证会导致向签发者或另一个中心实体发出通知或通信，这可能导致对个人的跟踪和画像分析。

与不可链接性类似，在用户已授予继续处理凭证请求的许可之后，用户代理无法确保签发者没有主动参与凭证展示的创建或验证。从那一点开始，由凭证管理器拥有此决策权。虽然某些凭证管理器可以被视为用户代理，但通常建议实现 Digital Credentials API 的用户代理设计其许可体验，以防止在用户确认之前将请求暴露给凭证管理器（同时牢记集成多个协作用户代理的考量）。

要求协议支持一些机制，使签发者、凭证管理器和验证者能够避免或减少对“回传”机制的依赖。

议题 279：可链接性和签发方参与作为协议要求 privacy-tracker

此 API 的不可链接性目标是哪一级？规范在多大程度上可以要求限制签发方参与？

在凭证交换中，颁发者参与的一种常见情形是进行凭证撤销检查。当出示意图实现验证者-颁发者不可关联时，这尤其具有挑战性。当凭证出示通过使用例如零知识证明而变得不可关联时，协议中使用的凭证格式预期会支持离线撤销方法，例如密码学累加器。还预期协议设计和规范会尽可能不鼓励验证者为了撤销目的而参与。

议题 280：我们能否要求协议支持不可链接的撤销？privacy-tracker registry

我们应该讨论不可链接撤销技术是否足够实用，因而可以被规范性要求。

验证方授权是指验证方证明其身份，并证明其有正当权利请求特定属性或凭证的过程。当交换敏感数据时，例如来自政府签发凭证的数据，这尤其有用。验证方授权可以限制不必要或滥用性的凭证请求，并确保验证方的访问被限制在其注册的特定凭证属性范围内。

检查验证方授权通常由凭证管理器处理，但用户代理可能会发现这类方案的存在有助于防止 API 滥用，并设计出信息充分的用户许可体验。

议题 281：仅支持授权验证方（针对政府凭证）的用户代理 privacy-tracker

我们是否应当要求协议包含允许用户代理理解验证方授权的规定？

为了防止用户信息在“传输”过程中暴露给其他方，例如加载在验证方页面上的浏览器扩展，并鼓励验证方安全存储用户凭证，协议需要在凭证交换中支持并强制使用加密响应。

议题 109：是否应要求响应加密 discussion pending closure privacy-tracker security-tracker

与#49以及我们已经进行过的其他若干讨论有关：我们是否想说响应必须始终加密（如果是，用哪些算法），还是可以将其保留为可选？

不必要的凭证请求是整个数字凭证生态系统的关键隐私风险。它们可能以不同方式并出于不同动机表现出来：

有意滥用 API，以出于欺诈、跟踪或出售数据的目的获取关于用户的敏感信息。例如，站点可能通过误导性内容诱骗用户共享其护照信息。这可能导致身份盗用和经济损失，以及严重失去对个人信息的控制和/或造成个人信息泄露。
在没有明确意图伤害用户的情况下发出不必要的凭证请求，例如在线商店要求用户使用驾驶执照注册，而不是使用通用电子邮件和通行密钥或联合凭证。这可能导致无法或不愿向站点共享此类凭证的用户被排斥， Web 上提示体验恶化，并增加意外数据泄露的风险。
出于有效目的请求过量信息，违背数据最小化原则。一个常见例子是为年龄验证收集用户的完整国家身份证件，而不是依赖选择性披露和年龄谓词。

这里的一个挑战是确定什么构成“有效”目的，以及哪些请求因而是“不必要的”，这需要凭证交换中所有相关方的参与。

理想情况下，验证者会自我约束其对凭证的请求。然而，从用户代理的角度来看，验证者是潜在攻击者，并且可能不会在其设计中考虑用户的最大利益。Digital Credentials API 基于这样的假设运行：所有验证者都可能具有促使其发起不必要请求和滥用的动机，并据此保护用户。
用户代理负责保护其用户免受 Web 上危险内容和权限请求的影响，并且可以代表用户进行干预，主动拒绝请求或要求预授权。为支持这一点，本规范要求凭证请求可由用户代理读取（即，不对验证者进行端到端加密，参见 5. 协议和6.2 准备凭证请求）。
签发者和立法者可能会决定，将（特别是政府签发的）凭证的使用限制为具有目的证明的特定验证者。凭证管理器可能会被法律或策略要求执行这些限制。
是否共享其个人信息的最终决定权在用户手中，这就是为什么该 API 要求用户代理向用户呈现凭证选择器，并且其他各方还可能额外要求确认或同意。

若要更详细地探讨如何确定和处理不必要的使用，将政府签发的凭证与其他凭证分开考虑是合理的，因为它们在数据的敏感性、滥用可能造成的潜在伤害，以及法律和监管考量方面可能存在差异。

适用于这两类凭证的风险缓解和确保用户控制的一个关键组成部分，是用户代理检查凭证请求元数据，并基于该元数据做出决策或进行 UI 呈现的能力。本规范通过协议要求来确保此类用户代理访问，即传输未加密的请求并包含相关信息（参见5. 协议和6.2 准备凭证请求）。

政府签发的数字凭证包括旅行证件、个人执照、福利和公共卫生计划证明、车辆登记，以及其他由政府机关签发的文件，或其他表示这些信息的文件。这些文件高度敏感，因为它们可能包含永久、不可撤销、唯一的标识符，而这些标识符对于个人身份以及与重要公共服务交互的能力至关重要。

这些凭证对用户和攻击者的高价值意味着存在显著的窃取风险，并且向未授权第三方泄露会带来显著的潜在危害。这包括出于跟踪和个性化目的请求政府身份信息。

政府凭证在线可用性提高所带来的一个主要顾虑是杰文斯悖论，即通过降低访问摩擦而增加对凭证需求的可能性。这种效应并非由数字凭证 API 本身固有造成，而是由整个生态系统中数字凭证采用率不断提高所造成；不过，它很可能会因用户代理实现数字凭证 API 而获得额外动力。因此，实现该 API 的用户代理需要考虑这一效应，因为它可能给用户带来有害结果：

信息泄露风险增加，并最终导致 Web 上的用户体验可信度降低。当大量服务以不安全方式访问并存储政府签发的凭证（即未维护加密或未能保护私钥）时，数据泄露和未授权访问的可能性也会增加。即使是看似非识别性的信息，例如出生日期和邮政编码，一旦组合起来，也可能在统计上识别个人。
当大量网站提示用户共享个人信息时，用户会产生提示疲劳并失去信任。
监控潜力增加，并限制在线服务的假名使用。验证方和签发方或其他方之间的串通，可能导致能够密切监视用户在 Web 上的活动，并对该个人采取不利行动。即使没有采取行动，仅仅存在被监控的可能性也可能造成焦虑、不适和行为变化，例如自我抑制和自我审查，从而影响个人自主权和言论自由。
对无法或不愿提供这些凭证的个人进行排斥和歧视，禁止他们参与以前不需要政府签发凭证的服务，例如 Web 上的论坛和社交媒体平台。

上述政府签发数字凭证的风险提出了一项挑战，这无法由生态系统中的单一参与者解决，并且需要在各个主权国家内部围绕通过现实世界凭证访问在线服务的风险和收益开展更广泛的政策讨论。

希望签发数字凭证的政府也能制定法律和法规，明确界定这些凭证能够如何以及出于何种目的使用。参与交换的所有各方，无论是否有法律义务这样做，都被建议支持任何政府验证方认证方案（如果存在）。对验证方认证方案（例如 EUDI 访问和注册证书）的支持（及集成）可以缓解不必要凭证请求泛滥的风险。然而，不能保证存在此类方案，这会显著增加凭证交换中的风险。

实现数字凭证 API 的用户代理还可以采取其他实际步骤，以降低风险、提高用户理解，并防止某些类型的危害：

仅支持能够实现选择性披露和其他数据最小化技术的协议，可以降低信息泄露的影响和可能性，并在权限和同意流程中为用户提供更好的上下文。
支持允许不可链接性机制的协议，例如零知识证明，可以通过隐藏签发者，防止基于验证者的监视和潜在歧视。
提供有用的上下文和清晰易懂的权限流程，将帮助用户更好地决定是否接受凭证交换，这可以降低在没有具体用户需求的情况下发起的交换请求的可行性。

此外，用户代理设计一种能够考虑缺少这些缓解措施的权限体验至关重要，例如，在没有任何验证者认证方案的情况下交换来自政府凭证的个人信息。建议对这些类型的交换应用更高程度的阻力，以及清晰的用户消息，以突出所涉及的风险。

非政府签发的凭证包括所有其他非政府签发且不表示政府签发文件的数字文档、证书和证明。这可能包括在职证明、（非政府）教育凭证，或电影票。尤其是，其交换很可能受法律和法规限制较少。虽然这些文件通常不表现出与政府签发凭证相同的风险，但它们也可能包含可识别或敏感信息。

非政府凭证被窃取和泄露的影响及可行性，在很大程度上取决于每种具体凭证类型的内容。一般而言，这可能导致失去控制权以及敏感私人信息暴露，还可能导致冒充和数据盗窃，从而增加对受影响个人进行后续攻击的可能性。

非政府凭证的灵活性和缺乏监管，为跨站点跟踪和通过长期标识符（例如电子邮件地址或电话号码）链接身份带来了滥用可能。参与基于数字凭证的跟踪方案的验证方可能会创造用户激励，使用户在没有充分理解其隐私影响的情况下，接受跨多个站点共享标识符凭证（Web 的“会员卡”）。

即使不愿在此类方案中共享其信息的用户也可能受到提示疲劳影响，并可能面临被排斥而无法使用这些服务的风险。

对于非政府签发的凭证，建议用户代理理解所请求的凭证格式及其隐私属性，并构建一个风险框架，用于决定向用户显示的上下文，以及适合每种凭证类型的摩擦程度。参与这些凭证交换的协议和格式通常预期支持选择性披露和不可链接性等特性，但这些特性在信息交换中可能并不总是合适或必要，尤其是在涉及低风险凭证（例如电影票）时。

能够识别被请求凭证类型的用户代理被鼓励定制其许可体验，以最好地适配所请求的凭证，并帮助用户理解共享该凭证的后果。

用户代理不应被期望理解所有凭证请求。不识别所请求凭证类型的用户代理，建议在其权限体验中显著增加用户阻力，并向用户清楚传达与网站共享未知凭证的风险。请注意，这可能需要在不同用户代理之间进行集成，以应用适当程度的阻力和透明度。例如，浏览器可能会将有关凭证请求的知识委托给操作系统，而操作系统可能要求凭证管理器注册已知凭证类型，并拒绝针对未知凭证类型的交换请求。

议题 100：考虑针对用户代理请求验证应用健壮性原则 discussion privacy-considerations

向用户提供适当透明度的需求，与使生态系统能够在没有明确用户代理认可的情况下开发新凭证格式的愿望相冲突。

议题 267：举报凭证请求滥用 privacy-tracker privacy-considerations

考虑为发出不必要和滥用性请求的验证方建立一个可互操作的滥用举报系统。

虽然该 API 确保在没有许可提示的情况下绝不会共享任何用户数据（参见 [[[#user-permission-and-transparency|用户许可与透明度]] 一节），但数字凭证 API 可能返回的现实世界标识符所具有的持久性和唯一性，使其成为跟踪器和指纹识别者的潜在目标。

即使使用选择性披露，攻击者也可能将来自数字凭证的数据（例如用户的年龄，或凭证颁发者、时间戳；参见 [[[#leaking-incidental-data|泄露附带数据]] 一节）组合起来，以重新识别用户和/或对用户进行指纹识别。

对第三方攻击者（例如嵌入在验证方页面上但并未为跟踪目的与其主动协作的脚本）而言，这种攻击可能更难，因为响应加密是强制性的，并且响应应当在验证方服务器上解密。因此，验证方可以确保不将解密后的信息反射回客户端 JavaScript。然而，并非所有验证方都会选择这样做。

为确保凭证的真实性，向验证方出示凭证通常会包含比验证方请求访问的内容更多的信息。它通常至少包含签发方和凭证管理器的签名，并可能包含其他元数据。

这些附加信息可用于重新识别和指纹识别用户，当进行原本不可链接的出示时，这一点尤其相关。

虽然数字凭证 API 不控制凭证响应的内容，但用户代理可以通过清晰突出显示除了所请求内容外哪些信息可能会被共享给验证方，并更广泛地通过识别和阻止验证方经由 API 进行指纹识别，来帮助保护用户免受这种类型的跟踪。

数字凭证 API 通过 userAgentAllowsProtocol() 暴露关于用户代理支持哪些出示和签发协议的信息。它通过不基于例如用户设备上安装了哪些凭证管理器应用来自定义响应，来缓解浏览器指纹识别以及暴露关于用户设备配置的信息。因此，返回的信息充其量相当于一个用户代理版本。

数字凭证 API 不允许站点在未先经过用户许可流程的情况下获知某个凭证是否可用。暴露凭证的存在会对用户隐私构成风险，因为凭证的存在属于个人信息，用户可能并不愿意与站点共享；并且结合其他信号后，可能被用于在未经用户许可的情况下识别用户。这也会对言论自由构成风险，因为网站可能越来越多地开始要求用户出示这些凭证才能访问服务，从而排除不愿出示凭证的个人。

议题：进行中的工作

数字凭证 API 使得通过凭证与网站共享高度个人化、敏感且有风险的用户信息成为可能，这可能赋予通过永久、唯一、不可撤销、跨上下文标识符在线上和线下跟踪用户的能力。它还会暴露用户浏览活动的一部分，以及他们向特定网站和/或凭证管理器表明身份的意图。用户代理在凭证请求中的一项关键责任，是从用户那里获得继续进行信息交换的许可。

用户要就是否继续进行凭证交换作出知情决定，需要以下重要上下文细节：

请求凭证的验证方的源。
正在请求的信息，或响应请求会暴露的信息。
出示这些信息是否会启用跟踪。
哪些凭证管理器可用于满足凭证请求。
将使用哪个凭证来共享所请求的信息。

建议用户代理在其实现中确保在发生任何与用户相关的信息交换之前，将所列细节完全披露给用户。

议题 252：我们是否应当规范性地定义权限提示的元素？privacy-considerations

这些是否应当在规范中成为规范性内容？

议题 44：API 请求应当向站点提供其解释所请求凭证信息为何以及如何被使用所需的内容 enhancement pending closure privacy-tracker

该 API 是否应当被设计为让站点可以提供上下文内说明？

议题 286：多个出示请求（和响应）的隐私考量 privacy-tracker privacy-considerations

我们需要描述处理多个凭证出示请求和响应时的顾虑、权衡以及可能的缓解措施。

根据用户系统的技术架构， “用户代理”的定义很可能包括软件栈中多个协作层，例如浏览器和操作系统。这些层的最高优先级必须是安全且信息充分的用户许可体验。因此，集成对用户安全可能至关重要。某些层可能持有其他层无法访问的信息，例如用户凭证的可用性。过度提示或在上下文不足的情况下提示，可能导致可被利用的混淆和提示盲视。

因此，提示用户授予许可的用户代理被鼓励在其认为安全的情况下集成软件层，以获得理想的用户体验。例如，如果浏览器信任操作系统的 API 合同会显示适当的提示，那么浏览器自身可以不显示提示。

作为用户许可流程的一部分，用户代理需要确保用户保留选择是否将凭证请求转发给凭证管理器以及选择哪个凭证管理器的权力。这是因为信息披露会作为请求的一部分发生，并且凭证管理器在请求时有能力保留或共享这些信息。

出于用户代理自动化和应用测试的目的，本文档为 WebDriver BiDi 规范定义了扩展模块。用户代理对其提供支持是可选的。

digitalCredentials 模块包含用于管理和模拟凭证管理器在 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 和 [[Create]](origin, options, sameOriginWithAncestors) 调用期间的远端行为的命令。

CDDLdigitalCredentials.VirtualWalletAction = "decline" / "respond" / "wait" / "clear"

digitalCredentials.SetVirtualWalletBehaviorParameters = {
  action: digitalCredentials.VirtualWalletAction,
  ? context: text,
  ? protocol: text,
  ? response: { * text => any },
}

digitalCredentials.VirtualWalletAction 类型表示不同类型的虚拟钱包动作。

"decline": 虚拟钱包模拟用户取消或拒绝，中止该请求。
"respond": 虚拟钱包模拟一次成功的用户交互，并返回预定义的凭证响应。
"wait": 虚拟钱包模拟一个活动的、待处理的提示，实际上使活动 promise 保持未决状态，以测试超时或并发请求处理。
"clear": 清除活动的虚拟钱包行为。

命令类型

CDDLdigitalCredentials.SetVirtualWalletBehavior = (
  method: "digitalCredentials.setVirtualWalletBehavior",
  params: digitalCredentials.SetVirtualWalletBehaviorParameters
)

返回类型

CDDLdigitalCredentials.SetVirtualWalletBehaviorResult = EmptyResult

给定 session 和 command parameters， digitalCredentials.setVirtualWalletBehavior 命令的远端步骤为：

令 action 为 command parameters["action"]。
如果存在，令 context 为 command parameters["context"]，否则为 null。
如果存在，令 protocol 为 command parameters["protocol"]，否则为 null。
如果存在，令 response 为 command parameters["response"]，否则为 null。
如果 action 为 "respond"：
1. 如果 protocol 为 null 或 response 为 null，则返回一个错误，其错误代码为invalid argument。
2. 如果 protocol 不是 DigitalCredentialProtocol 的枚举值，则返回一个错误，其错误代码为invalid argument。
3. 将 response序列化为 JSON 字符串。
4. 如果序列化产生异常，则返回一个错误，其错误代码为invalid argument。
否则：
1. 如果 response 不是 null 或 protocol 不是 null，则返回一个错误，其错误代码为invalid argument。
如果 action 为 "clear"：
1. 如果 context 不是 null，则从 WebDriver session 的活动虚拟钱包行为中移除 context 对应的条目。
2. 否则，将 WebDriver session 的活动虚拟钱包行为设置为 null。
否则：
1. 令 behavior 为一个由 (action, protocol, response) 组成的元组。
2. 如果 context 不是 null，则将浏览上下文 ID context 对应的 WebDriver session 的活动虚拟钱包行为设置为 behavior。
3. 否则，将 WebDriver session 的默认活动虚拟钱包行为设置为 behavior。
返回带有数据 null 的成功。

要在给定一个 Promise promise 和一个全局对象 global 的情况下处理虚拟钱包行为，运行以下步骤：

如果用户代理不处于自动化控制下，则返回 false。
令 context ID 为 global 的浏览上下文的 ID。
令 behavior 为当前 WebDriver session 针对 context ID 的活动虚拟钱包行为。
如果 behavior 为 null，则将 behavior 设置为当前 WebDriver session 的默认活动虚拟钱包行为。
如果 behavior 为 null，则返回 false。
令 (action, protocol, response) 为 behavior。
如果 action 为 "wait"，则返回 true。
如果 action 为 "decline"：
1. 使用 "NotAllowedError" DOMException拒绝 promise。
2. 返回 true。
如果 action 为 "respond"：
1. 令 JSON string 为序列化 response 的结果。
2. 令 JS object 为在给定 global 的相关 realm 时，解析 JSON string 的结果。
3. 令 credential 为一个新的 DigitalCredential 实例。
4. 将 credential 的protocol 属性设置为 protocol。
5. 将 credential 的data 属性设置为 JS object。
6. 在给定 global 的DOM 操作任务源上排入一个全局任务，以使用 credential兑现 promise。
7. 返回 true。

中止算法 §6.
中止信号 §6.
中止凭证请求 §6.4
aborting §6.1
action §13.1.1
活动 promise §6.
活动虚拟钱包行为 §13.1.2.1
API 泛洪 §10.1.1
"clear" §13.1.1
context §13.1.1
convert request protocol §5.1
[[Create]](origin, options, sameOriginWithAncestors) DigitalCredential 的内部槽 §8.3
凭证请求 §4.
凭证请求协调器 §6.
凭证响应 §4.
data
- DigitalCredentialGetRequest 的成员 §7.3.2
- DigitalCredentialCreateRequest 的成员 §7.6.2
- DigitalCredential 的属性 §7.7.2
"decline" §13.1.1
digital
- CredentialRequestOptions 的成员 §7.1.1
- CredentialCreationOptions 的成员 §7.4.1
数字凭证 §4.
数字凭证选择器 §4.
"digital-credentials-create" §9.
"digital-credentials-get" §9.
DigitalCredential 接口 §7.7
DigitalCredentialCreateRequest 字典 §7.6
DigitalCredentialCreationOptions 字典 §7.5
DigitalCredentialGetRequest 字典 §7.3
DigitalCredentialIssuanceProtocol 枚举 §7.8.3
DigitalCredentialPresentationProtocol 枚举 §7.8.2
DigitalCredentialProtocol §7.7
DigitalCredentialRequestOptions 字典 §7.2
digitalCredentials.SetVirtualWalletBehavior §13.1.2.1
"digitalCredentials.setVirtualWalletBehavior" §13.1.2.1
digitalCredentials.SetVirtualWalletBehaviorParameters §13.1.1
digitalCredentials.SetVirtualWalletBehaviorResult §13.1.2.1
digitalCredentials.VirtualWalletAction §13.1.1
[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) DigitalCredential 的内部槽 §8.1
[[discovery]] DigitalCredential 的内部槽 §8.5
这些类型的示例 §1.
处理虚拟钱包行为 §13.2
idle §6.1
范围内威胁 §10.1.1
发起凭证请求 §6.6
交互状态 §6.1
签发协议 §4.
签发请求 §4.
签发请求数据 §4.
签发响应 §4.
method §13.1.2.1
"openid4vci-v1" DigitalCredentialIssuanceProtocol 的枚举值 §5.
"openid4vp-v1-multisigned" DigitalCredentialPresentationProtocol 的枚举值 §5.
"openid4vp-v1-signed" DigitalCredentialPresentationProtocol 的枚举值 §5.
"openid4vp-v1-unsigned" DigitalCredentialPresentationProtocol 的枚举值 §5.
"org-iso-mdoc" DigitalCredentialPresentationProtocol 的枚举值 §5.
范围外威胁 §10.1.2
params §13.1.2.1
准备凭证请求 §6.2
出示协议 §4.
出示请求 §4.
出示请求数据 §4.
出示响应 §4.
protocol
- DigitalCredentialGetRequest 的成员 §7.3.1
- DigitalCredentialCreateRequest 的成员 §7.6.1
- DigitalCredential 的属性 §7.7.1
- 定义 §13.1.1
协议标识符 §4.
拒绝凭证请求并附带 §6.5
请求上下文 §7.8.1
请求篡改 §10.1.1
requesting §6.1
requests
- DigitalCredentialRequestOptions 的成员 §7.2.1
- DigitalCredentialCreationOptions 的成员 §7.5.1
- 定义 §7.8.1
"respond" §13.1.1
response §13.1.1
[[Store]](credential, sameOriginWithAncestors) DigitalCredential 的内部槽 §8.2
受支持的出示和签发协议表 §5.
text §13.1.1
顶级源 §7.8.1
[[type]] DigitalCredential 的内部槽 §8.4
未授权跨源访问 §10.1.1
用户代理允许协议 §7.7.3
userAgentAllowsProtocol() DigitalCredential 的方法 §7.7.3
验证凭证请求 §6.3
"wait" §13.1.1

[CREDENTIAL-MANAGEMENT] 定义了以下术语：
- [[Create]](origin, options, sameOriginWithAncestors) （用于 Credential）
- [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) （用于 Credential）
- [[Store]](credential, sameOriginWithAncestors)（用于 Credential）
- 创建一个 Credential
- create()（用于 CredentialsContainer）
- Credential 接口
- 凭证选择器
- 凭证管理器
- CredentialCreationOptions
- CredentialRequestOptions
- CredentialsContainer 接口
- get()（用于 CredentialsContainer）
- mediation（用于 CredentialRequestOptions）
- mediation（用于 CredentialCreationOptions）
- 请求一个 Credential
- required（用于 CredentialMediationRequirement）
- signal（用于 CredentialRequestOptions）
- signal（用于 CredentialCreationOptions）
- 用户中介
DOM Standard 定义了以下术语：
- 中止原因（用于 AbortSignal）
- 已中止（用于 AbortSignal）
- AbortSignal 接口
- 添加（用于 AbortSignal）
- Document
- 移除（用于 AbortSignal）
- 信号中止（用于 AbortController）
- 信号（用于 AbortController）
HTML Standard 定义了以下术语：
- 活动文档（用于 navigable）
- 关联的 Document
- 浏览上下文
- 子可导航体
- 消耗用户激活
- DOM 操作任务源
- 环境设置对象
- 完全活动（用于 Document）
- 具有用户注意的顶级可遍历体的完全活动后代（用于 Document）
- iframe 元素
- 并行
- object 类型
- 源（用于环境设置对象）
- 排入一个全局任务
- 相关全局对象
- 相关 realm
- 相关设置对象
- 安全上下文
- 顶级可遍历体
- 瞬态激活
Infra Standard 定义了以下术语：
- 追加（用于 list）
- ASCII 数字
- ASCII 小写字母
- 断言
- 码点
- 继续（用于 iteration）
- 对每个（用于 list）
- 为空（用于 list）
- 项（用于 struct）
- 列表
- 将 JSON 字符串解析为 JavaScript 值
- 将 JavaScript 值序列化为 JSON 字符串
- 将 Infra 值序列化为 JSON 字符串
- 字符串
- 结构
- 用户代理
[PERMISSIONS] 定义了以下术语：
- 明示许可
- 强大特性
[PERMISSIONS-POLICY] 定义了以下术语：
- 'self' （用于默认 allowlist）
- 默认 allowlists（用于策略控制特性）
- 策略控制特性
[PRIVACY-PRINCIPLES] 定义了以下术语：
- 用户代理职责
[VC-DATA-MODEL] 定义了以下术语：
- 声明
- 持有者
- 签发方
- 主体
- 验证方
[WEBDRIVER] 定义了以下术语：
- 错误
- 错误代码
- invalid argument
- 远端步骤
- session
- 成功
Web IDL Standard 定义了以下术语：
- 一个新 promise
- 以……拒绝的 promise
- AbortError 异常
- boolean 类型
- [Default] 扩展属性
- 默认 toJSON 步骤
- DOMException 接口
- DOMString 接口
- 枚举值
- 异常
- [Exposed] 扩展属性
- 接口对象
- 接口
- InvalidStateError 异常
- NotAllowedError 异常
- object 类型
- OperationError 异常
- Promise 接口
- ReferenceError 异常
- 拒绝
- 兑现
- [SameObject] 扩展属性
- [SecureContext] 扩展属性
- 序列
- this
- 抛出（用于 exception）
- TypeError 异常

数字凭证

摘要

本文档状态

1. 引言

2. 用法示例

2.1 特性检测

2.2 检查协议是否被允许

2.3 请求数字凭证

2.4 签发数字凭证

2.5 跨源请求数字凭证

2.6 跨源签发数字凭证

3. 范围

4. 术语

5. 协议

5.1 转换请求协议

6. 凭证请求协调器

6.1 交互状态

6.2 准备凭证请求

6.3 验证凭证请求

6.4 中止凭证请求

6.5 拒绝凭证请求

6.6 发起凭证请求

7. 数字凭证 API

7.1 对 CredentialRequestOptions 字典的扩展

7.1.1 digital 成员

7.2 DigitalCredentialRequestOptions 字典

7.2.1 requests 成员

7.3 DigitalCredentialGetRequest 字典

7.3.1 protocol 成员

7.3.2 data 成员

7.4 对 CredentialCreationOptions 字典的扩展

7.4.1 digital 成员

7.5 DigitalCredentialCreationOptions 字典

7.5.1 requests 成员

7.6 DigitalCredentialCreateRequest 字典

7.6.1 protocol 成员

7.6.2 data 成员

7.7 DigitalCredential 接口

7.7.1 protocol 成员

7.7.2 data 成员

7.7.3 userAgentAllowsProtocol() 方法

7.8 支持性数据结构

7.8.1 请求上下文结构

7.8.2 DigitalCredentialPresentationProtocol 枚举

7.8.3 DigitalCredentialIssuanceProtocol 枚举

8. 与 凭证管理 1 级集成

8.1 [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 内部方法

8.2 [[Store]](credential, sameOriginWithAncestors) 内部方法

8.3 [[Create]](origin, options, sameOriginWithAncestors) 内部方法

8.4 [[type]] 内部槽

8.5 [[discovery]] 内部槽

8.6 用户许可

9. Permissions Policy 集成

10. 安全考量

10.1 威胁模型

10.1.1 范围内威胁

10.1.2 范围外威胁

10.2 缓解措施

11. 隐私考量

11.1 设计考量和替代方案

11.2 隐私谱系

11.3 出示协议和凭证格式

11.3.1 面向用户隐私的出示协议考量

11.3.1.1 选择性披露

11.3.1.2 不可链接的出示

11.3.1.3 “回拨”机制

11.3.1.4 不可链接的撤销

11.3.1.5 对用户透明度、许可和同意的支持

11.3.1.6 对验证方授权的支持

11.3.1.7 加密凭证响应

11.4 不必要的凭证请求

11.4.1 政府签发的凭证

11.4.1.1 政府凭证被窃取和泄露的风险

11.4.1.2 政府凭证请求泛滥的风险

11.4.1.3 缓解不必要的政府凭证请求

11.4.2 非政府签发的凭证

11.4.2.1 非政府凭证被窃取和泄露的风险

11.4.2.2 非政府凭证请求泛滥的风险

11.4.2.3 缓解不必要的非政府凭证请求

11.4.2.4 举报滥用

7.1 对 `CredentialRequestOptions` 字典的扩展

7.1.1 `digital` 成员

7.2 `DigitalCredentialRequestOptions` 字典

7.2.1 `requests` 成员

7.3 `DigitalCredentialGetRequest` 字典

7.3.1 `protocol` 成员

7.3.2 `data` 成员

7.4 对 `CredentialCreationOptions` 字典的扩展

7.4.1 `digital` 成员

7.5 `DigitalCredentialCreationOptions` 字典

7.5.1 `requests` 成员

7.6 `DigitalCredentialCreateRequest` 字典

7.6.1 `protocol` 成员

7.6.2 `data` 成员

7.7 `DigitalCredential` 接口

7.7.1 `protocol` 成员

7.7.2 `data` 成员

7.7.3 `userAgentAllowsProtocol()` 方法

7.8.2 `DigitalCredentialPresentationProtocol` 枚举

7.8.3 `DigitalCredentialIssuanceProtocol` 枚举

8. 与凭证管理 1 级集成

13.1 `digitalCredentials` 模块

13.1.2.1 `digitalCredentials.setVirtualWalletBehavior` 命令

A.1 由本规范定义的术语