browser.enterprise.platformKeys

說明

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

權限

enterprise.platformKeys

可用性

僅適用於 ChromeOS 需要政策

概念和用途

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

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

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

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

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

  • 使用 sign() Token 方法 (定義於 SubtleCrypto) 建立憑證要求的資料簽章。

  • 填寫憑證要求，並傳送給憑證授權單位。

  • 如果收到憑證，請使用 [enterprise.platformKeys.importCertificate()`[3] 匯入

以下範例顯示主要的 API 互動，但不包括建構及傳送認證要求：

function getUserToken(callback) {
  browser.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) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

類型

Algorithm

Chrome 110 以上版本 瀏覽器。*自 Chrome 148 起

要產生的金鑰類型。

列舉

「RSA」

"ECDSA"

ChallengeKeyOptions

Chrome 110 以上版本 瀏覽器。*自 Chrome 148 起

屬性

  • 挑戰

    ArrayBuffer

    Verified Access Web API 發出的已驗證存取權挑戰。

  • registerKey

    RegisterKeyOptions 選填

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

  • 範圍

    範圍

    要驗證哪個 Enterprise 金鑰。

RegisterKeyOptions

Chrome 110 以上版本 瀏覽器。*自 Chrome 148 起

屬性

  • 演算法

    演算法

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

Scope

Chrome 110 以上版本 瀏覽器。*自 Chrome 148 起

是否要使用企業版使用者金鑰或企業機器金鑰。

列舉

"USER"

"MACHINE"

Token

屬性

  • id

    字串

    專門用於識別這個 Token。

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 以上版本 瀏覽器。*自 Chrome 148 起

    實作 WebCrypto 的 SubtleCrypto 介面。加密編譯作業 (包括金鑰產生) 是由軟體支援。金鑰保護和不可擷取屬性的實作都是在軟體中完成，因此金鑰的保護程度低於硬體支援金鑰。

    只能產生不可擷取的金鑰。唯一支援的金鑰類型是 RSASSA-PKCS1-V1_5，modulusLength 最大為 2048。每個金鑰最多只能用於簽署資料一次，除非擴充功能已透過 KeyPermissions 政策加入許可清單，在這種情況下，金鑰可以無限期使用。

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

  • subtleCrypto

    SubtleCrypto

    實作 WebCrypto 的 SubtleCrypto 介面。加密編譯作業 (包括金鑰產生) 均採用專屬硬體。

    只能產生不可擷取的金鑰。支援的金鑰類型為 RSASSA-PKCS1-V1_5 (modulusLength 最大 2048) 和 ECDSA (namedCurve P-256)。每個金鑰最多只能用於簽署資料一次，除非擴充功能已加入 KeyPermissions 政策許可清單，在這種情況下，金鑰可以無限期使用。

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

方法

challengeKey()

Chrome 110 以上版本 瀏覽器。*自 Chrome 148 起 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

與 challengeMachineKey 和 challengeUserKey 類似，但可指定已註冊金鑰的演算法。對硬體支援的企業機器金鑰發出驗證要求，並將回應做為遠端認證通訊協定的一部分。僅適用於 ChromeOS，且須搭配已驗證存取權 Web API 使用，該 API 會發出驗證問題並驗證回應。

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

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

參數

傳回

  • <ArrayBuffer> 承諾

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    傳回 Promise，並以驗證問題回應解析。

challengeMachineKey()

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

請改用 challengeKey。

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

參數

  • 挑戰

    ArrayBuffer

    Verified Access Web API 發出的已驗證存取權挑戰。

  • registerKey

    布林值 選填

    Chrome 59 以上版本 Chrome 148 以上版本的瀏覽器。*

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

傳回

  • <ArrayBuffer> 承諾

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    傳回 Promise，並以驗證問題回應解析。

challengeUserKey()

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

請改用 challengeKey。

驗證採用專屬硬體的企業版使用者金鑰，並將回應做為遠端認證通訊協定的一部分。僅適用於 ChromeOS，且須搭配 Verified Access Web API 使用，後者會發出驗證問題並驗證回應。如果 Verified Access Web API 驗證成功，即表示：* 目前的裝置是合法的 ChromeOS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。目前的裝置狀態符合企業版使用者政策。舉例來說，政策可能會指定裝置不得處於開發人員模式。* 驗證作業產生的公開金鑰會與目前裝置的硬體和目前登入的使用者緊密繫結。這項功能受到嚴格限制，如果目前裝置或使用者不受管理，或企業使用者政策未明確為呼叫端啟用這項作業，就會失敗。企業使用者金鑰不會儲存在 "user" 權杖中，其他 API 也無法存取。

參數

  • 挑戰

    ArrayBuffer

    Verified Access Web API 發出的已驗證存取權挑戰。

  • registerKey

    布林值

    如果設定這項政策，目前的企業版使用者金鑰會註冊 "user" 權杖，並放棄企業版使用者金鑰角色。接著，金鑰可以與憑證建立關聯，並像其他簽署金鑰一樣使用。這組金鑰是 2048 位元 RSA。之後呼叫這個函式時，就會產生新的企業版使用者金鑰。

傳回

  • <ArrayBuffer> 承諾

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    傳回 Promise，並以驗證問題回應解析。

getCertificates()

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

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

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

傳回

  • Promise<ArrayBuffer[]>

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    傳回 Promise，其中包含可用憑證清單。

getTokens()

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

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

傳回

  • Promise<Token[]>

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    由 getTokens 叫用，並提供可用權杖清單。

importCertificate()

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

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

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 憑證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

傳回

  • 承諾<void>

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    傳回 Promise，會在作業完成時解析。

removeCertificate()

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

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

參數

  • tokenId

    字串

    getTokens 傳回的權杖 ID。

  • 憑證

    ArrayBuffer

    X.509 憑證的 DER 編碼。

傳回

  • 承諾<void>

    Chrome 131 以上版本 Chrome 148 起支援 browser.*

    傳回 Promise，會在作業完成時解析。