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 com chrome.platformKeys.
Permissões
enterprise.platformKeys
Disponibilidade
Conceitos e uso
Veja a seguir as etapas do uso típico dessa API para registrar um certificado do cliente:
Consiga 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 no SubtleCrypto). Isso 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 no SubtleCrypto).Preencha a solicitação de certificação e envie-a à autoridade certificadora.
Se um certificado for recebido, importe-o usando [
enterprise.platformKeys.importCertificate()
`[3]
Este é 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.
Tipo enumerado
"RSA"
"ECDSA"
ChallengeKeyOptions
Propriedades
-
desafiar
ArrayBuffer
Um desafio emitido pela API Verified Access Web.
-
registerKey
RegisterKeyOptions opcional
Se presente, registra a chave desafiada com o token do
scope
especificado. A chave pode ser associada a um certificado e usada como qualquer outra chave de assinatura. As chamadas subsequentes para essa função gerarão uma nova chave corporativa noscope
especificado. -
escopo
Qual chave corporativa enfrentar.
RegisterKeyOptions
Propriedades
-
algoritmo
Qual algoritmo a chave registrada deve usar.
Scope
Se você quer usar a chave de usuário corporativo ou a chave de máquina corporativa.
Tipo enumerado
Token
Propriedades
-
id
string
Identifica exclusivamente este
Token
.Os IDs estáticos são
"user"
e"system"
, referentes ao token de hardware específico do usuário da plataforma e do sistema, respectivamente. Outros tokens (com outros identificadores) podem ser retornados porenterprise.platformKeys.getTokens
. -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 ou mais recenteImplementa a interface SubtleCrypto do WebCrypto. As operações criptográficas, incluindo a geração de chaves, têm o suporte de software. A proteção das chaves e, portanto, a implementação da propriedade não extraível, é feita no software. Portanto, as chaves são menos protegidas do que as chaves protegidas por hardware.
Apenas chaves RSASSA-PKCS1-V1_5 não extraíveis com
modulusLength
até 2048 podem ser geradas. Cada chave pode ser usada para assinar dados no máximo uma vez.As chaves geradas em um
Token
específico não podem ser usadas com outros tokens nem comwindow.crypto.subtle
. Da mesma forma, 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, têm suporte de hardware.
Somente chaves RSASSA-PKCS1-V1_5 não extraíveis com
modulusLength
até 2048 e ECDSA comnamedCurve
P-256 podem ser geradas. Cada chave pode ser usada para assinar dados no máximo uma vez.As chaves geradas em um
Token
específico não podem ser usadas com outros tokens nem comwindow.crypto.subtle
. Da mesma forma, 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 corporativa protegida por hardware e emite a resposta como parte de um protocolo de atestado remoto. Útil apenas no Chrome OS e em conjunto com a API Verified Access Web, que gera desafios e verifica respostas.
A verificação feita pela API Verified Access Web é um forte indicador de que o dispositivo atual é um dispositivo Chrome OS 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 obedece à política do 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á fortemente vinculada ao hardware do dispositivo atual. Se o escopo "user"
for especificado, a identidade também será fortemente vinculada ao usuário atual 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 a operação não tiver sido ativada explicitamente para o autor da chamada pela política do dispositivo empresarial. A chave em risco não reside no token "system"
ou "user"
e não pode ser acessada por nenhuma outra API.
Parâmetros
-
opções
Objeto contendo os campos definidos em
ChallengeKeyOptions
. -
callback
função
O parâmetro
callback
tem esta aparência:(response: ArrayBuffer)=>void
-
resposta
ArrayBuffer
A resposta do desafio.
-
challengeMachineKey()
chrome.enterprise.platformKeys.challengeMachineKey(
challenge: ArrayBuffer,
registerKey?: boolean,
callback: function,
)
Use challengeKey
.
Desafia uma chave de máquina corporativa protegida por hardware e emite a resposta como parte de um protocolo de atestado remoto. Útil apenas no Chrome OS e em conjunto com a API Verified Access Web, que gera desafios e verifica respostas. A verificação feita pela API Verified Access Web é um forte indicador de que: * O dispositivo atual é um dispositivo ChromeOS legítimo. * O dispositivo atual é gerenciado pelo domínio especificado durante a verificação. * O usuário que fez login é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo obedece à política do 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á fortemente 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 a operação não tiver sido ativada explicitamente para o autor da chamada pela política do dispositivo empresarial. A chave de máquina corporativa não fica no token "system"
e não pode ser acessada por nenhuma outra API.
Parâmetros
-
desafiar
ArrayBuffer
Um desafio emitido pela API Verified Access Web.
-
registerKey
booleano opcional
Chrome 59 ou mais recenteSe definido, a chave de máquina empresarial atual será registrada com o token
"system"
e renuncia ao papel de chave de máquina 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 para essa função vão gerar uma nova chave de máquina corporativa. -
callback
função
O parâmetro
callback
tem esta aparência:(response: ArrayBuffer)=>void
-
resposta
ArrayBuffer
A resposta do desafio.
-
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback: function,
)
Use challengeKey
.
Desafia uma chave de usuário corporativa protegida por hardware e emite a resposta como parte de um protocolo de atestado remoto. Útil apenas no Chrome OS e em conjunto com a API Verified Access Web, que gera desafios e verifica respostas. A verificação feita pela API Verified Access Web é um forte indicador de que: * O dispositivo atual é um dispositivo ChromeOS legítimo. * O dispositivo atual é gerenciado pelo domínio especificado durante a verificação. * O usuário que fez login é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo obedece à política do usuário empresarial. 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á fortemente vinculada ao hardware do dispositivo atual e ao usuário conectado no momento. 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 a operação não tiver sido ativada explicitamente para o autor da chamada pela política do usuário empresarial. A chave de usuário corporativo não fica no token "user"
e não pode ser acessada por nenhuma outra API.
Parâmetros
-
desafiar
ArrayBuffer
Um desafio emitido pela API Verified Access Web.
-
registerKey
boolean
Se definida, a chave de usuário empresarial atual será registrada com o token
"user"
e renuncia ao papel de chave de usuário corporativo. 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 para essa função gerarão uma nova chave de usuário corporativo. -
callback
função
O parâmetro
callback
tem esta aparência:(response: ArrayBuffer)=>void
-
resposta
ArrayBuffer
A resposta do desafio.
-
getCertificates()
chrome.enterprise.platformKeys.getCertificates(
tokenId: string,
callback: function,
)
Retorna a lista de todos os certificados do cliente disponíveis do token fornecido. Pode ser usado para verificar a existência e a expiração de certificados do 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
O parâmetro
callback
tem esta aparência:(certificates: ArrayBuffer[])=>void
-
certificates
ArrayBuffer[]
A lista de certificados, cada um na codificação DER de um certificado X.509.
-
getTokens()
chrome.enterprise.platformKeys.getTokens(
callback: function,
)
Retorna os tokens disponíveis. Na sessão de um usuário normal, a lista sempre conterá o token do usuário com id
"user"
. Se um token TPM do sistema estiver disponível, a lista retornada também conterá o token do sistema com id
"system"
. O token de todo o sistema será o mesmo para todas as sessões neste dispositivo (no sentido de um Chromebook, por exemplo).
Parâmetros
importCertificate()
chrome.enterprise.platformKeys.importCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
Importa certificate
para o token fornecido se a chave certificada já estiver armazenada nesse token. Após uma solicitação de certificação bem-sucedida, essa função deve ser usada para armazenar o certificado obtido 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 optional
O parâmetro
callback
tem esta aparência:()=>void
removeCertificate()
chrome.enterprise.platformKeys.removeCertificate(
tokenId: string,
certificate: ArrayBuffer,
callback?: function,
)
Remove certificate
do token fornecido, se houver. Use 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 espaço 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 optional
O parâmetro
callback
tem esta aparência:()=>void