chrome.enterprise.platformKeys

這個 API 僅適用於由政策安裝的擴充功能。

重要事項： 這個 API僅適用於 ChromeOS。

說明

請使用 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()`[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 金鑰。

RegisterKeyOptions

Chrome 110 以上版本

屬性

• 演算法

  演算法

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

Scope

Chrome 110 以上版本

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

列舉

"USER"

"MACHINE"

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 介面。密碼編譯作業 (包括金鑰產生作業) 均由硬體支援。

  您只能產生不可擷取的 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,
)

與 challengeMachineKey 和 challengeUserKey 類似，但允許指定已註冊金鑰的演算法。挑戰硬體支援 Enterprise 機器金鑰，並將回應發送為遠端認證通訊協定的一部分。這項功能僅適用於 ChromeOS，也要搭配 Verified Access Web API 使用，既會遇到挑戰及驗證回應。

Verified Access Web API 成功完成驗證，表示目前裝置是合法的 ChromeOS 裝置，目前裝置由驗證期間指定的網域管理，目前登入的使用者由驗證期間指定的網域管理，且目前裝置狀態符合企業裝置政策。舉例來說，政策可能會指定裝置不得處於開發人員模式。因為驗證產生的裝置身分都會緊密繫結至目前裝置的硬體。如果指定 "user" 範圍，身分也會與目前登入的使用者緊密連結。

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

參數

• 選項

  ChallengeKeyOptions

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (response: ArrayBuffer) => void

  • 回應

    ArrayBuffer

    挑戰回應。

傳回

• Promise<ArrayBuffer>

  待處理

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

challengeMachineKey()

Promise Chrome 50 以上版本 自 Chrome 110 版起已淘汰

chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

請改用 challengeKey。

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

參數

• 挑戰

  ArrayBuffer

  由 Verified Access Web API 發出的挑戰。

• registerKey

  boolean 選填

  Chrome 59 以上版本

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

• 回呼

  函式 選用

  callback 參數如下所示：

  (response: ArrayBuffer) => void

  • 回應

    ArrayBuffer

    挑戰回應。

傳回

• Promise<ArrayBuffer>

  待處理

  Promise 適用於 Manifest 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" 權杖註冊目前的 Enterprise 使用者金鑰，並退出 Enterprise 使用者金鑰角色。接著，您可以將金鑰與憑證建立關聯，並像其他簽署金鑰一樣使用。這組金鑰為 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[]>

  待處理

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

getTokens()

Promise

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

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

參數

• 回呼

  函式 選填

  callback 參數如下所示：

  (tokens: Token[]) => void

  • 符記

    權杖[]

    可用權杖清單。

傳回

• Promise<Token[]>

  待處理

  Promise 適用於 Manifest 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>

  待處理

  Promise 適用於 Manifest 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>

  待處理

  Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。