说明
使用 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
中生成新的企业密钥。 -
范围
要对哪个企业密钥进行质询。
RegisterKeyOptions
属性
-
算法
已注册的密钥应使用哪种算法。
Scope
是使用企业用户密钥还是企业机器密钥。
枚举
“USER”
"MACHINE"
Token
属性
-
id
字符串
此
Token
的唯一标识。静态 ID 分别为
"user"
和"system"
,分别指平台的用户专用令牌和系统级硬件令牌。enterprise.platformKeys.getTokens
可能会返回任何其他令牌(带有其他标识符)。 -
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.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
callback?: function,
)
与 challengeMachineKey
和 challengeUserKey
类似,但允许指定已注册密钥的算法。质询由硬件支持的企业机器密钥,并作为远程认证协议的一部分发出响应。仅在 ChromeOS 上有效,并且需要与 Verified Access Web API 搭配使用,该 API 既会发出质询,也会验证响应。
如果 Verified Access Web API 成功完成验证,则表明当前设备是合法的 ChromeOS 设备,当前设备由验证期间指定的网域管理,当前登录的用户由验证期间指定的网域管理,并且当前设备状态符合企业设备政策。例如,政策可能会指定设备不得处于开发者模式。验证发出的任何设备身份都与当前设备的硬件紧密绑定。如果指定了 "user"
范围,则身份也会与当前登录的用户紧密绑定。
此函数受到严格限制,如果当前设备不是受管理设备、当前用户不是受管理用户,或者企业设备政策未为调用方明确启用此操作,则会失败。被质疑的密钥不位于 "system"
或 "user"
令牌中,任何其他 API 都无法访问该密钥。
参数
-
包含
ChallengeKeyOptions
中定义的字段的对象。 -
callback
函数(可选)
callback
参数如下所示:(response: ArrayBuffer) => void
-
Response
ArrayBuffer
质询响应。
-
返回
-
Promise<ArrayBuffer>
Chrome 131 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback?: function,
)
请改用 challengeKey
。
对由硬件支持的企业机器密钥发出质询,并在远程认证协议中发出响应。仅在 ChromeOS 上有效,并且需要与 Verified Access Web API 搭配使用,该 API 既会发出质询,也会验证响应。通过 Verified Access Web API 成功完成验证,表明当前设备是合法的 ChromeOS 设备。* 当前设备由验证期间指定的网域管理。* 当前登录的用户由验证期间指定的网域管理。* 当前设备状态符合企业设备政策。例如,政策可以指定设备不得处于开发者模式。* 验证发出的任何设备身份都与当前设备的硬件紧密绑定。此函数受到严格限制,如果当前设备未受管理、当前用户未受管理,或企业设备政策尚未明确允许调用方执行此操作,此函数就会失败。企业机器密钥不位于 "system"
令牌中,任何其他 API 都无法访问。
参数
-
挑战
ArrayBuffer
Verified Access Web API 发出的质询。
-
registerKey
布尔值(可选)
Chrome 59 及更高版本如果设置此字段,系统会使用
"system"
令牌注册当前的企业机器密钥,并放弃企业机器密钥角色。然后,该密钥便可与证书相关联,并像任何其他签名密钥一样使用。此密钥为 2048 位 RSA 密钥。然后,对此函数的后续调用将生成新的企业机器密钥。 -
callback
函数(可选)
callback
参数的格式为:(response: ArrayBuffer) => void
-
Response
ArrayBuffer
质询响应。
-
返回
-
Promise<ArrayBuffer>
Chrome 131 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback?: function,
)
请改用 challengeKey
。
质询由硬件支持的企业用户密钥,并作为远程认证协议的一部分发出响应。仅在 ChromeOS 上有效,并且需要与 Verified Access Web API 搭配使用,该 API 既会发出质询,也会验证响应。通过 Verified Access Web API 成功完成验证,表明当前设备是合法的 ChromeOS 设备。* 当前设备由验证期间指定的网域管理。* 当前登录的用户由验证期间指定的域管理。* 当前设备状态符合企业用户规范。例如,政策可以指定设备不得处于开发者模式。* 验证发出的公钥与当前设备的硬件以及当前已登录的用户紧密相关联。此函数受到严格限制,如果当前设备不是受管理设备、当前用户不是受管理用户,或者企业用户政策未明确为调用方启用此操作,则该操作将会失败。企业用户密钥不位于 "user"
令牌中,任何其他 API 都无法访问。
参数
-
挑战
ArrayBuffer
Verified Access Web API 发出的质询。
-
registerKey
布尔值
如果设置,系统会使用
"user"
令牌注册当前企业用户密钥,并放弃企业用户密钥角色。然后,该密钥便可与证书相关联,并像任何其他签名密钥一样使用。此密钥是 2048 位 RSA。然后,对此函数的后续调用将生成新的企业用户密钥。 -
callback
函数(可选)
callback
参数如下所示:(response: ArrayBuffer) => void
-
Response
ArrayBuffer
质询响应。
-
返回
-
Promise<ArrayBuffer>
Chrome 131 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
callback?: function,
)
返回给定令牌提供的所有客户端证书的列表。可用于检查可用于特定身份验证的客户端证书是否存在以及是否过期。
参数
-
tokenId
字符串
getTokens
返回的令牌的 ID。 -
callback
函数(可选)
callback
参数如下所示:(certificates: ArrayBuffer[]) => void
-
certificates
ArrayBuffer[]
证书列表,每个证书均采用 X.509 证书的 DER 编码。
-
返回
-
Promise<ArrayBuffer[]>
Chrome 131 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
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
函数(可选)
callback
参数的格式为:() => void
返回
-
Promise<void>
Chrome 131 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
从给定令牌中移除 certificate
(如果存在)。应用于移除已废弃的证书,以免在身份验证期间不考虑这些证书,也不会使证书选择过于繁杂。应用于释放证书存储区中的存储空间。
参数
-
tokenId
字符串
getTokens
返回的令牌的 ID。 -
证书
ArrayBuffer
X.509 证书的 DER 编码。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 131 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。