说明
使用此 API 向可以使用这些证书进行 TLS 身份验证的平台公开证书。
权限
certificateProvider
可用性
概念和用法
此 API 向 ChromeOS 公开客户端证书的一般用法如下:
- 该扩展程序会注册事件
onCertificatesUpdateRequested
和onSignatureRequested
。 - 该扩展程序会在初始化后调用
setCertificates()
来提供初始证书列表。 - 该扩展程序会监控可用证书列表中的更改,并调用
setCertificates()
将每次此类更改告知浏览器。 - 在 TLS 握手期间,浏览器会收到客户端证书请求。对于
onCertificatesUpdateRequested
事件,浏览器会要求扩展程序报告当前提供的所有证书。 - 该扩展程序会使用
setCertificates()
方法返回当前可用的证书。 - 浏览器会将所有可用证书与来自远程主机的客户端证书请求进行匹配。匹配项会在选择对话框中向用户显示。
- 用户可以选择证书,从而批准身份验证或中止身份验证。
![证书选择对话框](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=6&hl=ro)
- 如果用户取消身份验证或没有与请求匹配的证书,则 TLS 客户端身份验证会被取消。
- 否则,如果用户使用此扩展程序提供的证书批准身份验证,则浏览器会请求扩展程序对数据进行签名,以便继续进行 TLS 握手。请求作为
onSignatureRequested
事件发送。 - 此事件包含输入数据,声明了生成签名必须使用哪种算法,并引用了此扩展程序报告的其中一个证书。该扩展程序必须使用与引用的证书关联的私钥为给定数据创建签名。创建签名可能需要在实际签名前添加 DigestInfo 和填充结果。
- 该扩展程序会使用
reportSignature()
方法将签名发回给浏览器。如果无法计算签名,则必须在不签名的情况下调用该方法。 - 如果提供了签名,浏览器会完成 TLS 握手。
实际的步骤顺序可能会有所不同。例如,如果使用企业政策来自动选择证书(请参阅 AutoSelectCertificateForUrls
和面向用户的 Chrome 政策),则系统不会要求用户选择证书。
在 Extension 中,可能类似于以下代码段:
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
属性
-
证书
ArrayBuffer
必须为 X.509 证书的 DER 编码。目前仅支持 RSA 密钥证书。
-
supportedHashes
哈希[]
必须设为此证书支持的所有哈希。系统只会向此扩展程序要求提供使用这类哈希算法之一计算出的摘要的签名。此顺序应为哈希偏好设置从低到高的顺序。
CertificatesUpdateRequest
属性
-
certificatesRequestId
number
要传递给
setCertificates
的请求标识符。
ClientCertificateInfo
属性
-
certificateChain
ArrayBuffer[]
该数组必须包含 X.509 客户端证书的 DER 编码作为其第一个元素。
必须且只能包含一个证书。
-
supportedAlgorithms
算法[]
此证书支持的所有算法。系统只会要求扩展程序提供使用以下算法之一的签名。
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
属性
-
error
可选
生成签名时出错(如果有)。
-
signRequestId
number
通过
onSignatureRequested
事件收到的请求标识符。 -
signature
ArrayBuffer 可选
签名(如果已成功生成)。
RequestPinDetails
属性
-
attemptsLeft
数字可选
剩余尝试次数。这样做是为了让任何界面都可以向用户显示此信息。Chrome 预计不会强制实施此政策,当超出 PIN 码请求数时,该扩展程序应调用 stopPinRequest(错误类型为 MAX_ATTEMPTS_EXCEEDED)。
-
errorType
向用户显示的错误模板。如果前一个请求失败,则应设置此字段,以通知用户失败原因。
-
requestType
PinRequestType(可选)
请求的代码类型。默认值为 PIN 码。
-
signRequestId
number
Chrome 在 SignRequest 中提供的 ID。
SetCertificatesDetails
属性
-
certificatesRequestId
数字可选
在响应
onCertificatesUpdateRequested
进行调用时,该参数应包含收到的certificatesRequestId
值。否则,应取消设置。 -
clientCertificates
当前可用的客户端证书列表。
-
error
可选
提取证书(如果有)时出错。我们会适时向用户显示此错误。
SignatureRequest
属性
-
算法
要使用的签名算法。
-
证书
ArrayBuffer
X.509 证书的 DER 编码。扩展程序必须使用关联的私钥对
input
进行签名。 -
输入
ArrayBuffer
要签名的数据。请注意,这些数据未进行哈希处理。
-
signRequestId
number
要传递给
reportSignature
的请求标识符。
SignRequest
属性
-
证书
ArrayBuffer
X.509 证书的 DER 编码。扩展程序必须使用关联的私钥对
digest
进行签名。 -
摘要
ArrayBuffer
必须签名的摘要。
-
hash
表示用于创建
digest
的哈希算法。 -
signRequestId
number
Chrome 57 及更高版本扩展程序在需要调用需要调用的方法(例如 requestPin)时使用唯一 ID。
StopPinRequestDetails
属性
-
errorType
错误模板。如果有,系统会向用户显示它。应包含流由错误导致的停止原因,例如 MAX_ATTEMPTS_EXCEEDED。
-
signRequestId
number
Chrome 在 SignRequest 中提供的 ID。
方法
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
应作为对 onSignatureRequested
的响应进行调用。
该扩展程序最终必须针对每个 onSignatureRequested
事件调用此函数;一段时间后,API 实现将停止等待此调用,并在调用此函数时返回超时错误。
参数
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
向用户请求 PIN 码。一次只能处理一个正在进行的请求。在另一个数据流正在进行时发出的请求会被拒绝。如果其他流程正在进行中,此扩展程序会负责稍后重试。
参数
-
详细信息
包含有关所请求对话框的详细信息。
-
callback
函数(可选)
callback
参数如下所示:(details?: PinResponseDetails) => void
-
详细信息
-
返回
-
Promise<PinResponseDetails | undefined>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
设置要在浏览器中使用的证书的列表。
该扩展程序应在初始化之后以及当前可用证书集的每一次更改时调用此函数。每次收到此事件时,此扩展程序也应调用此函数来响应 onCertificatesUpdateRequested
。
参数
-
要设置的证书。系统会忽略无效证书。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
停止由 requestPin
函数启动的 PIN 码请求。
参数
-
包含有关停止请求流的原因的详细信息。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本Manifest V3 及更高版本支持 promise,但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。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
-
signature
ArrayBuffer 可选
-
-