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()`[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 使用者金鑰或 Enterprise 機器金鑰。

列舉

"USER"

"MACHINE"

Token

屬性

  • id

    字串

    可明確識別這個 Token。

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以上版本

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

    只能產生無法擷取的金鑰。支援的金鑰類型包括 RSASSA-PKCS1-V1_5 和 RSA-OAEP，modulusLength 最多可達 2048。每個 RSASSA-PKCS1-V1_5 金鑰最多只能用於簽署資料一次，除非擴充功能已透過 KeyPermissions 政策列入許可清單，否則金鑰可無限期使用。在同一個政策中，允許清單中的擴充功能可以使用 RSA-OAEP 金鑰解除其他金鑰的包裝。

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

  • subtleCrypto

    SubtleCrypto

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

    只能產生無法擷取的金鑰。支援的金鑰類型包括 RSASSA-PKCS1-V1_5 和 RSA-OAEP (modulusLength 最多 2048)，以及 ECDSA (namedCurve P-256)。每個 RSASSA-PKCS1-V1_5 和 ECDSA 金鑰最多只能用於簽署資料一次，除非透過 KeyPermissions 政策將擴充功能加入許可清單，否則金鑰可無限期使用。在同一個政策中，允許清單中的擴充功能可以使用 RSA-OAEP 金鑰解除其他金鑰的包裝。

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

方法

challengeKey()

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

與 challengeMachineKey 和 challengeUserKey 類似，但可指定註冊金鑰的演算法。挑戰硬體支援的企業機器金鑰，並在遠端認證通訊協定中發出回應。僅適用於 ChromeOS，並搭配使用 Verified Access Web API，可發出挑戰並驗證回應。

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

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

參數

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (response: ArrayBuffer) => void

    • 回應

      ArrayBuffer

      挑戰回應。

傳回

  • Promise<ArrayBuffer>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

challengeMachineKey()

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

請改用 challengeKey。

挑戰硬體支援的企業機器金鑰，並在遠端認證通訊協定中發出回應。這項 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>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

challengeUserKey()

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

請改用 challengeKey。

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

參數

  • 挑戰

    ArrayBuffer

    由 Verified Access Web API 發出的挑戰。

  • registerKey

    布林值

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

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (response: ArrayBuffer) => void

    • 回應

      ArrayBuffer

      挑戰回應。

傳回

  • Promise<ArrayBuffer>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getCertificates()

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

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

參數

  • tokenId

    字串

    由 getTokens 傳回的權杖 ID。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (certificates: ArrayBuffer[]) => void

    • certificates

      ArrayBuffer[]

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

傳回

  • Promise<ArrayBuffer[]>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

getTokens()

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

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

參數

  • 回呼

    函式 選填

    callback 參數如下所示： 

    (tokens: Token[]) => void

    • 符記

      權杖[]

      可用權杖清單。

傳回

  • Promise<Token[]>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

importCertificate()

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

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

參數

  • tokenId

    字串

    由 getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。

removeCertificate()

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

從指定的符記中移除 certificate (如果有的話)。應用於移除過時的憑證，以便在驗證期間不考慮這些憑證，並避免憑證選項過於雜亂。應用於釋放憑證存放區中的儲存空間。

參數

  • tokenId

    字串

    由 getTokens 傳回的權杖 ID。

  • 認證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

  • 回呼

    函式 選填

    callback 參數如下所示： 

    () => void

傳回

  • Promise<void>

    Chrome 131 以上版本

    承諾在資訊清單 3 以上版本中受支援，但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。