该 API 还在 beta 测试中,仅对 beta 分支dev 分支的 Chrome 用户可用。

chrome.enterprise.platformKeys

描述 使用 chrome.enterprise.platformKeys API 生成由硬件产生的密钥,并为这些密钥安装证书。这些证书安装后可以在平台中使用,例如可用于 TLS 认证和网络访问。
可用版本 从 Chrome 37 开始支持。警告:目前为 Beta 分支。了解更多内容
权限 "enterprise.platformKeys"

注意:该 API 仅在 Chrome OS 上可用,并且仅适用于通过策略预先安装的扩展程序

用法

该 API 的典型用法涉及到客户端证书,遵循如下步骤:
  • 使用 enterprise.platformKeys.getTokens 获取所有可用令牌。
  • 找出 id 等于 "user" 的 Token 对象,接下来使用它。
  • 通过令牌对象的 generateKey 方法(在 SubtleCrypto 中定义)生成密钥对,该方法会返回密钥句柄。
  • 通过令牌对象的 exportKey 方法(在 SubtleCrypto 中定义)导出公钥。
  • 通过令牌对象的 sign 方法(在 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]),  // 等价于 65537
          hash: {
            name: "SHA-1",
          }
        };
        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) {
                  // 使用公钥建立证书请求。
                  return userToken.subtleCrypto.sign(
                      {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);
                },
                console.log.bind(console))
          .then(function(signature) {
                    // 根据 |signature| 完成证书请求,将请求发送至
                    // CA,并调用 onClientCertificateReceived。
                },
                console.log.bind(console));
      }
      
      function onClientCertificateReceived(userToken, certificate) {
        chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
      }
      
      getUserToken(generateAndSign);
      

摘要

类型
Token
方法
getTokens chrome.enterprise.platformKeys.getTokens(function callback)
getCertificates chrome.enterprise.platformKeys.getCertificates(string tokenId, function callback)
importCertificate chrome.enterprise.platformKeys.importCertificate(string tokenId, ArrayBuffer certificate, function callback)
removeCertificate chrome.enterprise.platformKeys.removeCertificate(string tokenId, ArrayBuffer certificate, function callback)

类型

Token

属性
string id

唯一标志 Token

静态标识符包括 "user""system",分别对应平台中特定用户和整个系统的硬件令牌,其他令牌(有不同的标识符)由 enterprise.platformKeys.getTokens 返回。

SubtleCrypto subtleCrypto

实现 WebCrypto 的 SubtleCrypto 接口,其中的加密操作,包括密钥生成,都是由硬件进行的。

只能生成 modulusLength 不超过 2048 的不可提取 RSASSA-PKCS1-V1_5 密钥,为数据签名时每个密钥只能使用一次。

某个 Token(令牌)生成的密钥不能和其他令牌一起使用,也不能和 window.crypto.subtle 一起使用。同样的,window.crypto.subtle 创建的 Key 对象也不能和该接口一起使用。

方法

getTokens

chrome.enterprise.platformKeys.getTokens(function callback)

返回可用的令牌。在通常的用户会话中,返回的列表一定包含用户令牌,id"user"。如果整个系统的 TPM 令牌可用,返回的列表还会包含整个系统的令牌,id"system"。整个系统的令牌对该设备上的所有会话都相同(设备也就是 Chromebook)。

参数
function callback

getTokens 调用,返回可用令牌。

callback 参数应该是一个如下形式的函数:

function(array of Token tokens) {...};
array of Token tokens

可用令牌的列表。

getCertificates

chrome.enterprise.platformKeys.getCertificates(string tokenId, function callback)

返回指定令牌中所有可用的客户端证书列表,可以用来检查某一次认证中客户端证书是否存在和过期。

参数
string tokenId

getTokens 返回的令牌标识符。

function callback

调用时返回可用证书列表。

callback 参数应该是一个如下形式的函数:

function(array of ArrayBuffer certificates) {...};
array of ArrayBuffer certificates

证书列表,全都为 X.509 证书以 DER 编码方式表示。

importCertificate

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

certificate(证书)导入到指定令牌(如果证书密钥已经存储在该令牌中)。证书请求成功后,应该调用该函数存储获得的证书,以便使操作系统和浏览器可以利用它进行认证。

参数
string tokenId

getTokens 返回的令牌标识符。

ArrayBuffer certificate

以 DER 编码方式表示的 X.509 证书。

function (可选)
callback

操作完成后调用。

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function() {...};

removeCertificate

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

参数
string tokenId

The id of a Token returned by getTokens. 从指定令牌中删除 certificate(证书)(如果存在的话),应该用于删除废弃的证书,因此在认证中不再考虑它们,而不会干扰证书的选择,还可以用于释放证书存储区的空间。

ArrayBuffer certificate

以 DER 编码方式表示的 X.509 证书。

function (可选)
callback

操作完成后调用。

如果您指定了 callback 参数,它应该是一个如下形式的函数:

function() {...};