chrome.platformKeys

说明

使用 chrome.platformKeys API 访问由平台管理的客户端证书。如果用户或政策授予了此权限,扩展程序便可在其自定义身份验证协议中使用此类证书。例如:这允许在第三方 VPN 中使用平台管理的证书(请参阅 chrome.vpnProvider)。

权限

platformKeys

可用性

Chrome 45 及更高版本 仅限 ChromeOS

类型

ClientCertificateRequest

属性

  • certificateAuthorities

    ArrayBuffer[]

    服务器允许的证书授权机构的标识名列表。每个条目都必须是 DER 编码的 X.509 DistinguishedName。

  • certificateTypes

    此字段是所请求的证书类型列表,按服务器偏好排序。系统将仅检索此列表中包含的类型的证书。不过,如果 certificateTypes 是空列表,则返回任何类型的证书。

ClientCertificateType

枚举

"rsaSign"

“ecdsaSign”

Match

属性

  • 证书

    数组缓冲区

    X.509 证书的 DER 编码。

  • keyAlgorithm

    对象

    经过认证的密钥的 KeyAlgorithm。此文件包含证书密钥固有的算法参数(例如密钥长度)。不包括符号函数使用的其他参数,例如哈希函数。

SelectDetails

属性

  • clientCerts

    ArrayBuffer[] 可选

    如果指定,则 selectClientCertificates 将对此列表执行操作。否则,从平台的证书存储区获取此扩展程序可用的所有证书的列表。系统会移除该扩展程序无权处理的条目或与请求不符的条目。

  • 互动

    布尔值

    如果值为 true,则系统会向用户显示过滤后的列表,以便用户手动选择证书,从而向扩展程序授予对证书和密钥的访问权限。系统只会返回所选的证书。如果为 false,则此列表会缩减到扩展程序有权访问的所有证书(自动或手动)。

  • 系统将仅返回与此请求匹配的证书。

VerificationDetails

属性

  • 主机名

    字符串

    要为其验证证书的服务器主机名,例如呈现 serverCertificateChain 的服务器。

  • serverCertificateChain

    ArrayBuffer[]

    每个链条目都必须是 X.509 证书的 DER 编码,第一个条目必须是服务器证书,并且每个条目都必须对其前面的条目进行认证。

VerificationResult

属性

  • debug_errors

    字符串[]

    如果信任验证失败,此数组会包含底层网络层报告的错误。否则,此数组为空。

    注意:此列表仅用于调试目的,不一定包含所有相关错误。返回的错误可能会在此 API 的未来修订版本中发生变化,并且不能保证一定是向前或向后兼容的。

  • 可信

    布尔值

    信任验证的结果:如果可以针对指定的验证详情建立信任,则为 true;如果信任因任何原因而遭拒,则为 false。

方法

getKeyPair()

chrome.platformKeys.getKeyPair(
  certificate: ArrayBuffer,
  parameters: object,
  callback: function,
)

将供 platformKeys.subtleCrypto 使用的 certificate 密钥对传递给 callback

参数

  • 证书

    数组缓冲区

    selectClientCertificates 返回的 Match 的证书。

  • 参数

    对象

    除了通过密钥本身固定的参数之外,还可以确定签名/哈希算法参数。WebCrypto 的 importKey 函数接受的形参相同,例如RsaHashedImportParams(对于 RSASSA-PKCS1-v1_5 密钥)和 EcKeyImportParams(对于 EC 密钥)。此外,对于 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 85 及更高版本
chrome.platformKeys.getKeyPairBySpki(
  publicKeySpkiDer: ArrayBuffer,
  parameters: object,
  callback: function,
)

publicKeySpkiDer 标识的用于 platformKeys.subtleCrypto 的密钥对传递给 callback

参数

  • publicKeySpkiDer

    数组缓冲区

    DER 编码的 X.509 SubjectPublicKeyInfo,例如方法是使用 format="spki" 调用 WebCrypto 的 exportKey 函数。

  • 参数

    对象

    除了由密钥本身修复的参数之外,还提供签名和哈希算法参数。WebCrypto 的 importKey 函数接受的形参相同,例如RsaHashedImportParams,表示 RSASSA-PKCS1-v1_5 密钥。对于 RSASSA-PKCS1-v1_5 密钥,我们还需要传递“hash”参数 { "hash": { "name": string } }。“哈希”参数表示在签名前的摘要操作中使用的哈希算法的名称。您可以向代码传递“none”作为哈希名称,在这种情况下,符号函数将应用 PKCS#1 v1.5 填充,但不会对给定数据进行哈希处理。

    目前,此方法支持“ECDSA”具有命名曲线 P-256 和“RSASSA-PKCS1-v1_5”的算法一种哈希算法:“none”、“SHA-1”、“SHA-256”、“SHA-384”和“SHA-512”之一。

  • callback

    函数

    callback 参数如下所示:

    (publicKey: object, privateKey?: object) => void

    • publicKey

      对象

    • privateKey

      对象(可选

      如果此扩展程序无权访问,它的值可能为 null

selectClientCertificates()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.platformKeys.selectClientCertificates(
  details: SelectDetails,
  callback?: function,
)

此方法会从客户端证书列表中过滤出平台已知且与 request 匹配且扩展程序有权访问相应证书及其私钥的客户端证书。如果 interactive 为 true,系统会显示一个对话框,让用户可从匹配的证书中进行选择,并向扩展程序授予对证书的访问权限。所选/过滤后的客户端证书将传递给 callback

参数

  • 详细信息
  • callback

    函数(可选)

    callback 参数如下所示:

    (matches: Match[]) => void

    • 匹配

      与请求匹配、扩展程序有权限且 interactive 为 true 时由用户选择的证书的列表。

返回

  • Promise<匹配[]>

    Chrome 121 及更高版本

    只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。

subtleCrypto()

chrome.platformKeys.subtleCrypto()

WebCrypto 的 SubtleCrypto 实现,允许对此扩展程序可用的客户端证书密钥执行加密操作。

返回

  • object |未定义

verifyTLSServerCertificate()

<ph type="x-smartling-placeholder"></ph> 承诺
chrome.platformKeys.verifyTLSServerCertificate(
  details: VerificationDetails,
  callback?: function,
)

根据平台的信任设置,检查对于 details.hostnamedetails.serverCertificateChain 是否可信任。注意:信任验证的实际行为尚未完整指定,将来可能会发生变化。API 实现会验证证书失效日期、验证证书路径,并检查已知 CA 的信任情况。实现应遵从 EKU serverAuth 并支持正文备用名称。

参数

返回

  • Promise&lt;VerificationResult&gt;

    Chrome 121 及更高版本

    只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。