chrome.enterprise.platformKeys

說明

請使用 chrome.enterprise.platformKeys API 產生金鑰並安裝這些金鑰的憑證。憑證會由平台管理，並可用於 TLS 驗證、網路存取，或透過 chrome.platformKeys 用於其他擴充功能。

權限

enterprise.platformKeys

適用國家/地區

僅限 ChromeOS 需要政策

概念和用法

使用此 API 註冊用戶端憑證的一般使用步驟如下：

  • 使用 enterprise.platformKeys.getTokens() 取得所有可用的權杖。

  • 找出 id 等於 "user" 的符記。之後請使用這個權杖。

  • 使用 generateKey() 權杖方法 (在 SubtleCrypto 中定義) 產生金鑰組。這會將控制代碼傳回到鍵。

  • 使用 exportKey() Token 方法 (在 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 以上版本

要產生的金鑰類型。

列舉

ChallengeKeyOptions

Chrome 110 以上版本

屬性

  • 挑戰

    ArrayBuffer

    Verified Access Web API 產生的驗證問題。

  • registerKey

    RegisterKeyOptions 選用

    如有，請使用指定 scope 的權杖註冊驗證的金鑰。接著，這組金鑰就能與憑證建立關聯，使用方式與其他簽署金鑰相同。後續呼叫這個函式時，系統會在指定的 scope 中產生新的 Enterprise 金鑰。

  • 範圍

    範圍

    要挑戰哪一個 Enterprise 金鑰。

RegisterKeyOptions

Chrome 110 以上版本

屬性

  • 演算法

    演算法

    已註冊金鑰應使用的演算法。

Scope

Chrome 110 以上版本

要使用 Enterprise 使用者金鑰還是企業機器金鑰。

列舉

Token

屬性

  • ID

    字串

    專門用於識別這個 Token。

    靜態 ID 有 "user" 和 "system"，分別是指平台的使用者專屬和全系統硬體權杖。enterprise.platformKeys.getTokens 可能傳回任何其他權杖 (包含其他 ID)。

  • 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 且採用 namedCurve P-256 的不可擷取 RSASSA-PKCS1-V1_5 金鑰，以及採用 namedCurve P-256 的 ECDSA。每個金鑰最多只能用於簽署資料。

    在特定 Token 上產生的金鑰無法與其他權杖一起使用，也不能與 window.crypto.subtle 搭配使用。同樣地，透過 window.crypto.subtle 建立的 Key 物件無法透過這個介面使用。

方法

challengeKey()

Chrome 110 以上版本 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback: function,
)

與 challengeMachineKey 和 challengeUserKey 類似，但允許指定已註冊金鑰的演算法。挑戰硬體支援 Enterprise 機器金鑰，並將回應發送為遠端認證通訊協定的一部分。這項功能僅適用於 Chrome 作業系統，而且搭配 Verified Access Web API 使用時，會一併出現問題及驗證回應。

Verified Access Web API 驗證成功後，就表示目前裝置是合法的 Chrome OS 裝置，目前的裝置是由驗證期間指定的網域進行管理、目前登入的使用者是由驗證時指定的網域管理，而目前裝置狀態符合企業裝置政策。例如，政策可能會指定裝置不得進入開發人員模式。因為驗證產生的裝置身分都會緊密繫結至目前裝置的硬體。如果指定 "user" 範圍，該身分也會盡可能綁定目前登入的使用者。

如果目前的裝置未受管理、目前的使用者未受到管理，或是尚未根據企業裝置政策明確啟用呼叫端，這項功能會受到高度限制，因此函式將會失敗。驗證過的金鑰不在 "system" 或 "user" 權杖中，任何其他 API 皆無法存取。

參數

  • 包含 ChallengeKeyOptions 中定義的欄位的物件。

  • 回呼

    功能

    callback 參數如下所示： 

    (response: ArrayBuffer) => void

    • 則回應

      ArrayBuffer

      挑戰回應。

challengeMachineKey()

Chrome 50 以上版本 自 Chrome 110 版起已淘汰
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

請改用 challengeKey。

挑戰硬體支援 Enterprise 機器金鑰，並將回應發送為遠端認證通訊協定的一部分。這項功能僅適用於 Chrome 作業系統，而且搭配 Verified Access Web API 使用時，會一併出現問題及驗證回應。Verified Access Web API 成功驗證後，通常代表確認下列事項：* 目前使用的裝置是合法的 Chrome OS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。* 目前裝置狀態符合企業裝置政策。例如，政策可能會指定裝置不得進入開發人員模式。* 驗證程序產生的裝置身分都會緊密地與目前裝置的硬體綁定。如果目前的裝置未受管理、目前的使用者未受到管理，或是尚未根據企業裝置政策明確啟用呼叫端，這項功能會受到高度限制，因此函式將會失敗。企業機器金鑰不會存放在 "system" 權杖中，其他任何 API 皆無法存取。

參數

  • 挑戰

    ArrayBuffer

    Verified Access Web API 產生的驗證問題。

  • registerKey

    布林值 選填

    Chrome 59 以上版本

    如果設定，目前的 Enterprise 機器金鑰會以 "system" 權杖註冊，並放棄 Enterprise 機器金鑰角色。接著，這組金鑰就能與憑證建立關聯，使用方式與其他簽署金鑰相同。這組金鑰為 2048 位元 RSA。後續呼叫這個函式時，系統會產生新的 Enterprise 機器金鑰。

  • 回呼

    功能

    callback 參數如下所示： 

    (response: ArrayBuffer) => void

    • 則回應

      ArrayBuffer

      挑戰回應。

challengeUserKey()

Chrome 50 以上版本 自 Chrome 110 版起已淘汰
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

請改用 challengeKey。

驗證硬體支援的 Enterprise 使用者金鑰，並在遠端認證通訊協定中發出回應。這項功能僅適用於 Chrome 作業系統，而且搭配 Verified Access Web API 使用時，會一併出現問題及驗證回應。Verified Access Web API 成功驗證後，通常代表確認下列事項：* 目前使用的裝置是合法的 Chrome OS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。* 目前裝置狀態符合企業使用者政策。例如，政策可能會指定裝置不得進入開發人員模式。* 驗證產生的公開金鑰與目前裝置的硬體和目前登入使用者的公開金鑰緊密繫結。如果目前的裝置未受管理、目前的使用者未受到管理，或是尚未根據企業使用者政策明確啟用呼叫端，這項功能就受到高度限制，因此函式將會失敗。無法將 Enterprise 使用者金鑰存放在 "user" 權杖中，其他任何 API 皆無法存取。

參數

  • 挑戰

    ArrayBuffer

    Verified Access Web API 產生的驗證問題。

  • registerKey

    boolean

    設定後，系統會使用 "user" 權杖註冊目前的 Enterprise 使用者金鑰，並退出 Enterprise 使用者金鑰角色。接著，這組金鑰就能與憑證建立關聯，使用方式與其他簽署金鑰相同。這組金鑰為 2048 位元 RSA。之後呼叫這個函式時，系統會產生新的 Enterprise 使用者金鑰。

  • 回呼

    功能

    callback 參數如下所示： 

    (response: ArrayBuffer) => void

    • 則回應

      ArrayBuffer

      挑戰回應。

getCertificates()

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

傳回指定權杖可用的所有用戶端憑證清單。可用於檢查適用於特定驗證的用戶端憑證是否存在與到期日。

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 回呼

    功能

    callback 參數如下所示： 

    (certificates: ArrayBuffer[]) => void

    • certificates

      ArrayBuffer[]

      憑證清單，每個憑證都以 DER 編碼為 X.509 憑證。

getTokens()

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

傳回可用的權杖。在一般使用者的工作階段中，清單一律會包含具有 id "user" 的使用者權杖。如果有系統通用的 TPM 權杖，傳回的清單也會包含具有 id "system" 的全系統權杖。這部裝置上所有工作階段 (例如 Chromebook 等裝置) 的系統全系統符記均相同。

參數

  • 回呼

    功能

    callback 參數如下所示： 

    (tokens: Token[]) => void

    • 權杖

      符記[]

      可用權杖清單。

importCertificate()

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

如果這個權杖中已儲存認證金鑰，將 certificate 匯入指定權杖。認證申請成功後，應使用此函式儲存已取得的憑證，供作業系統和瀏覽器使用，以便進行驗證。

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

removeCertificate()

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

從指定權杖中移除 certificate (如有)。應用於移除過時的憑證，以免系統在驗證期間考慮這些憑證，也不會讓憑證選擇過於雜亂。應用於憑證存放區中的可用儲存空間。

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void