说明
使用此 API 将证书提供给可以使用这些证书进行 TLS 身份验证的平台。
权限
certificateProvider可用性
用法
通常，此 API 用于向 ChromeOS 公开客户端证书，具体步骤如下：
- 该扩展程序会注册 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);
类型
Algorithm
支持的加密签名算法类型。
枚举
"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
属性
-
certificatesRequestId
number
要传递给
setCertificates的请求标识符。
ClientCertificateInfo
属性
-
certificateChain
ArrayBuffer[]
数组必须将 X.509 客户端证书的 DER 编码作为其第一个元素。
其中必须正好包含一个证书。
-
supportedAlgorithms
算法[]
此证书支持所有算法。系统只会要求扩展程序提供采用下列其中一种算法的签名。
Error
扩展程序可以报告的错误类型。
值
“GENERAL_ERROR”
Hash
已弃用。已替换为Algorithm。
枚举
"MD5_SHA1"
指定 MD5 和 SHA1 哈希算法。
"SHA1"
指定 SHA1 哈希算法。
"SHA256"
指定 SHA256 哈希算法。
"SHA384"
指定 SHA384 哈希算法。
"SHA512"
指定 SHA512 哈希算法。
PinRequestErrorType
可通过 requestPin 函数向用户显示的错误类型。
枚举
"INVALID_PIN"
指定 PIN 码无效。
"INVALID_PUK"
指定 PUK 无效。
"MAX_ATTEMPTS_EXCEEDED"
指定已超过最大尝试次数。
"UNKNOWN_ERROR"
指定无法用上述类型表示错误。
PinRequestType
扩展程序通过 requestPin 函数请求的代码类型。
枚举
"PIN"
指定请求的验证码是 PIN 码。
"PUK"
指定请求的验证码是 PUK 码。
PinResponseDetails
属性
-
userInput
字符串（可选）
用户提供的代码。如果用户关闭对话框或发生其他错误，则为空。
ReportSignatureDetails
属性
-
错误
"GENERAL_ERROR"
可选生成签名时发生的错误（如果有）。
-
signRequestId
number
通过
onSignatureRequested事件收到的请求标识符。 -
签名
ArrayBuffer 可选
签名（如果成功生成）。
RequestPinDetails
属性
-
attemptsLeft
编号（选填）
剩余的尝试次数。提供此信息是为了让任何界面都能向用户显示这些信息。当超出固定请求次数时，Chrome 预计不会强制执行此要求，而是应由具有 errorType = MAX_ATTEMPTS_EXCEEDED 的扩展程序调用 stopPinRequest。
-
errorType
PinRequestErrorType optional
向用户显示的错误模板。如果前一个请求失败，则应设置此字段，以通知用户失败原因。
-
requestType
请求的代码类型。默认值为 PIN。
-
signRequestId
number
Chrome 在 SignRequest 中提供的 ID。
SetCertificatesDetails
属性
-
certificatesRequestId
编号（选填）
在为响应
onCertificatesUpdateRequested而调用时，应包含收到的certificatesRequestId值。否则，应取消设置。 -
clientCertificates
当前可用的客户端证书列表。
-
错误
"GENERAL_ERROR"
可选提取证书时出错（如果有）。系统会适时向用户显示此错误。
SignatureRequest
属性
-
算法
要使用的签名算法。
-
证书
数组缓冲区
X.509 证书的 DER 编码。该扩展程序必须使用关联的私钥为
input签名。 -
输入
数组缓冲区
要签名的数据。请注意，数据未经过哈希处理。
-
signRequestId
number
要传递给
reportSignature的请求标识符。
SignRequest
属性
-
证书
数组缓冲区
X.509 证书的 DER 编码。该扩展程序必须使用关联的私钥为
digest签名。 -
摘要
数组缓冲区
必须签名的摘要。
-
哈希
是指用于创建
digest的哈希算法。 -
signRequestId
number
Chrome 57 及更高版本如果扩展程序需要调用需要它的方法，将要使用的唯一 ID。例如，requestPin 中。
StopPinRequestDetails
属性
-
errorType
PinRequestErrorType optional
错误模板。如果存在，则向用户显示。用于包含因错误导致的流停止的原因，例如MAX_ATTEMPTS_EXCEEDED。
-
signRequestId
number
Chrome 在 SignRequest 中提供的 ID。
方法
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
应在响应 onSignatureRequested 时进行调用。
该扩展程序最终必须针对每个 onSignatureRequested 事件调用此函数；API 实现将在一段时间后停止等待此次调用，并在调用此函数时返回超时错误作为响应。
参数
-
callback
函数（可选）
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
向用户请求 PIN 码。一次只能提出一项请求。在另一个流正在进行时发出的请求会被拒绝。如果其他流程正在进行中，扩展程序应负责稍后重试。
参数
-
详细信息
包含所请求对话框的相关详细信息。
-
callback
函数（可选）
callback参数如下所示：(details?: PinResponseDetails) => void
-
详细信息
-
返回
-
Promise<PinResponseDetails |未定义>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
设置在浏览器中使用的证书列表。
该扩展程序应在初始化之后以及当前可用证书集中的每次更改时调用此函数。在每次收到此事件时，此扩展程序还应调用此函数来响应 onCertificatesUpdateRequested。
参数
-
要设置的证书。系统会忽略无效的证书。
-
callback
函数（可选）
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
停止由 requestPin 函数启动的固定请求。
参数
-
包含有关停止请求流的原因的详细信息。
-
callback
函数（可选）
callback参数如下所示：() => void
返回
-
承诺<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise，其他平台需要使用回调。
事件
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
请改用 onCertificatesUpdateRequested。
每次浏览器请求此扩展程序提供的当前证书列表时，此事件都会触发。该扩展程序必须使用当前的证书列表调用 reportCallback 一次。
参数
-
callback
函数
callback参数如下所示：(reportCallback: function) => void
-
reportCallback
函数
reportCallback参数如下所示：(certificates: CertificateInfo[], callback: function) => void
-
certificates
-
callback
函数
callback参数如下所示：(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
如果通过 setCertificates 设置的证书不足，或浏览器请求更新信息，则会触发此事件。此扩展程序必须使用更新后的证书列表和收到的 certificatesRequestId 来调用 setCertificates。
参数
-
callback
函数
callback参数如下所示：(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
每当浏览器需要使用此扩展程序通过 setCertificates 提供的证书对消息签名时，此事件就会触发。
该扩展程序必须使用适当的算法和私钥对来自 request 的输入数据进行签名，并通过使用收到的 signRequestId 调用 reportSignature 将其返回。
参数
-
callback
函数
callback参数如下所示：(request: SignatureRequest) => void
-
request
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
请改用 onSignatureRequested。
每当浏览器为了响应 onCertificatesRequested 事件而需要使用此扩展程序提供的证书对消息签名时，就会触发此事件。该扩展程序必须使用适当的算法和私钥为 request 中的数据签名，并通过调用 reportCallback 将其返回。必须正好调用 reportCallback 一次。
参数
-
callback
函数
callback参数如下所示：(request: SignRequest, reportCallback: function) => void
-
request
-
reportCallback
函数
Chrome 47 及更高版本reportCallback参数如下所示：(signature?: ArrayBuffer) => void
-
签名
ArrayBuffer 可选
-
-