说明
使用此 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() {
browser.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.
browser.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.
browser.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
error: 'GENERAL_ERROR'
});
return;
}
const signature = signUnhashedData(key, request.input, request.algorithm);
browser.certificateProvider.reportSignature({
signRequestId: request.signRequestId,
signature: signature
});
}
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
handleCertificatesUpdateRequest);
browser.certificateProvider.onSignatureRequested.addListener(
handleSignatureRequest);
类型
Algorithm
支持的加密签名算法类型。
枚举
"RSASSA_PKCS1_v1_5_MD5_SHA1"
指定采用 MD5-SHA-1 哈希处理的 RSASSA PKCS#1 v1.5 签名算法。扩展程序不得在前面添加 DigestInfo 前缀，而只能添加 PKCS#1 填充。此算法已被弃用，从 Chrome 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
Hash[]
必须设置为此证书支持的所有哈希。此扩展程序只会收到使用其中一种哈希算法计算的摘要的签名请求。此列表应按哈希偏好降序排列。
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 及更高版本 browser.*（自 Chrome 148 起）扩展程序在需要调用需要唯一 ID 的方法（例如 requestPin）时应使用的唯一 ID。
StopPinRequestDetails
属性
-
errorType
错误模板。如果存在，则会向用户显示。旨在包含流程停止的原因（如果是由错误引起的），例如 MAX_ATTEMPTS_EXCEEDED。
-
signRequestId
数值
Chrome 在 SignRequest 中提供的 ID。
方法
reportSignature()
browser.certificateProvider.reportSignature(
details: ReportSignatureDetails,
): Promise<void>
应作为对 onSignatureRequested 的响应进行调用。
扩展程序最终必须针对每个 onSignatureRequested 事件调用此函数；API 实现会在一段时间后停止等待此调用，并在调用此函数时返回超时错误。
参数
返回
-
承诺<void>
Chrome 96 及更高版本 browser.*（自 Chrome 148 起）
requestPin()
browser.certificateProvider.requestPin(
details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>
向用户请求 PIN 码。一次只能有一个正在进行的请求。在另一个流程进行期间发出的请求会被拒绝。如果另一个流程正在进行中，则扩展程序有责任稍后重试。
参数
-
详细信息
包含所请求对话框的相关详细信息。
返回
-
Promise<PinResponseDetails | undefined>
Chrome 96 及更高版本 browser.*（自 Chrome 148 起）返回一个 Promise，该 Promise 会在用户提供 PIN 码时解析。如果对话框请求未成功完成（例如，对话框被用户取消或不允许显示），则会拒绝并显示错误。
setCertificates()
browser.certificateProvider.setCertificates(
details: SetCertificatesDetails,
): Promise<void>
设置要在浏览器中使用的证书列表。
扩展程序应在初始化后以及当前可用证书集发生每次更改时调用此函数。每次收到此事件时，扩展程序也应调用此函数来响应 onCertificatesUpdateRequested。
参数
-
要设置的证书。系统会忽略无效证书。
返回
-
承诺<void>
Chrome 96 及更高版本 browser.*（自 Chrome 148 起）返回一个在完成时解析的 Promise。
stopPinRequest()
browser.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
): Promise<void>
停止由 requestPin 函数启动的固定请求。
参数
-
包含有关停止请求流程的原因的详细信息。
返回
-
承诺<void>
Chrome 96 及更高版本 browser.*（自 Chrome 148 起）返回一个 Promise，该 Promise 会在关闭 PIN 码对话框的请求完成后解析。
事件
onCertificatesUpdateRequested
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
如果通过 setCertificates 设置的证书不足，或者浏览器请求更新信息，则会触发此事件。扩展程序必须使用更新后的证书列表和收到的 certificatesRequestId 调用 setCertificates。
参数
-
callback
函数
callback参数如下所示：(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
browser.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
每当浏览器需要使用此扩展程序通过 setCertificates 提供的证书对消息进行签名时，都会触发此事件。
扩展程序必须使用适当的算法和私钥对来自 request 的输入数据进行签名，并通过使用收到的 signRequestId 调用 reportSignature 来返回该数据。
参数
-
callback
函数
callback参数如下所示：(request: SignatureRequest) => void
-
request
-