chrome.certificateProvider

Description

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

Permissions

certificateProvider

Availability

Chrome 46+

# Usage

此 API 向 Chrome 操作系统公开客户端证书的典型用法遵循以下步骤：

• 扩展注册事件 onCertificatesUpdateRequested 和 onSignatureRequested。
• 扩展调用 setCertificates 以提供初始化后的初始证书列表。
• 扩展监视可用证书列表中的更改并调用 setCertificates 以将每个此类更改通知浏览器。
• 在 TLS 握手期间，浏览器会收到客户端证书请求。通过 onCertificatesUpdateRequested 事件，浏览器要求扩展报告它当前提供的所有证书。
• 扩展使用 setCertificates 方法报告当前可用的证书。
• 浏览器将所有可用证书与来自远程主机的客户端证书请求相匹配。匹配项在选择对话框中呈现给用户。
• 用户可以选择证书，从而批准认证或中止认证。

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

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

在扩展中，这可能类似于以下代码段：

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);

Summary

• Types

  Algorithm

  CertificateInfo

  CertificatesUpdateRequest

  ClientCertificateInfo

  Error

  Hash

  PinRequestErrorType

  PinRequestType

  PinResponseDetails

  ReportSignatureDetails

  RequestPinDetails

  SetCertificatesDetails

  SignatureRequest

  SignRequest

  StopPinRequestDetails

• Methods

  reportSignature

  requestPin

  setCertificates

  stopPinRequest

• Events

  onCertificatesRequested

  onCertificatesUpdateRequested

  onSignatureRequested

  onSignDigestRequested

Types

Algorithm

Chrome 86+

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

TYPE

"RSASSA_PKCS1_v1_5_MD5_SHA1", "RSASSA_PKCS1_v1_5_SHA1", "RSASSA_PKCS1_v1_5_SHA256", "RSASSA_PKCS1_v1_5_SHA384", "RSASSA_PKCS1_v1_5_SHA512", "RSASSA_PSS_SHA256", "RSASSA_PSS_SHA384", or "RSASSA_PSS_SHA512"

CertificateInfo

PROPERTIES

• certificate

  ArrayBuffer

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

• supportedHashes

  Hash[]

  必须设置为此证书支持的所有哈希值。此扩展将只要求使用这些哈希算法之一计算的摘要签名。这应该是按照减少哈希偏好的顺序。

CertificatesUpdateRequest

Chrome 86+

PROPERTIES

• certificatesRequestId

  number

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

ClientCertificateInfo

Chrome 86+

PROPERTIES

• certificateChain

  ArrayBuffer[]

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

• supportedAlgorithms

  Algorithm[]

  此证书支持的所有算法。只会要求扩展使用这些算法之一进行签名。

Error

Chrome 86+

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

VALUE

"GENERAL_ERROR"

Hash

已弃用。被算法Algorithm取代。

TYPE

"MD5_SHA1", "SHA1", "SHA256", "SHA384", or "SHA512"

PinRequestErrorType

Chrome 57+

可以通过 requestPin 函数呈现给用户的错误类型。

TYPE

"INVALID_PIN", "INVALID_PUK", "MAX_ATTEMPTS_EXCEEDED", or "UNKNOWN_ERROR"

PinRequestType

Chrome 57+

具有 requestPin 函数的扩展请求的代码类型。

TYPE

"PIN", or "PUK"

PinResponseDetails

Chrome 57+

PROPERTIES

• userInput

  string optional

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

ReportSignatureDetails

Chrome 86+

PROPERTIES

• error

  "GENERAL_ERROR" optional

  生成签名时发生的错误（如果有）。

• signRequestId

  number

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

• signature

  ArrayBuffer optional

  签名，如果成功生成。

RequestPinDetails

Chrome 57+

PROPERTIES

• attemptsLeft

  number optional

  剩余尝试次数。提供此信息是为了让任何 UI 都可以向用户呈现此信息。预计 Chrome 不会强制执行此操作,相反，当超过 pin 请求的数量时，扩展应使用 errorType = MAX_ATTEMPTS_EXCEEDED 调用 stopPinRequest。

• errorType

  PinRequestErrorType optional

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

• requestType

  PinRequestType optional

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

• signRequestId

  number

  Chrome 在 SignRequest 中给出的 ID。

SetCertificatesDetails

Chrome 86+

PROPERTIES

• certificatesRequestId

  number optional

  当响应 onCertificatesUpdateRequested 调用时，应包含接收到的certificatesRequestId 值。否则，应取消设置。

• clientCertificates

  ClientCertificateInfo[]

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

• error

  "GENERAL_ERROR" optional

  提取证书时发生的错误（如果有）。此错误将在适当的时候显示给用户。

SignatureRequest

Chrome 86+

PROPERTIES

• algorithm

  Algorithm

  要使用的签名算法。

• certificate

  ArrayBuffer

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

• input

  ArrayBuffer

  要签名的数据。请注意，数据未经过哈希处理。

• signRequestId

  number

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

SignRequest

PROPERTIES

• certificate

  ArrayBuffer

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

• digest

  ArrayBuffer

  必须签名的摘要。

• hash

  Hash

  指用于创建digest摘要的哈希算法。

• signRequestId

  number

  Chrome 57+

  如果扩展需要调用需要它的方法，则扩展使用的唯一 ID，例如请求引脚。

StopPinRequestDetails

Chrome 57+

PROPERTIES

• errorType

  PinRequestErrorType optional

  错误模板。如果存在，它会显示给用户。如果它是由错误引起的，则旨在包含停止流的原因，例如MAX_ATTEMPTS_EXCEEDED。

• signRequestId

  number

  Chrome 在 SignRequest 中给出的 ID。

Methods

reportSignature

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

Promise Chrome 86+

应作为对 onSignatureRequested 的响应调用。

扩展最终必须为每个 onSignatureRequested 事件调用这个函数； API 实现将在一段时间后停止等待此调用，并在调用此函数时响应超时错误。

PARAMETERS

• details

  ReportSignatureDetails

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同。

requestPin

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

Promise Chrome 57+

向用户请求 PIN。一次只允许一个正在进行的请求。在另一个流正在进行时发出的请求被拒绝。如果另一个流程正在进行中，则扩展程序有责任稍后再试。

PARAMETERS

• details

  RequestPinDetails

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

• callback

  function optional

  The callback parameter looks like:

  (details?: PinResponseDetails) => void

  • details

    PinResponseDetails optional

RETURNS

• Promise<PinResponseDetails | undefined>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同.

setCertificates

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

Promise Chrome 86+

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

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

PARAMETERS

• details

  SetCertificatesDetails

  要设置的证书。无效的证书将被忽略。

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同

stopPinRequest

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

Promise Chrome 57+

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

PARAMETERS

• details

  StopPinRequestDetails

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

• callback

  function optional

  The callback parameter looks like:

  () => void

RETURNS

• Promise<void>

  Pending

  这仅在未指定callback参数时返回 Promise，并且使用 MV3+。 Promise 中的类型与callback的第一个参数相同

Events

onCertificatesRequested

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

Chrome 47+ ≤MV2 Deprecated since Chrome 86

请改用 onCertificatesUpdateRequested。

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

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (reportCallback: function) => void

  • reportCallback

    function

    The reportCallback parameter looks like:

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

    • certificates

      CertificateInfo[]

    • callback

      function

      The callback parameter looks like:

      (rejectedCertificates: ArrayBuffer[]) => void

      • rejectedCertificates

        ArrayBuffer[]

onCertificatesUpdateRequested

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

Chrome 86+

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

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (request: CertificatesUpdateRequest) => void

  • request

    CertificatesUpdateRequest

onSignatureRequested

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

Chrome 86+

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

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

PARAMETERS

• callback

  function

  The callback parameter looks like:

  (request: SignatureRequest) => void

  • request

    SignatureRequest

onSignDigestRequested

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

≤MV2 Deprecated since Chrome 86

请改用 onSignatureRequested。

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

PARAMETERS

• callback

  function

  The callback parameter looks like:

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

  • request

    SignRequest

  • reportCallback

    function

    Chrome 47+

    The reportCallback parameter looks like:

    (signature?: ArrayBuffer) => void

    • signature

      ArrayBuffer optional

By.一粒技术服务