数字凭证

摘要

本文档规定了一个 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("Failed to verify credential");
      }

      // 呈现验证结果
      displayVerificationResult(await response.json());

    } catch (error) {
      console.error("Error requesting digital credential:", 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 issuing digital credential:", error);
    }
  });
</script>

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

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

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

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

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

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

本节为非规范性内容。

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

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

以下事项不在本规范范围内：

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

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

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

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

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

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

凭证请求协调器：

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

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

注

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

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

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

给定一个Window global、一个源 origin、一个序列，其值为DigitalCredentialGetRequest 或一个序列，其值为DigitalCredentialCreateRequest requests，以及一个可选的 AbortSignal signal，要准备凭证请求：

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

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

令 supportedRequests 为一个新的空列表。
对于 requests 中的每个 request：
1. 令 protocol 为给定 request 执行转换请求协议的结果。
2. 如果 protocol 为失败，继续。
3. 如果给定 protocol 执行用户代理允许协议返回 false，继续。
4. 将 request追加到 supportedRequests。
返回 supportedRequests。

注

筛选发生在消耗用户激活之前，这样协议均不受支持的请求会以TypeError拒绝，而不会消耗用户激活。后续在验证凭证请求中的验证可以安全地假定所有剩余请求都使用受支持的协议。

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

令 validatedRequests 为一个新的空列表。
对于 requests 中的每个 request：
1. 如果 request 是DigitalCredentialGetRequest，令 data 为 request 的data；或者，如果 request 是 DigitalCredentialCreateRequest，则为 request 的 data。
2. 将 data序列化为 JSON 字符串。
3. 如果序列化产生异常，抛出该异常。
4. 根据 request 的出示协议或签发协议或其他条件，验证 request 的出示请求数据或签发请求数据。
  除协议定义的要求外，用户代理还可能根据本地策略、配置或用户的选择应用验证条件。例如，用户代理可能拒绝请求特定凭证属性的请求。
  
  什么构成验证失败由具体协议决定，但如何将此类失败归类为异常类型则定义如下：
  
  注：协议特定的验证细节
  
  验证包括确认 request 的出示请求数据或签发请求数据符合指定出示协议或签发协议的要求。有关详细信息，包括潜在的验证失败原因，以及实现者在验证期间需要考虑的任何安全和隐私考虑，请参阅具体出示协议或签发协议的规范。
  1. 如果验证失败：
    1. 令 error 按如下方式确定：
      
      用户代理基于本地策略、配置或用户的选择不允许该请求：
      
      一个创建的“NotAllowedError” DOMException。
      
      注
      
      “NotAllowedError” 被有意设计为与用户取消操作时返回的错误无法区分，这样网站就无法判断请求是被用户还是被用户代理拒绝，也无法推断有关用户配置或凭证的任何信息。
      
      由于与用户无关的安全原因，例如上下文或传输，不允许该请求：
      
      一个创建的“SecurityError” DOMException。
      
      请求数据格式错误或无效：
      
      一个创建的 TypeError。
      
      否则：
      
      一个创建的“OperationError” DOMException。
    2. 抛出 error。
  2. 否则，将 request追加到 validatedRequests。
返回 validatedRequests。

给定一个 JavaScript 值 error，要中止凭证请求：

如果凭证请求协调器的活动 promise为 null，返回。
令 activePromise 为凭证请求协调器的活动 promise。
如果凭证请求协调器处于“请求中”交互状态：
1. 将凭证请求协调器的交互状态设置为“中止中”。
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. 将凭证请求协调器的交互状态设置为“空闲”。

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

令 topLevelOrigin 为 document 的顶级可遍历对象的活动文档的相关设置对象的源。
令 requestData 为一个新的请求上下文，其请求为 validatedRequests，且顶级源为 topLevelOrigin。
并行地：
1. 使用 requestData 显示一个数字凭证选择器，并等待以下结果之一：
  - 用户选择一个能够满足该请求的数字凭证或持有者。
  - 用户取消操作。
  - 平台遇到错误。
  当用户代理与位于另一设备上的凭证管理器通信时，用户代理推荐使用客户端到验证器协议（CTAP）。
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 为字符串出示响应或由持有者返回的字符串签发响应。
    
    注：为什么响应是字符串
    
    响应是字符串，因为用户代理负责在正确的领域中将其解析为 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. 将凭证请求协调器的交互状态设置为“空闲”。

数字凭证 API 利用凭证管理第 1 级规范，使用户代理能够协调签发和出示数字凭证。

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

此外，该 API 还允许请求签发一个数字凭证，这随后会向用户呈现一个凭证管理器选择器，允许用户选择一个凭证管理器来保存该数字凭证。这是通过调用 navigator.credentials.create() 方法实现的，该方法运行凭证管理第 1 级的创建凭证算法。然后，该算法回调本规范的DigitalCredential 接口的 [[Create]](origin, options, sameOriginWithAncestors) 内部方法。

通过此 API 进行的数字凭证签发与数字凭证出示略有不同。响应数据包含持有者的凭证管理器根据签发协议定义返回的协议特定响应，而并不表示实际签发的数字凭证本身。

有关如何与凭证管理第 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);
};

DigitalCredential 实例是源绑定的。

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

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

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

注

此方法不传达底层操作系统/平台对出示协议或签发协议的支持情况。

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

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

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

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

本规范中支持 DigitalCredential 的数据结构，例如枚举。

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

请求: 一个由已验证凭证请求组成的列表。
顶级源: 一个环境设置对象的源。

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

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

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

WebIDLenum DigitalCredentialIssuanceProtocol {
  "openid4vci-v1",
};

本节为非规范性内容。

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

注

其他依赖于协议、凭证管理器实现、操作系统或传输安全性的安全考虑被描述为预期或前置条件，但除非已经以规范性方式规定，否则这些内容并非本规范的规范性要求。

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

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

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

请求篡改: 能够在不安全上下文中注入或修改页面内容的网络攻击者试图在处理之前更改 DigitalCredentialGetRequest 或DigitalCredentialCreateRequest。
API 泛滥: 恶意网站试图通过快速、重复发出请求来压垮 API，以耗尽系统资源、迷惑用户、创建不必要的凭证交互，或导致提示疲劳，从而降低用户体验。这包括在不适当的时机发出请求，例如页面加载期间或缺乏有意义的用户上下文时。
未经授权的跨源访问: 恶意网站试图通过嵌入的第三方内容（例如 iframe）请求或签发数字凭证，而没有获得嵌入网站的明确许可，这可能会导致凭证收集或对敏感用户数据的未经授权访问。
针对底层平台的恶意载荷: 恶意网站试图利用底层操作系统或凭据管理器中的漏洞，方法是通过 API 传递精心构造或格式错误的协议请求。

超出范围的威胁是指由协议、凭据管理器、操作系统平台安全机制或传输层处理的威胁。即使这些威胁“超出范围”，它们仍然具有相关性，因为它们会影响凭据出示和签发的端到端安全性。以下内容定义了本规范的超出范围的威胁：

操作系统或设备遭入侵: 获得用户操作系统或设备硬件控制权的攻击者可能绕过用户代理的保护措施，直接从存储中提取敏感凭据数据，或操纵 API 调用。此威胁由操作系统平台安全性和硬件支持的密钥库来应对。
恶意凭据管理器: 用户可能会安装，或因机构强制要求或基本服务而被迫使用某个凭据管理器，该管理器会故意泄露数据、未能安全加密凭据，或无视用户同意。虽然该 API 在钱包选择之前通过明确的用户许可来保护用户（参见 11.6 用户许可与透明度），但一旦用户授权某个凭据管理器处理请求，该 API 就无法约束其内部行为。缓解此风险依赖于操作系统平台安全性、应用商店审核，以及用于监管钱包提供商的法律/监管框架。
协议和格式漏洞: 所使用的特定呈现协议、签发协议或凭据格式中的弱点（例如，加密缺陷、不安全算法、缺少重放保护或缺少请求认证）可能允许攻击者拦截、伪造或篡改传输中的凭据。缓解措施主要发生在协议、格式和传输层（例如，强制响应加密、请求签名以及 TLS）。虽然该 API 不定义特定于格式的密码学，也不检查协议载荷的密码学安全性，但它会对所支持的协议实施基线安全标准（例如要求响应加密并鼓励使用已签名请求），以引导请求通过最安全的路径。

以下缓解措施通过规范中的规范性要求应对范围内威胁。

Digital Credential API 的 WebIDL 接口仅在安全上下文中公开，从而降低通过篡改的风险，这些篡改来自不安全上下文（例如，通过网络注入恶意脚本）。有关更多信息，请参阅安全上下文规范的 § 5 安全注意事项一节。

为了降低针对底层平台的恶意载荷风险，用户代理使用JSON 序列化将请求参数传递给凭据管理器（参见验证凭据请求）。底层平台和凭据管理器负责在对这些特定于协议的 JSON 载荷执行操作之前，对其进行可靠的解析和验证。

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

瞬态激活： [[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) 和 [[Create]](origin, options, sameOriginWithAncestors) 方法都会消耗用户激活，从而防止在没有用户交互的情况下自动或重复发出请求。
始终要求中介：该 API 隐式地将用户中介设为 "required" （参见DigitalCredential 接口），确保每次凭据操作都通过平台的凭据选择器接口获得用户许可。

有关防止滥用凭据请求的其他指导，请参阅凭据管理第 1 级规范的 § 7 隐私注意事项一节。不过需要注意的是，这些保护措施存在局限性，因为网站仍可能采用暗黑模式来诱导用户进行不必要的交互，从而触发凭据请求。

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

此外，来自不透明源的请求会被拒绝。由于 DigitalCredential 实例是源绑定的，因此从不透明源请求或创建数字凭据的调用（例如 data: 文档，或在没有 allow-same-origin 的情况下被沙盒化的文档）会被凭据管理第 1 级拒绝，从而降低恶意从不受信任的环境中提取或欺骗的风险。

当出示协议提供一种对请求进行签名的方式时，强烈建议验证者使用该方式。

未签名的请求可能被运行在验证者自身页面中的脚本修改，例如由恶意浏览器扩展注入的脚本。该脚本可以更改所请求的内容，将一个范围有限的请求变成要求提供更多内容的请求，并且还可以替换用于加密响应的参数，使响应被加密给攻击者，而不是验证者。要求在安全上下文中使用该 API 并不能阻止这种情况，因为攻击者已经位于该上下文内部。对于未签名的请求，凭据管理器只能相信验证者已使自己的页面不包含此类脚本。另一方面，已签名的请求会为凭据管理器提供可供检查的内容，因此这种更改可以被检测到，而不会在未被察觉的情况下通过。

即便如此，只有当凭据管理器能够判断签名属于发出请求的验证者时，签名才有帮助。页面内的脚本可以使用自己的密钥对被修改的请求重新签名，因此除非能够依据一个已被识别为属于验证者的签名密钥来检查签名，否则签名无法防御此类攻击者。接受哪些签名密钥，以及如何建立这些密钥，由凭据所属的生态系统决定，而不是由本规范决定，并且已签名请求实际提供的保护取决于该决定。除了防止同一设备上的页面内篡改之外，请求签名在跨多个设备出示凭据时还提供关键的纵深防御（参见 10.4 跨设备安全与邻近性）。

Digital Credentials API 支持跨设备体验，在这种体验中，用户从辅助设备出示数字凭据，例如由智能手机充当凭据管理器，并将其出示给主设备，例如笔记本电脑。虽然具体的数据交换协议（例如，加密格式和传输方式）不在此 API 的范围内，但这类跨设备交互通常依赖已建立的协议，例如客户端到认证器协议 (CTAP)（客户端到认证器协议 (CTAP)）。

这些协议通过建立加密安全信道并强制要求物理邻近性（例如，通过蓝牙低功耗）来确保安全，以缓解远程中继攻击。关键的是，在跨设备流程中，凭据管理器不能天然信任由主设备转发的源字符串，因为主设备或其浏览器可能已被攻陷。因此，采用已签名请求的协议，其中验证者以加密方式证明其身份，相比仅依赖浏览器声明的源，能够提供显著更强的安全保证。

本节为非规范性内容。

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

随着本文档不断演进，本节仍在编写中。

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

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

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

期望参与数字凭证 API 设计和实现的各个工作组积极监测不断变化的隐私环境，并参与 API 相应的演进。

数字凭证 API 被设计用于对网站发出的数字凭证请求进行中介，并与凭证格式、其中包含的信息，以及用于交换该凭证的协议无关。这一设计以及其他关键设计选择源于一个目标：为用户提供相比现有替代方案（例如 [custom-schemes]）更安全且更注重隐私的凭证交换体验，同时仍与常见交换协议兼容，以便于采用。

API 提供验证者与持有者之间的连接接口，即用于启动凭据呈现协议以及用户切换到持有者应用程序以选择凭据的方式。过去用于此目的的解决方案包括二维码和自定义 URL 方案。如在 Web 上呈现凭据和身份呈现中的自定义方案相关问题所述，这些解决方案存在安全性、隐私性和可访问性方面的问题。

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

数字凭证 API 使用户代理能够代表用户进行中介协调（例如，以数字凭证选择器或凭证管理器选择器的形式），以便为请求提供上下文并防止立即暴露给持有者应用程序。它还对支持的协议实施某些最低要求，例如响应加密。

注

数字凭证 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：作为协议要求的可关联性和签发者参与隐私跟踪

此 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。不过，并非所有验证者都会选择这样做。

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

这些额外信息可能被用于重新识别用户和对用户进行指纹识别，这在原本不可关联的出示过程中尤其值得关注。

虽然 Digital Credentials API 不控制凭据响应的内容，但用户代理可以通过明确突出显示除所请求信息之外，哪些信息可能会与验证者共享，并且更广泛地通过识别和阻止验证者利用该 API 进行指纹识别，来帮助保护用户免受此类跟踪。

Digital Credentials API 通过 userAgentAllowsProtocol() 公开有关出示和签发协议是否受用户代理支持的信息。它通过不根据例如用户设备上安装了哪些凭据管理器应用程序来定制其响应，从而缓解浏览器指纹识别以及用户设备配置信息的泄露。因此，返回的信息至多等同于一个用户代理版本。

数字凭证 API 不允许网站在未先经过用户许可流程的情况下获知某个凭证是否可用。揭示凭证的存在会对用户隐私造成风险，因为凭证的存在本身就是用户可能不希望与网站共享的个人信息，而且与其他信号结合后，可能在未经用户许可的情况下用于识别用户。这也会对表达自由构成风险，因为网站可能会越来越多地要求用户出示这些凭证才能访问服务，从而排除不愿出示凭证的个人。

为确保此保护措施足够稳健，API 返回的错误不会通过可观察到的差异（例如不同的错误类型或时序攻击）泄露有关用户可用凭据的信息。例如，当用户没有匹配凭据时拒绝请求，与用户取消提示时拒绝请求会返回相同的通用错误。此外，为了在不依赖人为延迟的情况下防止时序攻击，用户代理在未找到匹配凭据时会向用户显示一个对话框（例如空的选择器或通知），从而使提示框被关闭的延迟无法与用户取消操作区分开来。

议题：仍在编写中

Digital Credentials API 能够通过凭据与网站共享高度个人化、敏感且存在风险的用户信息，并可能通过永久、唯一、不可撤销的跨上下文标识符，使网站能够在线上和线下跟踪用户。它还会向特定网站和/或凭据管理器透露用户的部分浏览活动以及其表明身份的意图。在凭据请求中，用户代理的一项关键职责是获得用户继续进行信息交换的许可。

用户要就是否继续进行凭据交换作出知情决定，需要了解的重要上下文详细信息包括以下内容：

请求凭据的验证者的源。
正在请求的信息，或响应该请求会披露的信息。
出示此信息是否会使跟踪成为可能。
哪些凭据管理器可用于满足凭据请求。
将使用哪个凭据来共享所请求的信息。

建议用户代理在实现中确保在交换任何与用户相关的信息之前，将上述详细信息完整披露给用户。

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

这些内容是否应该在规范中成为规范性要求？

议题 44：API 请求应向网站提供其说明为什么以及如何使用所请求凭证信息所需的信息 enhancement pending closure privacy-tracker

API 是否应被设计为允许网站提供与上下文相关的说明？

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

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

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

因此，提示许可的用户代理应在认为这样做安全的前提下集成软件层，以获得理想的用户体验。例如，如果浏览器信任操作系统的 API 契约会显示适当的提示，则可以不再自行显示提示。

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

Digital Credentials API 本身不会引入新的由浏览器管理的持久状态或本地存储机制。通过此 API 请求的凭据由外部凭据管理器或操作系统存储和管理。因此，当用户清除给定源或全局的浏览数据（例如 Cookie 或本地存储）时，通常不会清除或影响这些外部管理器中保存的凭据。

本节为非规范性内容。

此 API 与凭证格式和交换协议无关，并且将请求有效载荷（DigitalCredentialGetRequest 的 data 和 DigitalCredentialCreateRequest 的 data）以及响应有效载荷（DigitalCredential 的data）视为不透明数据。因此，该 API 未定义任何承载人类可读自然语言内容的字符串类型值：

它定义的字符串类型值，尤其是协议标识符，仅限于 ASCII（ASCII 小写字母、U+002D HYPHEN-MINUS 和ASCII 数字），并按完全相等进行比较。它们是机器标识符，而不是人类可读文本，因此规范化、大小写折叠以及语言或方向元数据均不适用。
所有有效载荷都以 JSON 文本和 JavaScript 值进行交换。当 JSON 字符串被编码为字节时（例如用于传输），它使用 UTF-8 编码。请求有效载荷使用将 JavaScript 值序列化为 JSON 字符串进行序列化，该操作会调用 ECMAScript JSON.stringify 操作，而响应使用将 JSON 字符串解析为 JavaScript 值进行解析。由于 JSON.stringify 会将孤立（未配对）的代理码点作为 \uXXXX 转义序列输出，因此序列化后的请求始终是格式良好且可用 UTF-8 编码的 JSON。
人类可读、可本地化的凭证内容（例如姓名或地址等凭证声明的值，包括它们在不同文字系统和语言中的表示）以不透明方式承载在凭证有效载荷中。其国际化由相关凭证格式以及出示协议或签发协议确定（例如 ISO/IEC 18013-5:2021 符合 ISO 的驾驶执照，第 5 部分：移动驾驶执照（mDL）应用中定义的格式，以及 OpenID 可验证出示 1.0等协议），本规范期望这些格式和协议在适当情况下提供语言和方向元数据以及本地化替代内容。
该 API 路由到平台且用户代理可能显示的唯一值，是发起请求的顶级源。向用户呈现源的主机，包括对国际化域名和双向文本的处理，遵循 URL 标准中的主机呈现指导，不属于本规范的范围。
在凭证交互期间向用户呈现的任何其他文本均由网站呈现（使用 HTML，该语言通过宿主语言提供语言和书写方向支持），或由平台的数字凭证选择器和凭证管理器选择器呈现。这些选择器不在本规范的范围内；当它们显示凭证内容时，由凭证格式和协议提供的该内容的语言和书写方向决定其呈现方式。

因此，本规范未引入任何需要语言或方向元数据的自然语言文本。如果未来修订版在 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，返回一个错误，其错误代码为无效参数。
2. 如果 protocol 不是 DigitalCredentialProtocol 的枚举值，返回一个错误，其错误代码为无效参数。
3. 将 response序列化为 JSON 字符串。
4. 如果序列化产生异常，返回一个错误，其错误代码为无效参数。
否则：
1. 如果 response 不为 null 或 protocol 不为 null，返回一个错误，其错误代码为无效参数。
如果 action 为 "clear"：
1. 如果 context 不为 null，从 WebDriver 会话的活动虚拟钱包行为中移除 context 的条目。
2. 否则，将 WebDriver 会话的活动虚拟钱包行为设置为 null。
否则：
1. 令 behavior 为元组（action、protocol、 response）。
2. 如果 context 不为 null，将 WebDriver 会话中浏览上下文 ID context 的活动虚拟钱包行为设置为 behavior。
3. 否则，将 WebDriver 会话的默认活动虚拟钱包行为设置为 behavior。
返回数据为 null 的成功结果。

注：在测试中模拟钱包错误

编写自动化测试的开发者可以通过将AbortSignal作为signal 传入（用于 get()），或将signal 传入（用于create()），然后使用所需的中止原因将其中止，从而模拟钱包错误。这会执行请求算法使用的同一中止路径。

示例 9：使用 AbortController 模拟钱包错误

(async () => {
  const controller = new AbortController();
  const credentialPromise = navigator.credentials.get({
    digital: {
      requests: [{
        protocol: "example-request-protocol",
        data: { /* 出示请求数据 */ }
      }]
    },
    signal: controller.signal
  });

  controller.abort(
    new DOMException("Simulated wallet failure", "OperationError")
  );

  try {
    await credentialPromise;
  } catch (error) {
    console.assert(error.name === "OperationError");
  }
})();

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

如果用户代理未处于自动化控制之下，返回 false。
令 context ID 为 global 的浏览上下文的 ID。
令 behavior 为当前 WebDriver 会话中 context ID 的活动虚拟钱包行为。
如果 behavior 为 null，将 behavior 设置为当前 WebDriver 会话的默认活动虚拟钱包行为。
如果 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 的相关领域解析 JSON string 的结果。
3. 令 credential 为一个新的DigitalCredential 实例。
4. 将 credential 的protocol 属性设置为 protocol。
5. 将 credential 的data 属性设置为 JS object。
6. 在给定 global 的DOM 操作任务源上排入一个全局任务，以使用 credential兑现 promise。
7. 返回 true。

中止算法 §6.
中止信号 §6.
中止凭据请求 §6.5
正在中止 §6.1
action §14.1.1
活动 promise §6.
活动虚拟钱包行为 §14.1.2.1
API 洪泛 §10.1.1
"clear" §14.1.1
context §14.1.1
转换请求协议 §5.1
[[Create]](origin, options, sameOriginWithAncestors) DigitalCredential 的内部槽 §8.3
凭证管理器选择器 §4.
凭据请求 §4.
凭据请求协调器 §6.
凭据响应 §4.
数据
- DigitalCredentialGetRequest 的成员 §7.3.2
- DigitalCredentialCreateRequest 的成员 §7.6.2
- DigitalCredential 的属性 §7.7.2
"decline" §14.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 §14.1.2.1
"digitalCredentials.setVirtualWalletBehavior" §14.1.2.1
digitalCredentials.SetVirtualWalletBehaviorParameters §14.1.1
digitalCredentials.SetVirtualWalletBehaviorResult §14.1.2.1
digitalCredentials.VirtualWalletAction §14.1.1
[[DiscoverFromExternalSource]](origin, options, sameOriginWithAncestors) DigitalCredential 的内部槽 §8.1
[[discovery]] DigitalCredential 的内部槽 §8.5
这些类型的示例 §1.
过滤凭据请求 §6.3
处理虚拟钱包行为 §14.2
空闲 §6.1
范围内威胁 §10.1.1
发起凭据请求 §6.7
交互状态 §6.1
签发协议 §4.
签发请求 §4.
签发请求数据 §4.
签发响应 §4.
恶意凭据管理器 §10.1.2
针对底层平台的恶意载荷 §10.1.1
method §14.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
超出范围的威胁 §10.1.2
params §14.1.2.1
准备凭据请求 §6.2
出示协议 §4.
出示请求 §4.
出示请求数据 §4.
出示响应 §4.
protocol
- DigitalCredentialGetRequest 的成员 §7.3.1
- DigitalCredentialCreateRequest 的成员 §7.6.1
- DigitalCredential 的属性 §7.7.1
- 定义 §14.1.1
协议和格式漏洞 §10.1.2
协议标识符 §4.
以……拒绝凭据请求 §6.6
请求上下文 §7.8.1
请求篡改 §10.1.1
正在请求 §6.1
requests
- DigitalCredentialRequestOptions 的成员 §7.2.1
- DigitalCredentialCreationOptions 的成员 §7.5.1
- 定义 §7.8.1
"respond" §14.1.1
response §14.1.1
[[Store]](credential, sameOriginWithAncestors) DigitalCredential 的内部槽 §8.2
受支持的出示和签发协议表 §5.
text §14.1.1
顶层源 §7.8.1
[[type]] DigitalCredential 的内部槽 §8.4
未经授权的跨源访问 §10.1.1
用户代理允许协议 §7.7.3
userAgentAllowsProtocol() DigitalCredential 的方法 §7.7.3
验证凭据请求 §6.4
"wait" §14.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）
- 请求一个 Credential
- required（用于 CredentialMediationRequirement）
- signal（用于 CredentialRequestOptions）
- signal（用于 CredentialCreationOptions）
- 用户介入
DOM 标准定义了以下内容：
- 中止原因（用于 AbortSignal）
- 已中止（用于 AbortSignal）
- AbortSignal 接口
- 添加（用于 AbortSignal）
- Document
- 移除（用于 AbortSignal）
- 信号中止（用于 AbortController）
- 信号（用于 AbortController）
HTML 标准定义了以下内容：
- 活动文档（用于 navigable）
- 关联的 Document
- 浏览上下文
- 子可导航对象
- 消耗用户激活
- DOM 操作任务源
- 环境设置对象
- 完全活动（用于 Document）
- 具有用户注意的顶级可遍历对象的完全活动后代（用于 Document）
- iframe 元素
- 并行地
- object 类型
- 不透明源
- 源
- 源（用于环境设置对象）
- 排入一个全局任务
- 相关全局对象
- 相关领域
- 相关设置对象
- 安全上下文
- 顶级可遍历对象
- 瞬态激活
- Window 接口
Infra 标准定义了以下内容：
- 追加（用于 list）
- ASCII 数字
- ASCII 小写字母
- 断言
- 码点
- 继续（用于 iteration）
- 对于每个（用于 list）
- 为空（用于 list）
- 项（用于 struct）
- 列表
- 将 JSON 字符串解析为 JavaScript 值
- 将 JavaScript 值序列化为 JSON 字符串
- 将 Infra 值序列化为 JSON 字符串
- 字符串
- 结构体
- 用户代理
[PERMISSIONS] 定义了以下内容：
- 明确许可
- 强大特性
[PERMISSIONS-POLICY] 定义了以下内容：
- 'self' （用于默认允许列表）
- 默认允许列表（用于策略控制特性）
- 策略控制特性
[PRIVACY-PRINCIPLES] 定义了以下内容：
- 用户代理职责
[VC-DATA-MODEL] 定义了以下内容：
- 声明
- 持有者
- 签发者
- 主体
- 验证者
[WEBDRIVER] 定义了以下内容：
- 错误
- 错误代码
- 无效参数
- 远端步骤
- 会话
- 成功
Web IDL 标准定义了以下内容：
- 一个新 promise
- 以给定值拒绝的 promise
- AbortError 异常
- boolean 类型
- 创建（用于 exception）
- [Default] 扩展属性
- 默认 toJSON 步骤
- DOMException 接口
- DOMString 接口
- 枚举值
- 异常
- [Exposed] 扩展属性
- 接口对象
- 接口
- InvalidStateError 异常
- NotAllowedError 异常
- object 类型
- OperationError 异常
- Promise 接口
- ReferenceError 异常
- 拒绝
- 兑现
- [SameObject] 扩展属性
- [SecureContext] 扩展属性
- SecurityError 异常
- 序列
- 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 拒绝凭证请求

6.7 发起凭证请求

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. 权限策略集成

10. 安全考虑

10.1 威胁模型

10.1.1 范围内威胁

10.1.2 范围外威胁

10.2 缓解措施

10.3 签署演示请求

10.4 跨设备安全性和邻近性

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 非政府凭证被盗和泄露的风险

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` 枚举

14.1 `digitalCredentials` 模块

14.1.2.1 `digitalCredentials.setVirtualWalletBehavior` 命令

A.1 本规范定义的术语