说明
使用 chrome.platformKeys
API 访问由平台管理的客户端证书。如果用户或政策授予了权限,则扩展程序可以在其自定义身份验证协议中使用此类证书。例如,此设置允许在第三方 VPN 中使用平台管理的证书(请参阅 chrome.vpnProvider)。
权限
platformKeys
可用性
类型
ClientCertificateRequest
属性
-
certificateAuthorities
ArrayBuffer[]
服务器允许的证书授权机构的标识名列表。每个条目都必须是 DER 编码的 X.509 DistinguishedName。
-
certificateTypes
此字段是所请求证书类型的列表,按服务器的偏好排序。只会检索此列表中包含的证书类型。不过,如果
certificateTypes
是空列表,系统将返回任意类型的证书。
ClientCertificateType
枚举
"rsaSign"
"ecdsaSign"
。
Match
属性
-
证书
ArrayBuffer
X.509 证书的 DER 编码。
-
keyAlgorithm
对象
已认证密钥的 KeyAlgorithm。其中包含证书密钥固有的算法参数(例如密钥长度)。不包括其他参数,例如符号函数使用的哈希函数。
SelectDetails
属性
-
clientCerts
ArrayBuffer[] 选填
如果给定,则
selectClientCertificates
将对此列表执行操作。否则,从平台可用于此扩展程序的证书存储区中获取所有证书的列表。系统会移除该扩展程序无权处理的条目,或者与该要求不符的条目。 -
interactive
boolean
如果为 true,则系统会向用户显示过滤列表,以手动选择证书,从而授权扩展程序访问证书和密钥。系统将仅返回所选的证书。如果为 false,则列表会缩减为(自动或手动)允许该扩展程序访问的所有证书。
-
request
系统将仅返回与此请求匹配的证书。
VerificationDetails
属性
-
hostname
string
要验证证书的服务器(例如提供
serverCertificateChain
的服务器)的主机名。 -
serverCertificateChain
ArrayBuffer[]
每个连锁店条目都必须是 X.509 证书的 DER 编码,第一个条目必须是服务器证书,并且每个条目都必须认证它前面的条目。
VerificationResult
属性
-
debug_errors
字符串[]
如果信任验证失败,此数组会包含底层网络层报告的错误。否则,此数组为空。
注意:此列表仅用于调试,未必包含所有相关错误。返回的错误可能会在此 API 的未来修订版本中发生变化,并且不能保证向前或向后兼容。
-
可信
boolean
信任验证的结果:如果可以建立对给定验证详情的信任,则为 true;如果出于任何原因拒绝信任,则为 false。
方法
getKeyPair()
chrome.platformKeys.getKeyPair(
certificate: ArrayBuffer,
parameters: object,
callback: function,
)
将 certificate
的密钥对传递给 callback
,以便与 platformKeys.subtleCrypto
配合使用。
参数
-
证书
ArrayBuffer
selectClientCertificates
返回的Match
的证书。 -
形参
对象
除了由密钥本身固定的参数外,还可确定签名/哈希算法参数。WebCrypto 的 importKey 函数可以接受相同的参数,例如,对于 RSASSA-PKCS1-v1_5 密钥,使用
RsaHashedImportParams
;对于 EC 密钥,使用EcKeyImportParams
。此外,对于 RSASSA-PKCS1-v1_5 密钥,可以使用以下值之一指定哈希算法名称参数:“none”“SHA-1”“SHA-256”“SHA-384”或“SHA-512”,例如{"hash": { "name": "none" } }
。然后,签名函数将应用 PKCS#1 v1.5 填充,但不会对指定数据进行哈希处理。目前,此方法仅支持“RSASSA-PKCS1-v1_5”和“ECDSA”算法。
-
callback
功能
callback
参数如下所示:(publicKey: object, privateKey?: object) => void
-
publicKey
对象
-
privateKey
对象(可选)
如果此扩展程序无权访问,值可能为
null
。
-
getKeyPairBySpki()
chrome.platformKeys.getKeyPairBySpki(
publicKeySpkiDer: ArrayBuffer,
parameters: object,
callback: function,
)
将 publicKeySpkiDer
标识的密钥对传递给 callback
,以便与 platformKeys.subtleCrypto
配合使用。
参数
-
publicKeySpkiDer
ArrayBuffer
DER 编码的 X.509 SubjectPublicKeyInfo,例如通过使用 format="spki" 调用 WebCrypto 的 exportKey 函数而获得。
-
形参
对象
除了由密钥本身固定的参数之外,还提供签名和哈希算法参数。WebCrypto 的 importKey 函数可以接受相同的参数,例如,对于 RSASSA-PKCS1-v1_5 密钥,可以使用
RsaHashedImportParams
。对于 RSASSA-PKCS1-v1_5 密钥,我们还需要传递一个“哈希”参数{ "hash": { "name": string } }
。“hash”参数表示摘要操作中要使用的哈希算法的名称,且该算法位于符号前面。可以传递“none”作为哈希名称,在这种情况下,符号函数将应用 PKCS#1 v1.5 填充,但不会对给定数据进行哈希处理。目前,此方法支持采用命名曲线 P-256 的“ECDSA”算法,以及采用以下其中一种哈希算法“none”“SHA-1”“SHA-256”“SHA-384”和“SHA-512”的“RSASSA-PKCS1-v1_5”算法。
-
callback
功能
callback
参数如下所示:(publicKey: object, privateKey?: object) => void
-
publicKey
对象
-
privateKey
对象(可选)
如果此扩展程序无权访问,值可能为
null
。
-
selectClientCertificates()
chrome.platformKeys.selectClientCertificates(
details: SelectDetails,
callback?: function,
)
此方法会从一系列客户端证书中滤除平台已知的、与 request
匹配且扩展程序有权访问证书及其私钥的客户端证书。如果 interactive
为 true,系统会向用户显示一个对话框,用户可以从匹配的证书中进行选择,并授予扩展程序访问证书的权限。所选/已过滤的客户端证书将传递给 callback
。
参数
返回
-
Promise<Match[]>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
subtleCrypto()
chrome.platformKeys.subtleCrypto()
WebCrypto 的 SubtleCrypto 实现,允许对扩展程序可用的客户端证书密钥执行加密操作。
返回
-
对象 | 未定义
verifyTLSServerCertificate()
chrome.platformKeys.verifyTLSServerCertificate(
details: VerificationDetails,
callback?: function,
)
根据平台的信任设置,针对 details.hostname
检查 details.serverCertificateChain
是否可信任。注意:信任验证的实际行为并未完全指定,将来可能会发生变化。API 实现会验证证书过期、验证证书路径和检查已知 CA 的信任度。该实现应遵循 EKU serverAuth 并支持主题备用名称。
参数
-
详细信息
-
callback
函数(可选)
callback
参数如下所示:(result: VerificationResult) => void
返回
-
Promise<VerificationResult>
Chrome 121 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。