此页面由 Cloud Translation API 翻译。

chrome.certificateProvider

说明

使用此 API 将证书提供给可以使用这些证书进行 TLS 身份验证的平台。

权限

certificateProvider

可用性

Chrome 46 及更高版本仅限 ChromeOS

概念和用法

通常，此 API 用于向 ChromeOS 公开客户端证书，具体步骤如下：

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

。 <ph type="x-smartling-placeholder">

如果用户中止身份验证或没有与请求匹配的证书，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);

类型

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

属性

证书

数组缓冲区

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

哈希[]

必须设置为此证书支持的所有哈希。系统只会要求此扩展程序提供使用其中一种哈希算法计算的摘要的签名。这应按照哈希优先顺序递减顺序。

CertificatesUpdateRequest

Chrome 86 及更高版本

属性

certificatesRequestId

number

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

ClientCertificateInfo

Chrome 86 及更高版本

属性

certificateChain

ArrayBuffer[]

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

其中必须正好包含一个证书。
supportedAlgorithms

算法[]

此证书支持所有算法。系统只会要求扩展程序提供采用下列其中一种算法的签名。

Error

Chrome 86 及更高版本

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

值

“GENERAL_ERROR”

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 及更高版本

属性

错误

"GENERAL_ERROR"
可选

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

number

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

ArrayBuffer 可选

签名（如果成功生成）。

RequestPinDetails

Chrome 57 及更高版本

属性

attemptsLeft

编号（选填）

剩余的尝试次数。提供此信息是为了让任何界面都能向用户显示这些信息。当超出固定请求次数时，Chrome 预计不会强制执行此要求，而是应由具有 errorType = MAX_ATTEMPTS_EXCEEDED 的扩展程序调用 stopPinRequest。
errorType

PinRequestErrorType optional

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

PinRequestType 选填

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

number

Chrome 在 SignRequest 中提供的 ID。

SetCertificatesDetails

Chrome 86 及更高版本

属性

certificatesRequestId

编号（选填）

在为响应 onCertificatesUpdateRequested 而调用时，应包含收到的 certificatesRequestId 值。否则，应取消设置。
clientCertificates

ClientCertificateInfo[]

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

"GENERAL_ERROR"
可选

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

SignatureRequest

Chrome 86 及更高版本

属性

算法

Algorithm

要使用的签名算法。
证书

数组缓冲区

X.509 证书的 DER 编码。该扩展程序必须使用关联的私钥为 input 签名。
输入

数组缓冲区

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

number

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

SignRequest

属性

证书

数组缓冲区

X.509 证书的 DER 编码。该扩展程序必须使用关联的私钥为 digest 签名。
摘要

数组缓冲区

必须签名的摘要。
哈希

哈希

是指用于创建 digest 的哈希算法。
signRequestId

number

Chrome 57 及更高版本

如果扩展程序需要调用需要它的方法，将要使用的唯一 ID。例如，requestPin 中。

StopPinRequestDetails

Chrome 57 及更高版本

属性

errorType

PinRequestErrorType optional

错误模板。如果存在，则向用户显示。用于包含因错误导致的流停止的原因，例如MAX_ATTEMPTS_EXCEEDED。
signRequestId

number

Chrome 在 SignRequest 中提供的 ID。

方法

reportSignature()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 86 及更高版本

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

应在响应 onSignatureRequested 时进行调用。

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

参数

详细信息

ReportSignatureDetails
callback

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Chrome 96 及更高版本

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

requestPin()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 57 及更高版本

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

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

参数

详细信息

RequestPinDetails

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

函数（可选）

callback 参数如下所示：
```
(details?: PinResponseDetails) => void
```
- 详细信息
  
  PinResponseDetails 可选

Promise<PinResponseDetails |未定义>

Chrome 96 及更高版本

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

setCertificates()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 86 及更高版本

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

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

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

参数

详细信息

SetCertificatesDetails

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

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<void>

Chrome 96 及更高版本

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

stopPinRequest()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 57 及更高版本

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

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

参数

详细信息

StopPinRequestDetails

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

函数（可选）

callback 参数如下所示：
```
() => void
```

承诺<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

<ph type="x-smartling-placeholder"></ph> &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
```
  - 签名
    
    ArrayBuffer 可选