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 以上版本

要產生的金鑰類型。

列舉

ChallengeKeyOptions

Chrome 110 以上版本

屬性

  • 挑戰

    ArrayBuffer

    Verified Access Web API 發出的挑戰。

  • registerKey

    RegisterKeyOptions 選用

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

  • 範圍

    範圍

    該詢問哪個 Enterprise 金鑰。

RegisterKeyOptions

Chrome 110 以上版本

屬性

  • 演算法

    演算法

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

Scope

Chrome 110 以上版本

要使用 Enterprise 使用者金鑰還是 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 以下的不可擷取 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 類似，但允許指定註冊金鑰的演算法。挑戰硬體支援的企業機器金鑰，然後發出回應，做為遠端認證通訊協定的一部分。這項功能僅適用於 Chrome OS，並與 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。

挑戰硬體支援的企業機器金鑰，然後發出回應，做為遠端認證通訊協定的一部分。這項功能僅適用於 Chrome OS，並與 Verified Access Web API 搭配使用，以便提出問題並驗證回應。如果 Verified Access Web API 成功通過驗證，即表示以下所有事項的訊號良好：* 目前的裝置是合法的 Chrome 作業系統裝置。* 目前的裝置是由驗證期間指定的網域所管理。* 目前的登入使用者是由驗證期間指定的網域所管理。* 目前裝置狀態符合企業裝置政策。舉例來說，政策可能會指定裝置不得處於開發人員模式。* 驗證程序發出的任何裝置身分都與目前裝置的硬體緊密連結。這項功能受到高度限制，如果目前的裝置未受到管理、目前的使用者未受到管理，或是企業裝置政策未明確針對呼叫端啟用這項功能，這項功能就會失敗。企業機器金鑰不會存放在 "system" 權杖中，也無法由其他 API 存取。

參數

  • 挑戰

    ArrayBuffer

    Verified Access Web API 發出的挑戰。

  • registerKey

    布林值 (選用)

    Chrome 59 以上版本

    如果已設定，系統就會以 "system" 權杖註冊目前的 Enterprise 機器金鑰，並放棄 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 OS，並與 Verified Access Web API 搭配使用，以便提出問題並驗證回應。如果 Verified Access Web API 成功通過驗證，即表示以下所有事項的訊號良好：* 目前的裝置是合法的 Chrome 作業系統裝置。* 目前的裝置是由驗證期間指定的網域所管理。* 目前的登入使用者是由驗證期間指定的網域所管理。* 目前裝置狀態符合企業使用者政策。舉例來說，政策可能會指定裝置不得處於開發人員模式。* 驗證作業發出的公開金鑰會與目前裝置的硬體和目前已登入的使用者緊密連結。這項功能受到高度限制，如果目前裝置未受到管理、目前的使用者未受到管理，或是企業使用者政策尚未明確針對呼叫端啟用這項功能，這項功能就會失敗。這個企業使用者金鑰不會存放在 "user" 權杖中，也無法由其他 API 存取。

參數

  • 挑戰

    ArrayBuffer

    Verified Access Web API 發出的挑戰。

  • registerKey

    boolean

    如果設定這項標記，系統會以 "user" 權杖註冊目前的企業使用者金鑰，並將「企業使用者金鑰」角色放棄。接著，金鑰可以與憑證建立關聯，並如同任何其他簽署金鑰一樣使用。這組金鑰為 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[]

      憑證清單，每個以 X.509 憑證的 DER 編碼呈現。

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