browser.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

Conceitos e 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()`[3]

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) {
  browser.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) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

Tipos

Algorithm

Chrome 110+ browser.* desde o Chrome 148

Tipo de chave a ser gerada.

Enumeração

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

Propriedades

  • algoritmo

    Algorithm

    Qual algoritmo a chave registrada deve usar.

Scope

Chrome 110+ browser.* desde o Chrome 148

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+ browser.* desde o Chrome 148

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

Chrome 110+ browser.* desde o Chrome 148 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): 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

Retorna

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* desde o Chrome 148

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

challengeMachineKey()

Chrome 50+ browser.* desde o Chrome 148 Descontinuado desde o Chrome 110
browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): 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+ browser.* desde o Chrome 148

    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.

Retorna

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* desde o Chrome 148

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

challengeUserKey()

Chrome 50+ browser.* desde o Chrome 148 Descontinuado desde o Chrome 110
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): 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.

Retorna

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* desde o Chrome 148

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

getCertificates()

browser.enterprise.platformKeys.getCertificates(
  tokenId: string,
): 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.

Retorna

  • Promise<ArrayBuffer[]>

    Chrome 131+ browser.* desde o Chrome 148

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

getTokens()

browser.enterprise.platformKeys.getTokens(): 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).

Retorna

  • Promise<Token[]>

    Chrome 131+ browser.* desde o Chrome 148

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

importCertificate()

browser.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): 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.

Retorna

  • Promessa<void>

    Chrome 131+ browser.* desde o Chrome 148

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

removeCertificate()

browser.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): 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.

Retorna

  • Promessa<void>

    Chrome 131+ browser.* desde o Chrome 148

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