Descrição
Use a API chrome.enterprise.platformKeys
para gerar chaves e instalar certificados para elas. Os certificados serão gerenciados pela plataforma e poderão ser usados para autenticação TLS, acesso à rede ou por outra extensão usando chrome.platformKeys.
Permissões
enterprise.platformKeys
Disponibilidade
Uso
O uso típico dessa API para registrar um certificado de cliente segue estas etapas:
Receba todos os tokens disponíveis usando enterprise.platformKeys.getTokens.
Encontre o token com
id
igual a"user"
. Use esse token posteriormente.Gere um par de chaves usando o método de token
generateKey
(definido em SubtleCrypto). Isso vai retornar o identificador para a chave.Exporte a chave pública usando o método de token
exportKey
(definido no SubtleCrypto).Crie a assinatura dos dados da solicitação de certificação usando o método de token
sign
(definido em SubtleCrypto).Preencha o pedido de certificação e envie para a autoridade certificadora.
Se um certificado for recebido, importe-o usando enterprise.platformKeys.importCertificate.
Confira um exemplo que mostra a principal interação da API, exceto a criação e o envio da solicitação de certificação:
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);
Tipos
Algorithm
Tipo de chave a ser gerada.
Enumeração
"RSA"
"ECDSA"
ChallengeKeyOptions
Propriedades
-
desafio
ArrayBuffer
Um desafio emitido pela API Web Verified Access.
-
registerKey
RegisterKeyOptions opcional
Se presente, registra a chave desafiada com o token especificado da
scope
. A chave pode ser associada a um certificado e usada como qualquer outra chave de assinatura. As chamadas subsequentes a essa função vão gerar uma nova chave Enterprise noscope
especificado. -
escopo
Qual chave empresarial será contestada.
RegisterKeyOptions
Propriedades
-
algoritmo
Qual algoritmo a chave registrada deve usar.
Scope
Se a chave de usuário ou de máquina corporativa será usada.
Enumeração
"USER"
"MACHINE"
Token
Propriedades
-
id
string
Identifica exclusivamente essa
Token
.Os IDs estáticos são
"user"
e"system"
, que se referem ao token de hardware específico do usuário e do sistema, respectivamente. Qualquer outro token (com outros identificadores) pode ser retornado porenterprise.platformKeys.getTokens
. -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 e versões mais recentesImplementa a interface SubtleCrypto do WebCrypto. As operações criptográficas, incluindo a geração de chaves, são apoiadas por software. A proteção das chaves e, portanto, a implementação da propriedade não extraível, é feita no software, então as chaves são menos protegidas do que as chaves protegidas por hardware.
Só é possível gerar chaves não extraíveis. Os tipos de chave aceitos são RSASSA-PKCS1-V1_5 e RSA-OAEP com
modulusLength
de até 2.048. Cada chave RSASSA-PKCS1-V1_5 pode ser usada para assinar dados no máximo uma vez, a menos que a extensão esteja na lista de permissões da política KeyPermissions, caso em que a chave pode ser usada indefinidamente. As chaves RSA-OAEP podem ser usadas por extensões na lista de permissões da mesma política para desempacotar outras chaves.As chaves geradas em um
Token
específico não podem ser usadas com outros tokens nem comwindow.crypto.subtle
. Da mesma forma, os objetosKey
criados comwindow.crypto.subtle
não podem ser usados com essa interface. -
subtleCrypto
SubtleCrypto
Implementa a interface SubtleCrypto do WebCrypto. As operações criptográficas, incluindo a geração de chaves, são compatíveis com hardware.
Só é possível gerar chaves não extraíveis. Os tipos de chave aceitos são RSASSA-PKCS1-V1_5 e RSA-OAEP com
modulusLength
de até 2048 e ECDSA comnamedCurve
P-256. Cada chave RSASSA-PKCS1-V1_5 e ECDSA pode ser usada para assinar dados no máximo uma vez, a menos que a extensão esteja na lista de permissões da política KeyPermissions. Nesse caso, a chave pode ser usada indefinidamente. As chaves RSA-OAEP podem ser usadas por extensões na lista de permissões da mesma política para desempacotar outras chaves.As chaves geradas em um
Token
específico não podem ser usadas com outros tokens nem comwindow.crypto.subtle
. Da mesma forma, os objetosKey
criados comwindow.crypto.subtle
não podem ser usados com essa interface.
Métodos
challengeKey()
chrome.enterprise.platformKeys.challengeKey(
options: ChallengeKeyOptions,
callback?: function,
)
Semelhante a challengeMachineKey
e challengeUserKey
, mas permite especificar o algoritmo de uma chave registrada. Desafia uma chave de máquina empresarial protegida por hardware e emite a resposta como parte de um protocolo de atestado remoto. Útil apenas no ChromeOS e em conjunto com a API Web Verified Access, que emite desafios e verifica respostas.
Uma verificação bem-sucedida pela API Web Verified Access é um indicador forte de que o dispositivo atual é um dispositivo ChromeOS legítimo, que ele é gerenciado pelo domínio especificado durante a verificação, que o usuário conectado é gerenciado pelo domínio especificado durante a verificação e que o estado atual do dispositivo está em conformidade com a política de dispositivos corporativos. Por exemplo, uma política pode especificar que o dispositivo não pode estar no modo de desenvolvedor. Qualquer identidade de dispositivo emitida pela verificação está intimamente vinculada ao hardware do dispositivo atual. Se o escopo "user"
for especificado, a identidade também estará vinculada ao usuário conectado.
Essa função é altamente restrita e vai falhar se o dispositivo atual não for gerenciado, o usuário atual não for gerenciado ou se essa operação não tiver sido ativada explicitamente para o autor da chamada pela política de dispositivo corporativo. A chave desafiada não está no token "system"
ou "user"
e não é acessível por nenhuma outra API.
Parâmetros
-
opções
Objeto que contém os campos definidos em
ChallengeKeyOptions
. -
callback
função opcional
O parâmetro
callback
tem este formato:(response: ArrayBuffer) => void
-
resposta
ArrayBuffer
A resposta ao desafio.
-
Retorna
-
Promise<ArrayBuffer>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback?: function,
)
Use challengeKey
.
Desafia uma chave de máquina empresarial protegida por hardware e emite a resposta como parte de um protocolo de atestado remoto. Útil apenas no ChromeOS e em conjunto com a API Web Verified Access, que emite desafios e verifica respostas. Uma verificação bem-sucedida pela API Web de acesso verificado é um indicador forte de todos os seguintes: * O dispositivo atual é um dispositivo ChromeOS legítimo. * O dispositivo atual é gerenciado pelo domínio especificado durante a verificação. * O usuário conectado atual é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo está em conformidade com a política de dispositivo da empresa. Por exemplo, uma política pode especificar que o dispositivo não pode estar no modo de desenvolvedor. * Qualquer identidade de dispositivo emitida pela verificação está vinculada ao hardware do dispositivo atual. Essa função é altamente restrita e vai falhar se o dispositivo atual não for gerenciado, o usuário atual não for gerenciado ou se essa operação não tiver sido ativada explicitamente para o autor da chamada pela política de dispositivo corporativo. A chave de máquina Enterprise não está no token "system"
e não é acessível por nenhuma outra API.
Parâmetros
-
desafio
ArrayBuffer
Um desafio emitido pela API Web Verified Access.
-
registerKey
booleano opcional
Chrome 59 e versões mais recentesSe definido, a chave de máquina Enterprise atual é registrada com o token
"system"
e renuncia à função de chave de máquina Enterprise. A chave pode ser associada a um certificado e usada como qualquer outra chave de assinatura. Essa chave é RSA de 2048 bits. As chamadas subsequentes a essa função vão gerar uma nova chave de máquina empresarial. -
callback
função opcional
O parâmetro
callback
tem este formato:(response: ArrayBuffer) => void
-
resposta
ArrayBuffer
A resposta ao desafio.
-
Retorna
-
Promise<ArrayBuffer>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback?: function,
)
Use challengeKey
.
Desafia uma chave de usuário Enterprise com suporte de hardware e emite a resposta como parte de um protocolo de atestado remoto. Útil apenas no ChromeOS e em conjunto com a API Web Verified Access, que emite desafios e verifica respostas. Uma verificação bem-sucedida pela API Web de acesso verificado é um indicador forte de todos os seguintes: * O dispositivo atual é um dispositivo ChromeOS legítimo. * O dispositivo atual é gerenciado pelo domínio especificado durante a verificação. * O usuário conectado atual é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo está em conformidade com a política do usuário corporativo. Por exemplo, uma política pode especificar que o dispositivo não pode estar no modo de desenvolvedor. * A chave pública emitida pela verificação está vinculada ao hardware do dispositivo atual e ao usuário conectado. Essa função é altamente restrita e vai falhar se o dispositivo atual não for gerenciado, o usuário atual não for gerenciado ou se essa operação não tiver sido ativada explicitamente para o autor da chamada pela política de usuário empresarial. A chave de usuário empresarial não está no token "user"
e não pode ser acessada por nenhuma outra API.
Parâmetros
-
desafio
ArrayBuffer
Um desafio emitido pela API Web Verified Access.
-
registerKey
booleano
Se definido, a chave de usuário empresarial atual é registrada com o token
"user"
e renuncia ao papel de chave de usuário empresarial. A chave pode ser associada a um certificado e usada como qualquer outra chave de assinatura. Essa chave é RSA de 2048 bits. As chamadas subsequentes a essa função vão gerar uma nova chave de usuário empresarial. -
callback
função opcional
O parâmetro
callback
tem este formato:(response: ArrayBuffer) => void
-
resposta
ArrayBuffer
A resposta ao desafio.
-
Retorna
-
Promise<ArrayBuffer>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
callback?: function,
)
Retorna a lista de todos os certificados do cliente disponíveis no token fornecido. Pode ser usado para verificar a existência e a expiração de certificados de cliente que podem ser usados para uma determinada autenticação.
Parâmetros
-
tokenId
string
O ID de um token retornado por
getTokens
. -
callback
função opcional
O parâmetro
callback
tem este formato:(certificates: ArrayBuffer[]) => void
-
certificados
ArrayBuffer[]
A lista de certificados, cada um na codificação DER de um certificado X.509.
-
Retorna
-
Promise<ArrayBuffer[]>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
getTokens()
chrome.enterprise.platformKeys.getTokens(
callback?: function,
)
Retorna os tokens disponíveis. Em uma sessão de usuário regular, a lista sempre vai conter o token do usuário com id
"user"
. Se um token do TPM do sistema estiver disponível, a lista retornada também conterá o token do sistema com id
"system"
. O token do sistema será o mesmo para todas as sessões neste dispositivo (dispositivo no sentido de, por exemplo, um Chromebook).
Parâmetros
Retorna
-
Promise<Token[]>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
importCertificate()
chrome.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
Importa certificate
para o token especificado se a chave certificada já estiver armazenada nele. Depois de uma solicitação de certificação bem-sucedida, essa função precisa ser usada para armazenar o certificado recebido e disponibilizá-lo ao sistema operacional e ao navegador para autenticação.
Parâmetros
-
tokenId
string
O ID de um token retornado por
getTokens
. -
certificado
ArrayBuffer
A codificação DER de um certificado X.509.
-
callback
função opcional
O parâmetro
callback
tem este formato:() => void
Retorna
-
Promise<void>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
Remove certificate
do token fornecido, se presente. Deve ser usado para remover certificados obsoletos para que eles não sejam considerados durante a autenticação e não atrapalhem a escolha do certificado. Deve ser usado para liberar armazenamento no repositório de certificados.
Parâmetros
-
tokenId
string
O ID de um token retornado por
getTokens
. -
certificado
ArrayBuffer
A codificação DER de um certificado X.509.
-
callback
função opcional
O parâmetro
callback
tem este formato:() => void
Retorna
-
Promise<void>
Chrome 131 e versões mais recentesAs promessas têm suporte apenas para o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.