chrome.enterprise.platformKeys

说明

使用 chrome.enterprise.platformKeys API 生成密钥并为这些密钥安装证书。这些证书将由平台管理，可用于 TLS 身份验证、网络访问或通过 chrome.platformKeys 由其他扩展程序使用。

权限

enterprise.platformKeys

可用性

仅限 ChromeOS 需要政策

用法

使用此 API 注册客户端证书的典型步骤如下：

  • 使用 enterprise.platformKeys.getTokens 获取所有可用令牌。

  • 查找 id 等于 "user" 的令牌。随后使用此令牌。

  • 使用 generateKey Token 方法（在 SubtleCrypto 中定义）生成密钥对。这将返回密钥的句柄。

  • 使用 exportKey 令牌方法（在 SubtleCrypto 中定义）导出公钥。

  • 使用 sign Token 方法（在 SubtleCrypto 中定义）创建认证请求数据的签名。

  • 完成认证申请并将其发送给认证机构。

  • 如果收到证书，请使用 enterprise.platformKeys.importCertificate 导入证书

以下示例展示了除构建和发送认证请求之外的主要 API 互动：

function getUserToken(callback) {   chrome.enterprise.platformKeys.getTokens(function(tokens) {     for (var i = 0; i < tokens.length; i++) {       if (tokens[i].id == "user") {         callback(tokens[i]);         return;       }     }     callback(undefined);   }); }  function generateAndSign(userToken) {   var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);   var algorithm = {     name: "RSASSA-PKCS1-v1_5",     // RsaHashedKeyGenParams     modulusLength: 2048,     publicExponent:         new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537     hash: {       name: "SHA-256",     }   };   var cachedKeyPair;   userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])     .then(function(keyPair) {             cachedKeyPair = keyPair;             return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);           },           console.log.bind(console))     .then(function(publicKeySpki) {             // Build the Certification Request using the public key.             return userToken.subtleCrypto.sign(                 {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);           },           console.log.bind(console))     .then(function(signature) {               // Complete the Certification Request with |signature|.               // Send out the request to the CA, calling back               // onClientCertificateReceived.           },           console.log.bind(console)); }  function onClientCertificateReceived(userToken, certificate) {   chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate); }  getUserToken(generateAndSign);

类型

Algorithm

Chrome 110 及更高版本

要生成的密钥类型。

枚举

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 及更高版本

属性

  • 挑战

    ArrayBuffer

    由 Verified Access Web API 发出的质询。

  • registerKey

    RegisterKeyOptions 可选

    如果存在，则使用指定的 scope 的令牌注册受质询的密钥。然后，该密钥可以与证书相关联，并像任何其他签名密钥一样使用。随后对该函数的调用将在指定的 scope 中生成新的企业密钥。

  • 范围

    范围

    要验证的企业密钥。

RegisterKeyOptions

Chrome 110 及更高版本

属性

  • 算法

    Algorithm

    注册密钥应使用的算法。

Scope

Chrome 110 及更高版本

是使用企业用户密钥还是企业机器密钥。

枚举

"USER"

“MACHINE”

Token

属性

  • id

    字符串

    唯一标识相应 Token。

    静态 ID 为 "user" 和 "system"，分别是指平台的用户专用硬件令牌和系统范围的硬件令牌。任何其他令牌（带有其他标识符）都可能由 enterprise.platformKeys.getTokens 返回。

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 及更高版本

    实现 WebCrypto 的 SubtleCrypto 接口。加密操作（包括密钥生成）由软件支持。密钥的保护以及不可提取属性的实现是在软件中完成的，因此密钥的保护程度不如硬件支持的密钥。

    只能生成不可提取的密钥。支持的密钥类型为 RSASSA-PKCS1-V1_5 和 RSA-OAEP（在 Chrome 版本 135 及更高版本中），密钥长度为 modulusLength，最高可达 2048。每个 RSASSA-PKCS1-V1_5 密钥最多只能用于一次数据签名，除非通过 KeyPermissions 政策将相应扩展程序列入许可名单，在这种情况下，该密钥可以无限期使用。自 Chrome 版本 135 起，RSA-OAEP 密钥受到支持，并且通过同一政策列入许可名单的扩展程序可以使用这些密钥来解封装其他密钥。

    在特定 Token 上生成的密钥不能用于任何其他令牌，也不能用于 window.crypto.subtle。同样，使用 window.crypto.subtle 创建的 Key 对象不能与此接口搭配使用。

  • subtleCrypto

    SubtleCrypto

    实现 WebCrypto 的 SubtleCrypto 接口。加密操作（包括密钥生成）由硬件支持。

    只能生成不可提取的密钥。支持的密钥类型包括 RSASSA-PKCS1-V1_5 和 RSA-OAEP（在 Chrome 版本 135 及更高版本中）以及 modulusLength 最多 2048 位的 ECDSA 和 namedCurve P-256。每个 RSASSA-PKCS1-V1_5 和 ECDSA 密钥最多只能用于一次数据签名，除非通过 KeyPermissions 政策将相应扩展程序列入许可名单，在这种情况下，密钥可以无限期使用。自 Chrome 版本 135 起，RSA-OAEP 密钥受到支持，并且通过同一政策列入许可名单的扩展程序可以使用这些密钥来解封装其他密钥。

    在特定 Token 上生成的密钥不能用于任何其他令牌，也不能用于 window.crypto.subtle。同样，使用 window.crypto.subtle 创建的 Key 对象不能与此接口搭配使用。

方法

challengeKey()

Promise Chrome 110 及更高版本 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
): Promise<ArrayBuffer>

与 challengeMachineKey 和 challengeUserKey 类似，但允许指定已注册密钥的算法。对由硬件支持的企业机器密钥发起质询，并根据远程证明协议发出响应。仅在 ChromeOS 上有用，并且需要与 Verified Access Web API 结合使用，该 API 既会发出质询，也会验证响应。

如果 Verified Access Web API 成功完成验证，则表明当前设备是合法的 ChromeOS 设备，当前设备受验证期间指定的网域管理，当前登录的用户受验证期间指定的网域管理，并且当前设备状态符合企业设备政策。例如，某项政策可能规定设备不得处于开发者模式。验证所发出的任何设备身份都与当前设备的硬件紧密绑定。如果指定了 "user" 范围，则身份也会与当前登录的用户紧密绑定。

此函数受到严格限制，如果当前设备不受管理、当前用户不受管理，或者企业设备政策未明确为调用方启用此操作，则此函数将失败。受质询的密钥不位于 "system" 或 "user" 令牌中，并且无法通过任何其他 API 进行访问。

参数

  • 包含 ChallengeKeyOptions 中定义的字段的对象。

  • callback

    函数 可选

    callback 参数如下所示： 

    (response: ArrayBuffer) => void

    • Response

      ArrayBuffer

      质询响应。

返回

  • Promise<ArrayBuffer>

    Chrome 131 及更高版本

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

challengeMachineKey()

Promise Chrome 50 及更高版本 自 Chrome 110 起已弃用
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

请改用 challengeKey。

对由硬件支持的企业机器密钥发起质询，并根据远程证明协议发出响应。仅在 ChromeOS 上有用，并且需要与 Verified Access Web API 结合使用，该 API 既会发出质询，也会验证响应。如果经过验证的访问权限 Web API 成功验证，则强烈表明以下所有情况：* 当前设备是合法的 ChromeOS 设备。* 当前设备由验证期间指定的网域管理。* 当前登录的用户由验证期间指定的网域管理。* 当前设备状态符合企业设备政策。例如，某项政策可能规定设备不得处于开发者模式。* 验证功能发出的任何设备身份都与当前设备的硬件紧密绑定。此函数受到严格限制，如果当前设备不受管理、当前用户不受管理，或者企业设备政策未明确为调用方启用此操作，则此函数将失败。企业机器密钥不位于 "system" 令牌中，并且无法通过任何其他 API 进行访问。

参数

  • 挑战

    ArrayBuffer

    由 Verified Access Web API 发出的质询。

  • registerKey

    布尔值（可选）

    Chrome 59 及更高版本

    如果已设置，则当前企业机器密钥会注册为 "system" 令牌，并放弃企业机器密钥角色。然后，该密钥可以与证书相关联，并像任何其他签名密钥一样使用。此密钥为 2048 位 RSA 密钥。随后对该函数的调用将生成新的企业机器密钥。

  • callback

    函数 可选

    callback 参数如下所示： 

    (response: ArrayBuffer) => void

    • Response

      ArrayBuffer

      质询响应。

返回

  • Promise<ArrayBuffer>

    Chrome 131 及更高版本

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

challengeUserKey()

Promise Chrome 50 及更高版本 自 Chrome 110 起已弃用
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

请改用 challengeKey。

对硬件支持的企业用户密钥发起质询，并根据远程证明协议发出响应。仅在 ChromeOS 上有用，并且需要与 Verified Access Web API 结合使用，该 API 既会发出质询，也会验证响应。如果经过验证的访问权限 Web API 成功验证，则强烈表明以下所有情况：* 当前设备是合法的 ChromeOS 设备。* 当前设备由验证期间指定的网域管理。* 当前登录的用户由验证期间指定的网域管理。* 当前设备状态符合企业用户政策。例如，某项政策可能规定设备不得处于开发者模式。* 验证所发出的公钥与当前设备的硬件和当前登录用户紧密绑定。此功能受到严格限制，如果当前设备不受管理、当前用户不受管理，或者企业用户政策未明确为调用方启用此操作，则此功能将失败。企业用户密钥不位于 "user" 令牌中，任何其他 API 都无法访问该密钥。

参数

  • 挑战

    ArrayBuffer

    由 Verified Access Web API 发出的质询。

  • registerKey

    布尔值

    如果设置，则当前企业用户密钥会注册到 "user" 令牌，并放弃企业用户密钥角色。然后，该密钥可以与证书相关联，并像任何其他签名密钥一样使用。此密钥为 2048 位 RSA 密钥。随后对该函数的调用将生成新的企业用户密钥。

  • callback

    函数 可选

    callback 参数如下所示： 

    (response: ArrayBuffer) => void

    • Response

      ArrayBuffer

      质询响应。

返回

  • Promise<ArrayBuffer>

    Chrome 131 及更高版本

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

getCertificates()

Promise 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
): Promise<ArrayBuffer[]>

返回指定令牌中的所有可用客户端证书的列表。可用于检查可用于特定身份验证的客户端证书是否存在以及是否过期。

参数

  • tokenId

    字符串

    getTokens 返回的令牌的 ID。

  • callback

    函数 可选

    callback 参数如下所示： 

    (certificates: ArrayBuffer[]) => void

    • 证书

      ArrayBuffer[]

      证书列表，每个证书都采用 X.509 证书的 DER 编码。

返回

  • Promise<ArrayBuffer[]>

    Chrome 131 及更高版本

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

getTokens()

Promise 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

返回可用令牌。在常规用户的会话中，该列表将始终包含用户的令牌，且该令牌具有 id "user"。如果存在系统级 TPM token，则返回的列表还将包含具有 id "system" 的系统级 token。对于相应设备（例如 Chromebook）上的所有会话，系统级令牌都将相同。

参数

  • callback

    函数 可选

    callback 参数如下所示： 

    (tokens: Token[]) => void

    • 词元

      令牌[]

      可用令牌的列表。

返回

  • Promise<Token[]>

    Chrome 131 及更高版本

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

importCertificate()

Promise 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

如果认证密钥已存储在相应令牌中，则将 certificate 导入到相应令牌。成功发出认证请求后，应使用此函数存储获得的证书，并使其可供操作系统和浏览器用于身份验证。

参数

  • tokenId

    字符串

    getTokens 返回的令牌的 ID。

  • 证书

    ArrayBuffer

    X.509 证书的 DER 编码。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 131 及更高版本

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

removeCertificate()

Promise 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

从给定令牌中移除 certificate（如果存在）。应使用此方法移除过时的证书，以免在身份验证期间考虑这些证书，并避免证书选择过程过于杂乱。应使用此方法释放证书存储区中的存储空间。

参数

  • tokenId

    字符串

    getTokens 返回的令牌的 ID。

  • 证书

    ArrayBuffer

    X.509 证书的 DER 编码。

  • callback

    函数 可选

    callback 参数如下所示： 

    () => void

返回

  • Promise<void>

    Chrome 131 及更高版本

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