说明
使用此 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”
指定 RSASSA PSS 签名算法，使用 SHA-256 哈希函数、MGF1 掩码生成函数和与哈希大小相同的盐。
"RSASSA_PSS_SHA384"
指定 RSASSA PSS 签名算法，该算法使用 SHA-384 哈希函数、MGF1 掩码生成函数和与哈希大小相同的盐。
“RSASSA_PSS_SHA512”
指定 RSASSA PSS 签名算法，该算法使用 SHA-512 哈希函数、MGF1 掩码生成函数以及与哈希大小相同的盐。
CertificateInfo
属性
-
证书
ArrayBuffer
必须是 X.509 证书的 DER 编码。目前仅支持使用 RSA 密钥的证书。
-
supportedHashes
哈希[]
必须设置为相应证书支持的所有哈希。此扩展程序只会要求对使用这些哈希算法之一计算出的摘要进行签名。应按哈希偏好程度降序排列。
CertificatesUpdateRequest
属性
-
certificatesRequestId
数值
要传递给
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
数值
通过
onSignatureRequested事件接收到的请求标识符。 -
签名
ArrayBuffer 可选
成功生成的签名。
RequestPinDetails
属性
-
attemptsLeft
number 可选
剩余尝试次数。提供此信息是为了让任何界面都能向用户显示此信息。Chrome 不会强制执行此操作，而是当 PIN 码请求数超出时，扩展程序应调用 stopPinRequest 并将 errorType 设置为 MAX_ATTEMPTS_EXCEEDED。
-
errorType
向用户显示的错误模板。如果之前的请求失败，则应设置此参数，以将失败原因通知给用户。
-
requestType
所请求的验证码类型。默认值为 PIN 码。
-
signRequestId
数值
Chrome 在 SignRequest 中提供的 ID。
SetCertificatesDetails
属性
-
certificatesRequestId
number 可选
在响应
onCertificatesUpdateRequested时调用，应包含收到的certificatesRequestId值。否则，应取消设置。 -
clientCertificates
当前可用的客户端证书列表。
-
错误
"GENERAL_ERROR"
可选提取证书时发生的错误（如果有）。系统会在适当的时候向用户显示此错误。
SignatureRequest
属性
-
算法
要使用的签名算法。
-
证书
ArrayBuffer
X.509 证书的 DER 编码。扩展程序必须使用关联的私钥对
input进行签名。 -
输入
ArrayBuffer
要签名的数据。请注意，数据未经过哈希处理。
-
signRequestId
数值
要传递给
reportSignature的请求标识符。
SignRequest
属性
-
证书
ArrayBuffer
X.509 证书的 DER 编码。扩展程序必须使用关联的私钥对
digest进行签名。 -
摘要
ArrayBuffer
必须签名的摘要。
-
哈希
指用于创建
digest的哈希算法。 -
signRequestId
数值
Chrome 57 及更高版本供扩展程序使用的唯一 ID，如果扩展程序需要调用需要此 ID 的方法（例如 requestPin），则应使用此 ID。
StopPinRequestDetails
属性
-
errorType
错误模板。如果存在，则会向用户显示。旨在包含因错误而停止流程的原因，例如 MAX_ATTEMPTS_EXCEEDED。
-
signRequestId
数值
Chrome 在 SignRequest 中提供的 ID。
方法
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
): Promise<void>
应作为对 onSignatureRequested 的响应进行调用。
扩展程序必须最终为每个 onSignatureRequested 事件调用此函数；API 实现会在一段时间后停止等待此调用，并在调用此函数时以超时错误进行响应。
参数
返回
-
Promise<void>
Chrome 96 及更高版本
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>
向用户请求 PIN 码。一次只能有一个正在进行的请求。在另一个流程正在进行时发出的请求会被拒绝。如果另一个流程正在进行中，扩展程序应负责稍后重试。
参数
-
详细信息
包含有关所请求对话框的详细信息。
返回
-
Promise<PinResponseDetails | undefined>
Chrome 96 及更高版本
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
): Promise<void>
设置要在浏览器中使用的证书列表。
扩展程序应在初始化后以及当前可用证书集发生每次更改时调用此函数。扩展程序还应在每次收到此事件时，调用此函数以响应 onCertificatesUpdateRequested。
参数
-
要设置的证书。系统会忽略无效证书。
返回
-
Promise<void>
Chrome 96 及更高版本
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
): Promise<void>
停止由 requestPin 函数启动的 PIN 码请求。
参数
-
包含有关停止请求流的原因的详细信息。
返回
-
Promise<void>
Chrome 96 及更高版本
事件
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
-