chrome.enterprise.platformKeys

说明

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

权限

enterprise.platformKeys

可用性

<ph type="x-smartling-placeholder"></ph> 仅限 ChromeOS 需要政策

概念和用法

如需使用此 API 注册客户端证书，请按以下步骤操作：

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

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

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

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

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

  • 完成认证请求并将其发送给认证授权机构。

  • 如果收到证书，请使用 [enterprise.platformKeys.importCertificate()`[3] 导入

以下示例展示了除构建和发送认证请求之外的主要 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"

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 接口。加密操作（包括密钥生成）由软件支持。密钥的保护（以及不可提取属性的实现）是在软件中完成的，因此这些密钥的保护程度低于由硬件支持的密钥。

    系统只能生成 modulusLength 不超过 2048 且不可提取的 RSASSA-PKCS1-V1_5 密钥。每个密钥最多只能用于一次数据签名。

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

  • subtleCrypto

    SubtleCrypto

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

    系统只能生成 modulusLength 不超过 2048 且不可提取的 RSASSA-PKCS1-V1_5 密钥以及 namedCurve P-256 的 ECDSA 密钥。每个密钥最多只能用于签名一次数据。

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

方法

challengeKey()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 110 及更高版本 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

与 challengeMachineKey 和 challengeUserKey 类似，但允许指定已注册密钥的算法。质询由硬件支持的企业机器密钥，并作为远程认证协议的一部分发出响应。仅适用于 ChromeOS，与 Verified Access Web API（用于提出质询和验证回答）结合使用。

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

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

参数

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: ArrayBuffer) => void

    • Response

      ArrayBuffer

      质询响应。

返回

  • Promise&lt;ArrayBuffer&gt;

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。

challengeMachineKey()

<ph type="x-smartling-placeholder"></ph> 承诺 Chrome 50 及更高版本 自 Chrome 110 起弃用
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

请改用 challengeKey。

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

参数

  • 挑战

    ArrayBuffer

    Verified Access Web API 发出的质询。

  • registerKey

    布尔值（可选）

    Chrome 59 及更高版本

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: ArrayBuffer) => void

    • Response

      ArrayBuffer

      质询响应。

返回

  • Promise&lt;ArrayBuffer&gt;

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。

challengeUserKey()

Promise Chrome 50 及更高版本 从 Chrome 110 开始已废弃
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

请改用 challengeKey。

质询由硬件支持的企业用户密钥，并作为远程认证协议的一部分发出响应。仅适用于 ChromeOS，与 Verified Access Web API（用于提出质询和验证回答）结合使用。Verified Access Web API 验证成功，可以明确体现以下所有方面：* 当前设备是合法的 ChromeOS 设备。* 当前设备由验证期间指定的网域管理。* 当前登录的用户由验证期间指定的域管理。* 当前设备状态符合企业用户政策。例如，政策可能会指定设备不得处于开发者模式。* 验证过程发出的公钥与当前设备的硬件和当前登录的用户紧密绑定。此函数受到严格限制，如果当前设备不是受管理设备、当前用户不是受管理用户，或者企业用户政策未为调用方明确启用此操作，则会失败。企业用户密钥不在 "user" 令牌中，并且无法通过任何其他 API 访问。

参数

  • 挑战

    ArrayBuffer

    Verified Access Web API 发出的质询。

  • registerKey

    布尔值

    如果设置了此字段，系统会使用 "user" 令牌注册当前的 Enterprise User Key 角色，并放弃 Enterprise User Key 角色。然后，该密钥可与证书关联，并像使用其他签名密钥一样使用。此密钥是 2048 位 RSA。然后，对此函数的后续调用将生成新的企业用户密钥。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (response: ArrayBuffer) => void

    • Response

      ArrayBuffer

      质询响应。

返回

  • Promise&lt;ArrayBuffer&gt;

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。

getCertificates()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

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

参数

  • tokenId

    字符串

    getTokens 返回的令牌的 ID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (certificates: ArrayBuffer[]) => void

    • certificates

      ArrayBuffer[]

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

返回

  • Promise&lt;ArrayBuffer[]&gt;

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。

getTokens()

prometido 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

返回可用的令牌。在普通用户的会话中，列表中始终包含包含 id "user" 的用户令牌。如果有可用的系统级 TPM 令牌，返回的列表还会包含具有 id "system" 的系统级令牌。此设备（对于 Chromebook 等设备）的所有会话的系统级令牌都是相同的。

参数

  • callback

    函数（可选）

    callback 参数如下所示： 

    (tokens: Token[]) => void

    • 词元

      令牌[]

      可用令牌的列表。

返回

  • Promise<令牌 []>

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。

importCertificate()

prometido 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

如果已在给定令牌中存储经过认证的密钥，则将 certificate 导入到该令牌。成功发出认证请求后，应使用此函数存储所获取的证书，并将其提供给操作系统和浏览器以进行身份验证。

参数

  • tokenId

    字符串

    getTokens 返回的令牌的 ID。

  • 证书

    ArrayBuffer

    X.509 证书的 DER 编码。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。promise 的解析结果与传递给回调的类型相同。

removeCertificate()

prometido 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

从给定令牌中移除 certificate（如果存在）。应用于移除已废弃的证书，以免在身份验证期间不考虑这些证书，也不会使证书选择过于繁杂。应用于释放证书存储区中的存储空间。

参数

  • tokenId

    字符串

    getTokens 返回的令牌的 ID。

  • 证书

    ArrayBuffer

    X.509 证书的 DER 编码。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    待处理

    Manifest V3 及更高版本支持 Promise，但为以下项目提供回调： 向后兼容性您不能在同一个函数调用中同时使用这两者。通过 promise 使用传递给回调的类型进行解析。