chrome.certificateProvider

重要提示：此 API 仅适用于 ChromeOS。

说明

使用此 API 向可以使用这些证书进行 TLS 身份验证的平台公开证书。

权限

certificateProvider

可用性

Chrome 46 及更高版本 仅限 ChromeOS

概念和用法

此 API 向 ChromeOS 公开客户端证书的一般用法如下：

• 该扩展程序会注册事件 onCertificatesUpdateRequested 和 onSignatureRequested。
• 该扩展程序会在初始化后调用 setCertificates() 来提供初始证书列表。
• 该扩展程序会监控可用证书列表中的更改，并调用 setCertificates() 将每次此类更改告知浏览器。
• 在 TLS 握手期间，浏览器会收到客户端证书请求。对于 onCertificatesUpdateRequested 事件，浏览器会要求扩展程序报告当前提供的所有证书。
• 该扩展程序会使用 setCertificates() 方法返回当前可用的证书。
• 浏览器会将所有可用证书与来自远程主机的客户端证书请求进行匹配。匹配项会在选择对话框中向用户显示。
• 用户可以选择证书，从而批准身份验证或中止身份验证。

证书选择对话框。

• 如果用户取消身份验证或没有与请求匹配的证书，则 TLS 客户端身份验证会被取消。
• 否则，如果用户使用此扩展程序提供的证书批准身份验证，则浏览器会请求扩展程序对数据进行签名，以便继续进行 TLS 握手。请求作为 onSignatureRequested 事件发送。
• 此事件包含输入数据，声明了生成签名必须使用哪种算法，并引用了此扩展程序报告的其中一个证书。该扩展程序必须使用与引用的证书关联的私钥为给定数据创建签名。创建签名可能需要在实际签名前添加 DigestInfo 和填充结果。
• 该扩展程序会使用 reportSignature() 方法将签名发回给浏览器。如果无法计算签名，则必须在不签名的情况下调用该方法。
• 如果提供了签名，浏览器会完成 TLS 握手。

实际的步骤顺序可能会有所不同。例如，如果使用企业政策来自动选择证书（请参阅 AutoSelectCertificateForUrls 和面向用户的 Chrome 政策），则系统不会要求用户选择证书。

在 Extension 中，可能类似于以下代码段：

function collectAvailableCertificates() {
  // Return all certificates that this Extension can currently provide.
  // For example:
  return [{
    certificateChain: [new Uint8Array(...)],
    supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']
  }];
}

// The Extension calls this function every time the currently available list of
// certificates changes, and also once after the Extension's initialization.
function onAvailableCertificatesChanged() {
  chrome.certificateProvider.setCertificates({
    clientCertificates: collectAvailableCertificates()
  });
}

function handleCertificatesUpdateRequest(request) {
  // Report the currently available certificates as a response to the request
  // event. This is important for supporting the case when the Extension is
  // unable to detect the changes proactively.
  chrome.certificateProvider.setCertificates({
    certificatesRequestId: request.certificatesRequestId,
    clientCertificates: collectAvailableCertificates()
  });
}

// Returns a private key handle for the given DER-encoded certificate.
// |certificate| is an ArrayBuffer.
function getPrivateKeyHandle(certificate) {...}

// Digests and signs |input| with the given private key. |input| is an
// ArrayBuffer. |algorithm| is an Algorithm.
// Returns the signature as ArrayBuffer.
function signUnhashedData(privateKey, input, algorithm) {...}

function handleSignatureRequest(request) {
  // Look up the handle to the private key of |request.certificate|.
  const key = getPrivateKeyHandle(request.certificate);
  if (!key) {
    // Handle if the key isn't available.
    console.error('Key for requested certificate no available.');

    // Abort the request by reporting the error to the API.
    chrome.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  chrome.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
chrome.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

类型

Algorithm

Chrome 86 及更高版本

支持的加密签名算法的类型。

枚举

"RSASSA_PKCS1_v1_5_MD5_SHA1"
使用 MD5-SHA-1 哈希指定 RSASSA PKCS#1 v1.5 签名算法。该扩展程序不得添加 DigestInfo 前缀，而应添加 PKCS#1 填充内容。此算法已弃用，从版本 109 开始，Chrome 将不再请求此算法。

"RSASSA_PKCS1_v1_5_SHA1"
使用 SHA-1 哈希函数指定 RSASSA PKCS#1 v1.5 签名算法。

"RSASSA_PKCS1_v1_5_SHA256"
使用 SHA-256 哈希函数指定 RSASSA PKCS#1 v1.5 签名算法。

"RSASSA_PKCS1_v1_5_SHA384"
使用 SHA-384 哈希函数指定 RSASSA PKCS#1 v1.5 签名算法。

"RSASSA_PKCS1_v1_5_SHA512"
使用 SHA-512 哈希函数指定 RSASSA PKCS#1 v1.5 签名算法。

"RSASSA_PSS_SHA256"
使用 SHA-256 哈希函数、MGF1 掩码生成函数和大小与哈希值相同的盐指定 RSASSA PSS 签名算法。

"RSASSA_PSS_SHA384"
使用 SHA-384 哈希函数、MGF1 掩码生成函数以及大小与哈希值相同的盐指定 RSASSA PSS 签名算法。

"RSASSA_PSS_SHA512"
使用 SHA-512 哈希函数、MGF1 掩码生成函数以及大小与哈希值相同的盐指定 RSASSA PSS 签名算法。

CertificateInfo

属性

• 证书

  ArrayBuffer

  必须为 X.509 证书的 DER 编码。目前仅支持 RSA 密钥证书。

• supportedHashes

  哈希[]

  必须设为此证书支持的所有哈希。系统只会向此扩展程序要求提供使用这类哈希算法之一计算出的摘要的签名。此顺序应为哈希偏好设置从低到高的顺序。

CertificatesUpdateRequest

Chrome 86 及更高版本

属性

• certificatesRequestId

  number

  要传递给 setCertificates 的请求标识符。

ClientCertificateInfo

Chrome 86 及更高版本

属性

• certificateChain

  ArrayBuffer[]

  该数组必须包含 X.509 客户端证书的 DER 编码作为其第一个元素。

  必须且只能包含一个证书。

• supportedAlgorithms

  算法[]

  此证书支持的所有算法。系统只会要求扩展程序提供使用以下算法之一的签名。

Error

Chrome 86 及更高版本

扩展程序可以报告的错误类型。

值

Hash

已弃用。替换为 Algorithm。

枚举

"MD5_SHA1"
指定 MD5 和 SHA1 哈希算法。

"SHA1"
指定 SHA1 哈希算法。

"SHA256"
指定 SHA256 哈希算法。

"SHA384"
指定 SHA384 哈希算法。

"SHA512"
指定 SHA512 哈希算法。

PinRequestErrorType

Chrome 57 及更高版本

可通过 requestPin 函数向用户显示的错误类型。

枚举

"INVALID_PIN"
指定的 PIN 码无效。

"INVALID_PUK"
指定的 PUK 无效。

"MAX_ATTEMPTS_EXCEEDED"
指定已超过最大尝试次数。

"UNKNOWN_ERROR"
指定不能由上述类型表示错误。

PinRequestType

Chrome 57 及更高版本

扩展程序使用 requestPin 函数请求的代码类型。

枚举

"PIN"
指定的代码是 PIN 码。

"PUK"
指定的代码是 PUK。

PinResponseDetails

Chrome 57 及更高版本

属性

• userInput

  字符串（可选）

  用户提供的代码。如果用户关闭了对话框或发生其他错误，则为空。

ReportSignatureDetails

Chrome 86 及更高版本

属性

• error

   可选

  生成签名时出错（如果有）。

• signRequestId

  number

  通过 onSignatureRequested 事件收到的请求标识符。

• signature

  ArrayBuffer 可选

  签名（如果已成功生成）。

RequestPinDetails

Chrome 57 及更高版本

属性

• attemptsLeft

  数字可选

  剩余尝试次数。这样做是为了让任何界面都可以向用户显示此信息。Chrome 预计不会强制实施此政策，当超出 PIN 码请求数时，该扩展程序应调用 stopPinRequest（错误类型为 MAX_ATTEMPTS_EXCEEDED）。

• errorType

  PinRequestErrorType（可选）

  向用户显示的错误模板。如果前一个请求失败，则应设置此字段，以通知用户失败原因。

• requestType

  PinRequestType（可选）

  请求的代码类型。默认值为 PIN 码。

• signRequestId

  number

  Chrome 在 SignRequest 中提供的 ID。

SetCertificatesDetails

Chrome 86 及更高版本

属性

• certificatesRequestId

  数字可选

  在响应 onCertificatesUpdateRequested 进行调用时，该参数应包含收到的 certificatesRequestId 值。否则，应取消设置。

• clientCertificates

  ClientCertificateInfo[]

  当前可用的客户端证书列表。

• error

   可选

  提取证书（如果有）时出错。我们会适时向用户显示此错误。

SignatureRequest

Chrome 86 及更高版本

属性

• 算法

  Algorithm

  要使用的签名算法。

• 证书

  ArrayBuffer

  X.509 证书的 DER 编码。扩展程序必须使用关联的私钥对 input 进行签名。

• 输入

  ArrayBuffer

  要签名的数据。请注意，这些数据未进行哈希处理。

• signRequestId

  number

  要传递给 reportSignature 的请求标识符。

SignRequest

属性

• 证书

  ArrayBuffer

  X.509 证书的 DER 编码。扩展程序必须使用关联的私钥对 digest 进行签名。

• 摘要

  ArrayBuffer

  必须签名的摘要。

• hash

  哈希

  表示用于创建 digest 的哈希算法。

• signRequestId

  number

  Chrome 57 及更高版本

  扩展程序在需要调用需要调用的方法（例如 requestPin）时使用唯一 ID。

StopPinRequestDetails

Chrome 57 及更高版本

属性

• errorType

  PinRequestErrorType（可选）

  错误模板。如果有，系统会向用户显示它。应包含流由错误导致的停止原因，例如 MAX_ATTEMPTS_EXCEEDED。

• signRequestId

  number

  Chrome 在 SignRequest 中提供的 ID。

方法

reportSignature()

Promise Chrome 86 及更高版本

chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

应作为对 onSignatureRequested 的响应进行调用。

该扩展程序最终必须针对每个 onSignatureRequested 事件调用此函数；一段时间后，API 实现将停止等待此调用，并在调用此函数时返回超时错误。

参数

• 明细

  ReportSignatureDetails

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

requestPin()

Promise Chrome 57 及更高版本

chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

向用户请求 PIN 码。一次只能处理一个正在进行的请求。在另一个数据流正在进行时发出的请求会被拒绝。如果其他流程正在进行中，此扩展程序会负责稍后重试。

参数

• 明细

  RequestPinDetails

  包含有关所请求对话框的详细信息。

• callback

  函数（可选）

  callback 参数如下所示：

  (details?: PinResponseDetails)=>void

  • 明细

    PinResponseDetails（可选）

返回

• Promise<PinResponseDetails|undefined>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setCertificates()

Promise Chrome 86 及更高版本

chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

设置要在浏览器中使用的证书的列表。

该扩展程序应在初始化之后以及当前可用证书集的每一次更改时调用此函数。每次收到此事件时，此扩展程序也应调用此函数来响应 onCertificatesUpdateRequested。

参数

• 明细

  SetCertificatesDetails

  要设置的证书。系统会忽略无效证书。

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

stopPinRequest()

Promise Chrome 57 及更高版本

chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

停止由 requestPin 函数启动的 PIN 码请求。

参数

• 明细

  StopPinRequestDetails

  包含有关停止请求流的原因的详细信息。

• callback

  函数（可选）

  callback 参数如下所示：

  ()=>void

返回

• Promise<void>

  Chrome 96 及更高版本

  Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

活动

onCertificatesRequested

Chrome 47 及更高版本 &leq; MV2 自 Chrome 86 起弃用

chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

请改用 onCertificatesUpdateRequested。

每次浏览器请求此扩展程序提供的当前证书列表时，都会触发此事件。该扩展程序必须使用当前证书列表正好调用 reportCallback 一次。

参数

• callback

  功能

  callback 参数如下所示：

  (reportCallback: function)=>void

  • reportCallback

    功能

    reportCallback 参数如下所示：

    (certificates: CertificateInfo[],callback: function)=>void

    • certificates

      CertificateInfo[]

    • callback

      功能

      callback 参数如下所示：

      (rejectedCertificates: ArrayBuffer[])=>void

      • rejectedCertificates

        ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 及更高版本

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

如果通过 setCertificates 设置的证书不足，或浏览器请求更新信息，则会触发此事件。该扩展程序必须使用更新后的证书列表和收到的 certificatesRequestId 来调用 setCertificates。

参数

• callback

  功能

  callback 参数如下所示：

  (request: CertificatesUpdateRequest)=>void

  • request

    CertificatesUpdateRequest

onSignatureRequested

Chrome 86 及更高版本

chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

每当浏览器需要使用此扩展程序通过 setCertificates 提供的证书对邮件进行签名时，就会触发此事件。

该扩展程序必须使用适当的算法和私钥对来自 request 的输入数据进行签名，并使用收到的 signRequestId 调用 reportSignature 来返回这些数据。

参数

• callback

  功能

  callback 参数如下所示：

  (request: SignatureRequest)=>void

  • request

    SignatureRequest

onSignDigestRequested

&leq; MV2 自 Chrome 86 起已废弃

chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

请改用 onSignatureRequested。

每当浏览器需要使用此扩展程序提供的证书为消息签名时，就会触发此事件，以响应 onCertificatesRequested 事件。该扩展程序必须使用适当的算法和私钥对 request 中的数据进行签名，并通过调用 reportCallback 返回数据。reportCallback 必须仅调用一次。

参数

• callback

  功能

  callback 参数如下所示：

  (request: SignRequest,reportCallback: function)=>void

  • request

    SignRequest

  • reportCallback

    功能

    Chrome 47 及更高版本

    reportCallback 参数如下所示：

    (signature?: ArrayBuffer)=>void

    • signature

      ArrayBuffer 可选