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 outra extensão com chrome.platformKeys.

Permissões

enterprise.platformKeys

Disponibilidade

Somente no ChromeOS Requer política

Conceitos e uso

O uso típico dessa API para registrar um certificado de cliente segue estas etapas:

  • Acesse todos os tokens disponíveis usando enterprise.platformKeys.getTokens().

  • Encontre o token com id igual a "user". Use esse token depois.

  • 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 em 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()`[3]

Confira um exemplo que mostra a interação principal 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 versão mais recente

Tipo de chave a ser gerada.

Enumeração

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 e versões mais recentes

Propriedades

  • desafio

    ArrayBuffer

    Um desafio emitido pela API Web Verified Access.

  • registerKey

    RegisterKeyOptions opcional

    Se presente, registra a chave desafiada com o token do scope especificado. A chave pode então 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 corporativa no scope especificado.

  • escopo

    Escopo

    Qual chave empresarial será contestada.

RegisterKeyOptions

Chrome 110 ou versão mais recente

Propriedades

  • algoritmo

    Algorithm

    Qual algoritmo a chave registrada deve usar.

Scope

Chrome 110 ou versão mais recente

Se a chave de usuário ou a chave de máquina corporativa será usada.

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, respectivamente. Outros tokens (com outros identificadores) podem ser retornados por enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 e versões mais recentes

    Implementa a interface SubtleCrypto do WebCrypto. As operações criptográficas, incluindo a geração de chaves, são protegidas por software. A proteção das chaves e, portanto, a implementação da propriedade não extraível, é feita no software, de modo que as chaves são menos protegidas do que as chaves protegidas por hardware.

    Somente chaves RSASSA-PKCS1-V1_5 não extraíveis com modulusLength de até 2.048 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 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 do WebCrypto. As operações criptográficas, incluindo a geração de chaves, são compatíveis com hardware.

    Somente chaves RSASSA-PKCS1-V1_5 não extraíveis com modulusLength de até 2048 e ECDSA com namedCurve 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 com 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 e mais recentes 
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 com a API Verified Access Web, que emite desafios e verifica as respostas.

Uma verificação bem-sucedida pela API Verified Access Web é um sinal 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 obedece à 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 emitida pela verificação está 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 fica 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 este formato: 

    (response: ArrayBuffer) => void

    • resposta

      ArrayBuffer

      A resposta do desafio.

Retorna

  • Promise<ArrayBuffer>

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

challengeMachineKey()

Promessa Chrome 50 ou mais recente Descontinuado desde o Chrome 110
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 com a API Verified Access Web, que emite desafios e verifica as respostas. Uma verificação bem-sucedida pela API Verified Access Web é um forte sinal de todos os itens a seguir: * 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á 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 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 da empresa não fica no token "system" e não pode ser acessada 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 recentes

    Se definida, a chave de máquina da empresa atual será registrada com o token "system" e renuncia ao papel de chave de máquina da empresa. A chave pode então ser associada a um certificado e usada como qualquer outra chave de assinatura. Essa chave é RSA de 2048 bits. Chamadas subsequentes para essa função vão gerar uma nova chave de máquina corporativa.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    (response: ArrayBuffer) => void

    • resposta

      ArrayBuffer

      A resposta do desafio.

Retorna

  • Promise<ArrayBuffer>

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

challengeUserKey()

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

Use challengeKey.

Aplica uma chave de usuário 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 Verified Access Web é um forte indicador de todos os itens a seguir: * 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 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á fortemente vinculada ao hardware do dispositivo atual e ao usuário conectado no momento. Esta função é altamente restrita e 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 explicitamente ativada para o autor da chamada pela política do usuário corporativo. A chave de usuário corporativa não fica 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 então ser associada a um certificado e usada como qualquer outra chave de assinatura. Essa chave é RSA de 2048 bits. Chamadas subsequentes para essa função vão gerar uma nova chave de usuário corporativo.

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (response: ArrayBuffer) => void

    • resposta

      ArrayBuffer

      A resposta do desafio.

Retorna

  • Promise<ArrayBuffer>

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getCertificates()

Promessa 
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&lt;ArrayBuffer[]&gt;

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

getTokens()

Promessa 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

Retorna os tokens disponíveis. Em uma sessão de usuário normal, a lista sempre 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

  • callback

    função opcional

    O parâmetro callback tem este formato: 

    (tokens: Token[]) => void

    • tokens

      Token[]

      A lista de tokens disponíveis.

Retorna

  • Promessa<Token[]>

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

importCertificate()

Promessa 
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

  • Promessa<void>

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.

removeCertificate()

Promessa 
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 de certificados. Precisa 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

  • Promessa<void>

    Pendente

    O Manifesto V3 e versões mais recentes oferecem suporte a promessas, mas callbacks são fornecidos para a compatibilidade com versões anteriores. Não é possível usar os dois na mesma chamada de função. A promessa é resolvida com o mesmo tipo transmitido para o callback.