chrome.enterprise.platformKeys

refresh date: 2026-09-25 robots: noindex

Importante: essa API funciona apenas no ChromeOS.

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

Observação: essa API é apenas para extensões pré-instaladas por uma política.

Uso

O uso típico dessa API para registrar um certificado do 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 a solicitação de certificação e envie-a à autoridade de certificação.

• Se um certificado for recebido, importe-o usando enterprise.platformKeys.importCertificate.

Veja 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+

Tipo de chave a ser gerada.

Enumeração

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110+

Propriedades

• desafio

  ArrayBuffer

  Um desafio emitido pela API Web de acesso verificado.

• 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 será desafiada.

RegisterKeyOptions

Chrome 110+

Propriedades

• algoritmo

  Algorithm

  Qual algoritmo a chave registrada deve usar.

Scope

Chrome 110+

Se você quer usar a chave de usuário corporativo ou a chave de máquina corporativa.

Enumeração

"USER"

"MACHINE"

Token

Propriedades

• ID

  string

  Identifica exclusivamente este 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 da plataforma, 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 apoiadas por software. A proteção das chaves e, portanto, a implementação da propriedade não extraível, é feita no 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. O único tipo de chave aceito é RSASSA-PKCS1-V1_5 com modulusLength de até 2048. Cada chave 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 geradas em um Token específico não podem ser usadas com outros tokens nem com o window.crypto.subtle. Da mesma forma, os 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 com suporte de hardware.

  Só é possível gerar chaves não extraíveis. Os tipos de chave compatíveis são RSASSA-PKCS1-V1_5 com modulusLength de até 2048 e ECDSA com namedCurve P-256. Cada chave 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 geradas em um Token específico não podem ser usadas com outros tokens nem com o window.crypto.subtle. Da mesma forma, os objetos Key criados com window.crypto.subtle não podem ser usados com essa interface.

Métodos

challengeKey()

Promessa Chrome 110+

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 Enterprise com suporte de hardware e emite a resposta como parte de um protocolo de atestação remota. Útil apenas no ChromeOS e em conjunto com a API Web de acesso verificado, que emite desafios e verifica respostas.

Uma verificação bem-sucedida pela API Web de Acesso Verificado é 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 no momento é gerenciado pelo domínio especificado durante a verificação e que o estado atual do dispositivo está em conformidade com a política do dispositivo corporativo. Por exemplo, uma política pode especificar que o dispositivo não pode estar no modo de desenvolvedor. Qualquer identificador do dispositivo emitido pela verificação está estritamente vinculado ao hardware do dispositivo atual. Se o escopo "user" for especificado, a identidade também será vinculada 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 essa operação não tiver sido explicitamente ativada para o autor da chamada pela política do dispositivo corporativo. A chave contestada não reside no token "system" ou "user" e não pode ser acessada por nenhuma outra API.

Parâmetros

• opções

  ChallengeKeyOptions

  Objeto que contém os campos definidos em ChallengeKeyOptions.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (response: ArrayBuffer) => void

  • resposta

    ArrayBuffer

    A resposta ao desafio.

Retorna

• Promise<ArrayBuffer>

  Chrome 131+

  Retorna uma promessa que é resolvida com a resposta do desafio.

  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+ Descontinuado desde o Chrome 110

chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Use challengeKey.

Desafia uma chave de máquina Enterprise com suporte de hardware e emite a resposta como parte de um protocolo de atestação remota. Útil apenas no ChromeOS e em conjunto com a API Web de acesso verificado, que emite desafios e verifica respostas. Uma verificação bem-sucedida pela API Web de acesso verificado é 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 conectado no momento é gerenciado pelo domínio especificado durante a verificação. O estado atual do dispositivo está em conformidade com a política do dispositivo corporativo. Por exemplo, uma política pode especificar que o dispositivo não pode estar no modo de desenvolvedor. * Qualquer identificador do dispositivo emitido pela verificação está estritamente vinculado 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 autor da chamada pela política do dispositivo corporativo. A chave de máquina corporativa 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 Web de acesso verificado.

• registerKey

  booleano opcional

  Chrome 59 ou mais recente

  Se definida, a chave de máquina empresarial atual é registrada com o token "system" e abre mão do 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 2.048 bits. As chamadas subsequentes para essa função vão gerar uma nova chave de máquina empresarial.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (response: ArrayBuffer) => void

  • resposta

    ArrayBuffer

    A resposta ao desafio.

Retorna

• Promise<ArrayBuffer>

  Chrome 131+

  Retorna uma promessa que é resolvida com a resposta do desafio.

  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+ Descontinuado desde o Chrome 110

chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Use challengeKey.

Desafia uma chave de usuário corporativo com suporte de hardware e emite a resposta como parte de um protocolo de atestação remota. Útil apenas no ChromeOS e em conjunto com a API Web de acesso verificado, que emite desafios e verifica respostas. Uma verificação bem-sucedida pela API Web de acesso verificado é 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 conectado no momento é gerenciado pelo domínio especificado durante a verificação. * O estado atual do dispositivo obedece à política de 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á 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 essa 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 corporativo 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 Web de acesso verificado.

• registerKey

  booleano

  Se definida, a chave de usuário corporativo atual será registrada com o token "user" e abrirá mão do 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 2.048 bits. As chamadas subsequentes para essa função vão gerar uma nova chave de usuário corporativo.

• callback

  função optional

  O parâmetro callback é semelhante a:

  (response: ArrayBuffer) => void

  • resposta

    ArrayBuffer

    A resposta ao desafio.

Retorna

• Promise<ArrayBuffer>

  Chrome 131+

  Retorna uma promessa que é resolvida com a resposta do desafio.

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

getCertificates()

Promessa

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

Retorna a lista de todos os certificados do cliente disponíveis no token fornecido. Pode ser usado para verificar a existência e a validade 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 optional

  O parâmetro callback é semelhante a:

  (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+

  Retorna uma promessa que é resolvida com a lista de certificados disponíveis.

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

getTokens()

Promessa

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

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

Parâmetros

• callback

  função optional

  O parâmetro callback é semelhante a:

  (tokens: Token[]) => void

  • tokens

    Token[]

    A lista de tokens disponíveis.

Retorna

• Promise<Token[]>

  Chrome 131+

  Invocado por getTokens com a lista de tokens disponíveis.

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

importCertificate()

Promessa

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

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 é semelhante a:

  () => void

Retorna

• Promessa<void>

  Chrome 131+

  Retorna uma promessa que é resolvida quando essa operação é concluída.

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

removeCertificate()

Promessa

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

Remove certificate do token fornecido, se houver. 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 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 é semelhante a:

  () => void

Retorna

• Promessa<void>

  Chrome 131+

  Retorna uma promessa que é resolvida quando essa operação é concluída.

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