chrome.enterprise.platformKeys

說明

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

權限

enterprise.platformKeys

可用性

僅適用於 ChromeOS 需要政策

概念與用途

使用這項 API 註冊用戶端憑證的典型做法如下：

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

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

  • 使用 generateKey() Token 方法 (定義於 SubtleCrypto) 產生金鑰組。這會傳回金鑰的控制代碼。

  • 使用 exportKey() Token 方法 (定義於 SubtleCrypto) 匯出公開金鑰。

  • 使用 sign() Token 方法 (在 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」

"ECDSA"

ChallengeKeyOptions

Chrome 110 以上版本

屬性

  • 挑戰

    ArrayBuffer

    由 Verified Access Web API 發出的驗證問題。

  • registerKey

    RegisterKeyOptions 選用

    如果存在，則會使用指定的 scope 權杖註冊受質詢的金鑰。然後，金鑰可以與憑證建立關聯，並像其他簽署金鑰一樣使用。後續呼叫這個函式時，系統會在指定的 scope 中產生新的企業金鑰。

  • 範圍

    範圍

    要驗證的 Enterprise 金鑰。

RegisterKeyOptions

Chrome 110 以上版本

屬性

  • 演算法

    演算法

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

Scope

Chrome 110 以上版本

是否要使用 Enterprise User Key 或 Enterprise Machine Key。

列舉

「USER」

「MACHINE」

Token

屬性

  • id

    字串

    專門用於識別這個 Token。

    靜態 ID 為 "user" 和 "system"，分別是指平台的使用者專屬和系統層級硬體權杖。enterprise.platformKeys.getTokens 可能會傳回其他權杖 (連同其他 ID)。

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以上版本

    實作 WebCrypto 的 SubtleCrypto 介面。包括金鑰產生作業在內的加密編譯作業，都是由軟體支援。金鑰的保護措施 (因此也包括不可擷取屬性的實作) 是透過軟體完成，因此金鑰的保護力不如硬體支援金鑰。

    只能產生不可擷取的金鑰。支援的金鑰類型為 RSASSA-PKCS1-V1_5 和 RSA-OAEP (Chrome 135 以上版本)，modulusLength 最多為 2048。除非透過 KeyPermissions 政策將擴充功能加入允許清單，否則每個 RSASSA-PKCS1-V1_5 金鑰最多只能用於簽署資料一次，加入允許清單後則可無限次使用。Chrome 135 以上版本支援 RSA-OAEP 金鑰，且可供透過相同政策加入允許清單的擴充功能，用來解開其他金鑰。

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

  • subtleCrypto

    SubtleCrypto

    實作 WebCrypto 的 SubtleCrypto 介面。包括金鑰產生作業在內的加密編譯作業，都由硬體支援。

    只能產生不可擷取的金鑰。支援的金鑰類型為 RSASSA-PKCS1-V1_5 和 RSA-OAEP (Chrome 135 以上版本)，modulusLength 最多 2048 個，以及 ECDSA，namedCurve 最多 P-256 個。除非擴充功能透過 KeyPermissions 政策加入允許清單，否則每個 RSASSA-PKCS1-V1_5 和 ECDSA 金鑰最多只能用於簽署資料一次，加入允許清單後則可無限次使用。Chrome 135 以上版本支援 RSA-OAEP 金鑰，且可供透過相同政策加入允許清單的擴充功能，用來解開其他金鑰。

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

方法

challengeKey()

Chrome 110 以上版本 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

與 challengeMachineKey 和 challengeUserKey 類似，但允許指定已註冊金鑰的演算法。挑戰硬體支援的企業電腦金鑰，並在遠端認證通訊協定中發出回應。僅適用於 ChromeOS，且必須搭配 Verified Access Web API 使用，才能發出驗證問題並驗證回應。

如果「已驗證存取權」Web API 驗證成功，就表示目前的裝置是正版 ChromeOS 裝置、目前的裝置由驗證期間指定的網域管理、目前登入的使用者由驗證期間指定的網域管理，且目前的裝置狀態符合企業裝置政策。舉例來說，政策可能會規定裝置不得處於開發人員模式。驗證程序發出的任何裝置 ID 都會與目前裝置的硬體緊密繫結。如果指定 "user" 範圍，身分也會緊密繫結至目前登入的使用者。

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

參數

傳回

  • Promise<ArrayBuffer>

    Chrome 131 以上版本

challengeMachineKey()

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

請改用 challengeKey。

挑戰硬體支援的企業電腦金鑰，並在遠端認證通訊協定中發出回應。僅適用於 ChromeOS，且必須搭配 Verified Access Web API 使用，才能發出驗證問題並驗證回應。如果已驗證存取權 Web API 驗證成功，則表示：* 目前的裝置是正版 ChromeOS 裝置。* 目前裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。* 目前裝置狀態符合企業裝置政策。舉例來說，政策可能會規定裝置不得處於開發人員模式。* 驗證程序發出的任何裝置 ID 都會與目前裝置的硬體緊密繫結。這項功能受到嚴格限制，如果目前的裝置或使用者未受管理，或是企業裝置政策未明確為呼叫者啟用這項作業，就會失敗。企業機器金鑰不會存在於 "system" 權杖中，且任何其他 API 都無法存取。

參數

  • 挑戰

    ArrayBuffer

    由 Verified Access Web API 發出的驗證問題。

  • registerKey

    布林值 選填

    Chrome 59 以上版本

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

傳回

  • Promise<ArrayBuffer>

    Chrome 131 以上版本

challengeUserKey()

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

請改用 challengeKey。

對硬體支援的企業使用者金鑰發出質詢，並根據遠端認證通訊協定發出回應。僅適用於 ChromeOS，且必須搭配 Verified Access Web API 使用，才能發出驗證問題並驗證回應。如果已驗證存取權 Web API 驗證成功，則表示：* 目前的裝置是正版 ChromeOS 裝置。* 目前裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。* 目前裝置狀態符合企業使用者政策。舉例來說，政策可能會規定裝置不得處於開發人員模式。* 驗證程序發出的公開金鑰會與目前裝置的硬體和目前登入的使用者緊密繫結。這項功能受到嚴格限制，如果目前的裝置或使用者未受管理，或是企業使用者政策未明確為呼叫者啟用這項作業，就會失敗。企業使用者金鑰不會存在於 "user" 權杖中，且任何其他 API 都無法存取。

參數

  • 挑戰

    ArrayBuffer

    由 Verified Access Web API 發出的驗證問題。

  • registerKey

    布林值

    如果設定，系統會使用 "user" 權杖註冊目前的企業使用者金鑰，並放棄企業使用者金鑰角色。然後，金鑰可以與憑證建立關聯，並像其他簽署金鑰一樣使用。這組金鑰為 2048 位元 RSA。後續對這個函式的呼叫會產生新的企業使用者金鑰。

傳回

  • Promise<ArrayBuffer>

    Chrome 131 以上版本

getCertificates()

chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

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

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

傳回

  • Promise<ArrayBuffer[]>

    Chrome 131 以上版本

getTokens()

chrome.enterprise.platformKeys.getTokens(): Promise<Token[]>

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

傳回

  • Promise<Token[]>

    Chrome 131 以上版本

importCertificate()

chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

如果認證金鑰已儲存在這個權杖中，則將 certificate 匯入至指定權杖。成功提出認證要求後，請使用這項函式儲存取得的憑證，並提供給作業系統和瀏覽器進行驗證。

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

傳回

  • Promise<void>

    Chrome 131 以上版本

removeCertificate()

chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

從指定權杖中移除 certificate (如有)。應移除過時的憑證，以免系統在驗證時考慮這些憑證，並避免憑證選項過於雜亂。應使用此函式釋放憑證存放區中的儲存空間。

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

傳回

  • Promise<void>

    Chrome 131 以上版本