說明
請使用 chrome.enterprise.platformKeys
API 產生金鑰並安裝這些金鑰的憑證。憑證會由平台管理,並可用於 TLS 驗證、網路存取,或透過 chrome.platformKeys 用於其他擴充功能。
權限
enterprise.platformKeys
可用性
用量
使用此 API 註冊用戶端憑證的一般使用步驟如下:
使用 enterprise.platformKeys.getTokens 取得所有可用的權杖。
找出
id
等於"user"
的符記。之後請使用這個權杖。使用
generateKey
權杖方法 (在 SubtleCrypto 中定義) 產生金鑰組。這會將控制代碼傳回到鍵。使用
exportKey
Token 方法 (在 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
要產生的金鑰類型。
列舉
「零售業務員」
「ECDSA」
ChallengeKeyOptions
屬性
-
挑戰
ArrayBuffer
Verified Access Web API 產生的驗證問題。
-
registerKey
如有,請使用指定
scope
的權杖註冊驗證的金鑰。接著,這組金鑰就能與憑證建立關聯,使用方式與其他簽署金鑰相同。後續呼叫這個函式時,系統會在指定的scope
中產生新的 Enterprise 金鑰。 -
範圍
要挑戰哪一個 Enterprise 金鑰。
RegisterKeyOptions
屬性
-
演算法
已註冊金鑰應使用的演算法。
Scope
要使用 Enterprise 使用者金鑰還是企業機器金鑰。
列舉
「USER」
「MACHINE」
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 且採用namedCurve
P-256 的不可擷取 RSASSA-PKCS1-V1_5 金鑰,以及採用namedCurve
P-256 的 ECDSA。每個金鑰最多只能用於簽署資料。在特定
Token
上產生的金鑰無法與其他權杖一起使用,也不能與window.crypto.subtle
搭配使用。同樣地,透過window.crypto.subtle
建立的Key
物件無法透過這個介面使用。
方法
challengeKey()
chrome.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
callback: function,
)
與 challengeMachineKey
和 challengeUserKey
類似,但允許指定已註冊金鑰的演算法。挑戰硬體支援 Enterprise 機器金鑰,並將回應發送為遠端認證通訊協定的一部分。這項功能僅適用於 Chrome 作業系統,而且搭配 Verified Access Web API 使用時,會一併出現問題及驗證回應。
Verified Access Web API 驗證成功後,就表示目前裝置是合法的 Chrome OS 裝置,目前的裝置是由驗證期間指定的網域進行管理、目前登入的使用者是由驗證時指定的網域管理,而目前裝置狀態符合企業裝置政策。例如,政策可能會指定裝置不得進入開發人員模式。因為驗證產生的裝置身分都會緊密繫結至目前裝置的硬體。如果指定 "user"
範圍,該身分也會盡可能綁定目前登入的使用者。
如果目前的裝置未受管理、目前的使用者未受到管理,或是尚未根據企業裝置政策明確啟用呼叫端,這項功能就受到高度限制,因此函式將會失敗。驗證過的金鑰不在 "system"
或 "user"
權杖中,任何其他 API 皆無法存取。
參數
-
包含
ChallengeKeyOptions
中定義的欄位的物件。 -
回呼
函式
callback
參數如下所示:(response: ArrayBuffer) => void
-
回應
ArrayBuffer
挑戰回應。
-
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback: function,
)
請改用 challengeKey
。
挑戰硬體支援 Enterprise 機器金鑰,並將回應發送為遠端認證通訊協定的一部分。這項功能僅適用於 Chrome 作業系統,而且搭配 Verified Access Web API 使用時,會一併出現問題及驗證回應。Verified Access Web API 成功驗證後,通常代表確認下列事項:* 目前使用的裝置是合法的 Chrome OS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。* 目前裝置狀態符合企業裝置政策。例如,政策可能會指定裝置不得進入開發人員模式。* 驗證程序產生的裝置身分都會緊密地與目前裝置的硬體綁定。如果目前的裝置未受管理、目前的使用者未受到管理,或是尚未根據企業裝置政策明確啟用呼叫端,這項功能會受到高度限制,因此函式將會失敗。企業機器金鑰不會存放在 "system"
權杖中,其他任何 API 皆無法存取。
參數
-
挑戰
ArrayBuffer
Verified Access Web API 產生的驗證問題。
-
registerKey
布林值 選填
Chrome 59 以上版本如果設定,目前的 Enterprise 機器金鑰會以
"system"
權杖註冊,並放棄 Enterprise 機器金鑰角色。接著,這組金鑰就能與憑證建立關聯,使用方式與其他簽署金鑰相同。這組金鑰為 2048 位元 RSA。後續呼叫這個函式時,系統會產生新的 Enterprise 機器金鑰。 -
回呼
函式
callback
參數如下所示:(response: ArrayBuffer) => void
-
回應
ArrayBuffer
挑戰回應。
-
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback: function,
)
請改用 challengeKey
。
驗證硬體支援的 Enterprise 使用者金鑰,並在遠端認證通訊協定中發出回應。這項功能僅適用於 Chrome 作業系統,而且搭配 Verified Access Web API 使用時,會一併出現問題及驗證回應。Verified Access Web API 成功驗證後,通常代表確認下列事項:* 目前使用的裝置是合法的 Chrome OS 裝置。* 目前的裝置是由驗證期間指定的網域管理。* 目前登入的使用者是由驗證期間指定的網域管理。* 目前裝置狀態符合企業使用者政策。例如,政策可能會指定裝置不得進入開發人員模式。* 驗證產生的公開金鑰與目前裝置的硬體和目前登入使用者的公開金鑰緊密繫結。如果目前的裝置未受管理、目前的使用者未受到管理,或是尚未根據企業使用者政策明確啟用呼叫端,這項功能就受到高度限制,因此函式將會失敗。無法將 Enterprise 使用者金鑰存放在 "user"
權杖中,其他任何 API 皆無法存取。
參數
-
挑戰
ArrayBuffer
Verified Access Web API 產生的驗證問題。
-
registerKey
布林值
設定後,系統會使用
"user"
權杖註冊目前的 Enterprise 使用者金鑰,並退出 Enterprise 使用者金鑰角色。接著,這組金鑰就能與憑證建立關聯,使用方式與其他簽署金鑰相同。這組金鑰為 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[]
憑證清單,每個憑證都以 DER 編碼為 X.509 憑證。
-
getTokens()
chrome.enterprise.platformKeys.getTokens(
callback: function,
)
傳回可用的權杖。在一般使用者的工作階段中,清單一律會包含具有 id
"user"
的使用者權杖。如果有系統通用的 TPM 權杖,傳回的清單也會包含具有 id
"system"
的全系統權杖。這部裝置上所有工作階段 (例如 Chromebook 等裝置) 的系統全系統符記均相同。
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