說明
使用 chrome.enterprise.platformKeys
API 產生金鑰,並為這些金鑰安裝憑證。憑證會由平台管理,可用於 TLS 驗證、網路存取,或透過 chrome.platformKeys 由其他擴充功能使用。
權限
enterprise.platformKeys
可用性
概念和用法
使用這個 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
要產生的金鑰類型。
列舉
"RSA"
"ECDSA"
ChallengeKeyOptions
屬性
-
挑戰
ArrayBuffer
由 Verified Access Web API 發出的挑戰。
-
registerKey
如果有指定,則會將挑戰金鑰註冊至指定的
scope
權杖。接著,您可以將金鑰與憑證建立關聯,並像其他簽署金鑰一樣使用。後續對這個函式的呼叫會在指定的scope
中產生新的企業金鑰。 -
範圍
要驗證哪個 Enterprise 金鑰。
RegisterKeyOptions
屬性
-
演算法
註冊金鑰應使用的演算法。
Scope
是否使用 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()
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()
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()
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()
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()
chrome.enterprise.platformKeys.getTokens(
callback?: function,
)
傳回可用的符記。在一般使用者的工作階段中,清單一律會包含使用者的權杖,並附上 id
"user"
。如果系統層級的 TPM 權杖可用,則傳回的清單也會包含系統層級權杖,並附上 id
"system"
。系統層級權杖會與此裝置 (例如 Chromebook) 的所有工作階段相同。
傳回
-
Promise<Token[]>
Chrome 131 以上版本承諾在資訊清單 3 以上版本中受支援,但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。
importCertificate()
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()
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 以上版本中受支援,但回呼則是為了回溯相容性而提供。您無法在同一個函式呼叫中同時使用這兩種方法。承諾會以傳遞至回呼的相同類型解析。