chrome.enterprise.platformKeys

說明

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

權限

enterprise.platformKeys

可用性

僅限 ChromeOS 需要政策

用量

使用這個 API 註冊用戶端憑證的一般步驟如下:

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

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

  • 使用 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]),  // 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

    如果有的話,請使用指定的 scope 權杖,將挑戰金鑰註冊。接著,您可以將金鑰與憑證建立關聯,並像其他簽署金鑰一樣使用。後續呼叫這個函式時,系統會在指定的 scope 中產生新的 Enterprise 金鑰。

  • 範圍

    要驗證哪個 Enterprise 金鑰。

RegisterKeyOptions

Chrome 110 以上版本

屬性

  • 演算法

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

Scope

Chrome 110 以上版本

是否使用 Enterprise 使用者金鑰或 Enterprise 機器金鑰。

列舉

"USER"

"MACHINE"

Token

屬性

  • id

    字串

    這個 Token 的專屬 ID。

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以上版本

    實作 WebCrypto 的 SubtleCrypto 介面。加密編譯作業 (包括產生金鑰) 是由軟體提供支援。金鑰的保護機制,以及不可擷取屬性的實作方式,都是在軟體中完成,因此金鑰的保護機制不如硬體支援金鑰。

    您只能產生無法擷取的 RSASSA-PKCS1-V1_5 金鑰,且 modulusLength 最多只能為 2048。每個金鑰最多只能用於簽署資料一次。

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

  • subtleCrypto

    SubtleCrypto

    實作 WebCrypto 的 SubtleCrypto 介面。密碼編譯作業 (包括金鑰產生作業) 均由硬體支援。

    您只能產生不可擷取的 RSASSA-PKCS1-V1_5 金鑰 (modulusLength 最多為 2048),以及 ECDSA (namedCurve P-256)。每個金鑰最多只能用於簽署資料一次。

    在特定 Token 上產生的金鑰無法與任何其他權杖搭配使用,也無法與 window.crypto.subtle 搭配使用。同樣地,使用 window.crypto.subtle 建立的 Key 物件也無法與此介面搭配使用。

方法

challengeKey()

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

challengeMachineKeychallengeUserKey 類似,但可指定註冊金鑰的演算法。對硬體支援 Enterprise 機器金鑰進行驗證,並發出回應做為遠端認證通訊協定的一部分。僅適用於 ChromeOS,且必須搭配 Verified Access Web API 使用,才能發出挑戰並驗證回應。

Verified Access Web API 成功驗證後,系統會發出強烈信號,表示目前的裝置是合法的 ChromeOS 裝置、目前的裝置由驗證期間指定的網域管理、目前登入的使用者由驗證期間指定的網域管理,且目前的裝置狀態符合企業裝置政策。例如,政策可能會指定裝置不得進入開發人員模式。驗證程序產生的任何裝置身分都會與目前裝置的硬體緊密連結。如果指定 "user" 範圍,身分也會與目前登入的使用者緊密連結。

這項功能受到嚴格限制,如果目前的裝置未受管理、目前的使用者未受管理,或是企業裝置政策未明確為呼叫端啟用這項作業,就會失敗。挑戰金鑰不會位於 "system""user" 權杖中,也無法透過任何其他 API 存取。

參數

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

  • 回呼

    函式 選填

    callback 參數如下所示:

    (response: ArrayBuffer) => void

    • 回應

      ArrayBuffer

      挑戰回應。

傳回

  • Promise<ArrayBuffer>

    待處理

    承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。

challengeMachineKey()

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

請改用 challengeKey

挑戰硬體支援 Enterprise 機器金鑰,並將回應發送為遠端認證通訊協定的一部分。這項 API 僅適用於 ChromeOS,且必須搭配 Verified Access Web API 使用,才能發出挑戰並驗證回應。透過已驗證存取權 Web API 成功驗證,表示下列所有情況:* 目前的裝置是合法的 ChromeOS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者由驗證期間指定的網域管理。* 目前的裝置狀態符合企業裝置政策。舉例來說,政策可能會指定裝置不得處於開發人員模式。* 驗證程序產生的任何裝置身分都會與目前裝置的硬體緊密結合。如果目前的裝置未受管理、目前的使用者未受到管理,或是尚未根據企業裝置政策明確啟用呼叫端,這項功能就受到高度限制,因此函式將會失敗。企業機器金鑰不會儲存在 "system" 權杖中,也無法透過任何其他 API 存取。

參數

  • 挑戰

    ArrayBuffer

    由 Verified Access Web API 發出的挑戰。

  • registerKey

    boolean 選填

    Chrome 59 以上版本

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

  • 回呼

    函式 選填

    callback 參數如下所示:

    (response: ArrayBuffer) => void

    • 回應

      ArrayBuffer

      挑戰回應。

傳回

  • Promise<ArrayBuffer>

    待處理

    承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。

challengeUserKey()

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

請改用 challengeKey

驗證硬體支援的 Enterprise 使用者金鑰,並在遠端認證通訊協定中發出回應。這項 API 僅適用於 ChromeOS,且必須搭配 Verified Access Web API 使用,才能發出挑戰並驗證回應。透過已驗證存取權 Web API 成功驗證,表示下列所有情況:* 目前的裝置是合法的 ChromeOS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者由驗證期間指定的網域管理。* 目前的裝置狀態符合企業使用者政策。例如,政策可能會指定裝置不得進入開發人員模式。* 驗證程序產生的公開金鑰,會與目前裝置的硬體和目前登入的使用者緊密連結。這項功能受到嚴格限制,如果目前裝置未受管理、目前使用者未受管理,或是企業使用者政策未明確為呼叫端啟用這項作業,就會失敗。企業使用者金鑰不會位於 "user" 權杖中,也無法透過任何其他 API 存取。

參數

  • 挑戰

    ArrayBuffer

    由 Verified Access Web API 發出的挑戰。

  • registerKey

    布林值

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

  • 回呼

    函式 選填

    callback 參數如下所示:

    (response: ArrayBuffer) => void

    • 回應

      ArrayBuffer

      挑戰回應。

傳回

  • Promise<ArrayBuffer>

    待處理

    Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。

getCertificates()

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

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

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 回呼

    函式 選填

    callback 參數如下所示:

    (certificates: ArrayBuffer[]) => void

    • certificates

      ArrayBuffer[]

      憑證清單,每個憑證均採用 X.509 憑證的 DER 編碼。

傳回

  • Promise<ArrayBuffer[]>

    待處理

    承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。

getTokens()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示:

    (tokens: Token[]) => void

    • 符記

      可用權杖清單。

傳回

  • Promise<Token[]>

    待處理

    承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。

importCertificate()

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

如果已將認證金鑰儲存在這個權杖中,就會將 certificate 匯入至指定的權杖。認證要求成功後,應使用這項功能儲存取得的憑證,並讓作業系統和瀏覽器可用於驗證。

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • 回呼

    函式 選填

    callback 參數如下所示:

    () => void

傳回

  • Promise<void>

    待處理

    承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。

removeCertificate()

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

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

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • 回呼

    函式 選填

    callback 參數如下所示:

    () => void

傳回

  • Promise<void>

    待處理

    承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。