說明
使用 chrome.enterprise.platformKeys
API 產生金鑰,並為這些金鑰安裝憑證。憑證會由平台管理,可用於 TLS 驗證、網路存取,或透過 chrome.platformKeys 由其他擴充功能使用。
權限
enterprise.platformKeys
可用性
用量
使用這個 API 註冊用戶端憑證的一般步驟如下:
使用 enterprise.platformKeys.getTokens 取得所有可用的權杖。
找出
id
等於"user"
的符記。之後請使用這個權杖。使用
generateKey
權杖方法 (在 SubtleCrypto 中定義) 產生金鑰組。這會傳回鍵的句柄。使用
exportKey
權杖方法 (在 SubtleCrypto 中定義) 匯出公開金鑰。使用
sign
權杖方法 (在 SubtleCrypto 中定義) 建立認證要求資料的簽名。填妥認證申請表,並將表單送交認證機構。
如果收到憑證,請使用 enterprise.platformKeys.importCertificate 匯入憑證
以下範例除了顯示建構及傳送認證要求之外,還會顯示主要的 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
要產生的金鑰類型。
列舉
"RSA"
「ECDSA」
ChallengeKeyOptions
屬性
-
挑戰
ArrayBuffer
由 Verified Access Web API 發出的挑戰。
-
registerKey
如果有的話,請使用指定的
scope
權杖,將挑戰金鑰註冊。接著,您可以將金鑰與憑證建立關聯,並像其他簽署金鑰一樣使用。後續呼叫這個函式時,系統會在指定的scope
中產生新的 Enterprise 金鑰。 -
範圍
要驗證哪個 Enterprise 金鑰。
RegisterKeyOptions
屬性
-
演算法
註冊金鑰應使用的演算法。
Scope
是否使用 Enterprise 使用者金鑰或 Enterprise 機器金鑰。
列舉
"USER"
"MACHINE"
Token
屬性
-
id
字串
這個
Token
的專屬 ID。靜態 ID 有
"user"
和"system"
,分別是指平台的使用者專屬和全系統硬體權杖。enterprise.platformKeys.getTokens
可能會傳回任何其他符記 (含其他 ID)。 -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 以上版本實作 WebCrypto 的 SubtleCrypto 介面。加密編譯作業 (包括產生金鑰) 是由軟體提供支援。金鑰的保護機制,以及不可擷取屬性的實作方式,都是在軟體中完成,因此金鑰的保護機制不如硬體支援金鑰。
您只能產生無法擷取的 RSASSA-PKCS1-V1_5 金鑰,且
modulusLength
最多只能為 2048。每個金鑰最多只能用於簽署資料一次。在特定
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()
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
中定義欄位的物件。 -
回呼
函式 選填
callback
參數如下所示:(response: ArrayBuffer) => void
-
回應
ArrayBuffer
挑戰回應。
-
傳回
-
Promise<ArrayBuffer>
待處理承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback?: function,
)
請改用 challengeKey
。
挑戰硬體支援 Enterprise 機器金鑰,並將回應發送為遠端認證通訊協定的一部分。這項 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>
待處理承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。
challengeUserKey()
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"
權杖註冊,並放棄企業使用者金鑰角色。接著,這組金鑰就能與憑證建立關聯,使用方式與其他簽署金鑰相同。這組金鑰為 2048 位元 RSA 金鑰。之後呼叫這個函式時,系統會產生新的 Enterprise 使用者金鑰。 -
回呼
函式 選填
callback
參數如下所示:(response: ArrayBuffer) => void
-
回應
ArrayBuffer
挑戰回應。
-
傳回
-
Promise<ArrayBuffer>
待處理Promise 僅適用於 Manifest V3 及以上版本,其他平台需要使用回呼。
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
callback?: function,
)
傳回可透過指定權杖取得的所有用戶端憑證清單。可用於檢查可用於特定驗證的用戶端憑證是否存在及到期日。
參數
-
tokenId
字串
getTokens
傳回的權杖 ID。 -
回呼
函式 選填
callback
參數如下所示:(certificates: ArrayBuffer[]) => void
-
certificates
ArrayBuffer[]
憑證清單,每個憑證均採用 X.509 憑證的 DER 編碼。
-
傳回
-
Promise<ArrayBuffer[]>
待處理承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。
getTokens()
chrome.enterprise.platformKeys.getTokens(
callback?: function,
)
傳回可用的符記。在一般使用者的工作階段中,清單一律會包含具有 id
"user"
的使用者權杖。如果有系統通用的 TPM 權杖,傳回的清單也會包含具有 id
"system"
的全系統權杖。系統層級權杖會與此裝置 (例如 Chromebook) 的所有工作階段相同。
傳回
-
Promise<Token[]>
待處理承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。
importCertificate()
chrome.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
如果已將認證金鑰儲存在這個權杖中,就會將 certificate
匯入至指定的權杖。認證要求成功後,應使用這項功能儲存取得的憑證,並讓作業系統和瀏覽器可用於驗證。
參數
-
tokenId
字串
getTokens
傳回的權杖 ID。 -
認證
ArrayBuffer
X.509 憑證的 DER 編碼。
-
回呼
函式 選填
callback
參數如下所示:() => void
傳回
-
Promise<void>
待處理承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
從指定的符記中移除 certificate
(如果有的話)。應用於移除過時的憑證,以免系統在驗證期間考慮這些憑證,也不會讓憑證選擇過於雜亂。應用於憑證存放區中的可用儲存空間。
參數
-
tokenId
字串
getTokens
傳回的權杖 ID。 -
認證
ArrayBuffer
X.509 憑證的 DER 編碼。
-
回呼
函式 選填
callback
參數如下所示:() => void
傳回
-
Promise<void>
待處理承諾僅支援資訊清單 V3 以上版本,其他平台則需要使用回呼。