chrome.enterprise.platformKeys

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

Somente no ChromeOS Requer política

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 da chave.

  • Exporte a chave pública usando o método de token exportKey (definido em SubtleCrypto).

  • Crie a assinatura dos dados da solicitação de certificação usando o método de token sign (definido em SubtleCrypto).

  • Preencha e envie a solicitação de certificação 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

Chrome 110 ou mais recente

Tipo de chave a ser gerada.

Enumeração

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 ou mais recente

Propriedades

  • desafio

    ArrayBuffer

    Um desafio emitido pela API da Web do Verified Access.

  • 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 vão gerar uma nova chave empresarial no scope especificado.

  • escopo

    Escopo

    Qual chave empresarial usar para o desafio.

RegisterKeyOptions

Chrome 110 ou mais recente

Propriedades

  • algoritmo

    Algorithm

    Qual algoritmo a chave registrada deve usar.

Scope

Chrome 110 ou mais recente

Se você vai usar a chave de usuário ou de máquina do Enterprise.

Enumeração

"USER"

"MACHINE"

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 por enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97+

    Implementa a interface SubtleCrypto da WebCrypto. As operações criptográficas, incluindo a geração de chaves, são baseadas em software. A proteção das chaves e, portanto, a implementação da propriedade não extraível são feitas em software. Por isso, 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 compatíveis são RSASSA-PKCS1-V1_5 e RSA-OAEP (em versões do Chrome 135 ou mais recentes) com modulusLength até 2048. 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 pela política KeyPermissions. Nesse caso, a chave pode ser usada indefinidamente. As chaves RSA-OAEP são compatíveis com o Chrome desde a versão 135 e podem ser usadas por extensões na lista de permissões pela mesma política para desencapsular outras chaves.

    As chaves geradas em um Token específico não podem ser usadas com outros tokens nem com window.crypto.subtle. Da mesma forma, objetos Key criados com window.crypto.subtle não podem ser usados com essa interface.

  • subtleCrypto

    SubtleCrypto

    Implementa a interface SubtleCrypto da WebCrypto. As operações criptográficas, incluindo a geração de chaves, são protegidas por hardware.

    Só é possível gerar chaves não extraíveis. Os tipos de chave compatíveis são RSASSA-PKCS1-V1_5 e RSA-OAEP (em versões do Chrome 135 ou mais recentes) com modulusLength até 2048 e ECDSA com namedCurve 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 pela política KeyPermissions. Nesse caso, a chave pode ser usada indefinidamente. As chaves RSA-OAEP são compatíveis com o Chrome desde a versão 135 e podem ser usadas por extensões na lista de permissões pela mesma política para desencapsular outras chaves.

    As chaves geradas em um Token específico não podem ser usadas com outros tokens nem com window.crypto.subtle. Da mesma forma, objetos Key criados com window.crypto.subtle não podem ser usados com essa interface.

Métodos

challengeKey()

Promise Chrome 110 ou mais recente 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
): Promise<ArrayBuffer>

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 comprovação remota. Ú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 forte sinal 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 atual é 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 é estritamente vinculada ao hardware do dispositivo atual. Se o escopo "user" for especificado, a identidade também será fortemente vinculada ao usuário conectado no momento.

Essa função é altamente restrita e vai falhar se o dispositivo ou o usuário atual não forem gerenciados ou se essa operação não tiver sido explicitamente ativada para o caller pela política de dispositivo corporativo. A chave contestada não está no token "system" ou "user" e não pode ser acessada por nenhuma outra API.

Parâmetros

  • Objeto que contém os campos definidos em ChallengeKeyOptions.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (response: ArrayBuffer) => void

    • resposta

      ArrayBuffer

      A resposta ao desafio.

Retorna

  • Promise<ArrayBuffer>

    Chrome 131 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

challengeMachineKey()

Promise Chrome 50 ou mais recente Suspenso desde o Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Use challengeKey.

Desafia uma chave de máquina empresarial protegida por hardware e emite a resposta como parte de um protocolo de comprovação remota. Ú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 forte sinal de tudo o que segue: * O dispositivo atual é um dispositivo ChromeOS legítimo. * O dispositivo atual é gerenciado pelo domínio especificado durante a verificação. * O usuário conectado no momento é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo está em compliance 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á fortemente vinculada ao hardware do dispositivo atual. Essa função é altamente restrita e vai falhar se o dispositivo ou o usuário atual não forem gerenciados ou se essa operação não tiver sido explicitamente ativada para o caller pela política de dispositivo corporativo. A chave de máquina empresarial não reside no token "system" e não pode ser acessada por nenhuma outra API.

Parâmetros

  • desafio

    ArrayBuffer

    Um desafio emitido pela API da Web do Verified Access.

  • registerKey

    booleano opcional

    Chrome 59 ou mais recente

    Se definido, a chave de máquina empresarial atual será registrada com o token "system" e vai renunciar à função 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 dessa função vão gerar uma nova chave de máquina empresarial.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (response: ArrayBuffer) => void

    • resposta

      ArrayBuffer

      A resposta ao desafio.

Retorna

  • Promise<ArrayBuffer>

    Chrome 131 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

challengeUserKey()

Promise Chrome 50 ou mais recente Suspenso desde o Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Use challengeKey.

Desafia uma chave de usuário empresarial protegida por hardware e emite a resposta como parte de um protocolo de comprovação remota. Ú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 forte sinal de tudo o que segue: * O dispositivo atual é um dispositivo ChromeOS legítimo. * O dispositivo atual é gerenciado pelo domínio especificado durante a verificação. * O usuário conectado no momento é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo está em conformidade com a política de usuários corporativos. 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. Essa função é altamente restrita e vai falhar se o dispositivo ou o usuário atual não forem gerenciados ou se a operação não tiver sido explicitamente ativada para o autor da chamada pela política de usuário corporativo. A chave de usuário do Enterprise não reside no token "user" e não pode ser acessada por nenhuma outra API.

Parâmetros

  • desafio

    ArrayBuffer

    Um desafio emitido pela API da Web do Verified Access.

  • registerKey

    booleano

    Se definido, a chave de usuário empresarial atual será registrada com o token "user" e vai renunciar à função 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 para essa função vão gerar uma nova chave de usuário empresarial.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (response: ArrayBuffer) => void

    • resposta

      ArrayBuffer

      A resposta ao desafio.

Retorna

  • Promise<ArrayBuffer>

    Chrome 131 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getCertificates()

Promise 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
): Promise<ArrayBuffer[]>

Retorna a lista de todos os certificados de cliente disponíveis no token especificado. 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 esta aparência: 

    (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 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

getTokens()

Promise 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

Retorna os tokens disponíveis. Em uma sessão de usuário comum, a lista sempre vai conter o token do usuário com id "user". Se um token do TPM em todo o sistema estiver disponível, a lista retornada também vai conter o token em todo o sistema com id "system". O token em todo o sistema será o mesmo para todas as sessões neste dispositivo (por exemplo, um Chromebook).

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (tokens: Token[]) => void

    • tokens

      Token[]

      A lista de tokens disponíveis.

Retorna

  • Promise<Token[]>

    Chrome 131 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

importCertificate()

Promise 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

Importa certificate para o token especificado se a chave certificada já estiver armazenada nele. 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 opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 131 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.

removeCertificate()

Promise 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
): Promise<void>

Remove certificate do token especificado, se ele estiver 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 esta aparência: 

    () => void

Retorna

  • Promise<void>

    Chrome 131 ou mais recente

    As promessas só são compatíveis com o Manifest V3 e versões mais recentes. Outras plataformas precisam usar callbacks.