chrome.certificateProvider

Descrição

Use essa API para expor certificados à plataforma que pode usá-los para autenticações TLS.

Permissões

certificateProvider

Disponibilidade

Chrome 46 ou superior Somente ChromeOS

Conceitos e uso

O uso típico dessa API para expor certificados do cliente ao ChromeOS segue estas etapas:

  • A extensão se registra para os eventos onCertificatesUpdateRequested e onSignatureRequested.
  • A extensão chama setCertificates() para fornecer a lista inicial de certificados após a inicialização.
  • A extensão monitora as mudanças na lista de certificados e chamadas disponíveis setCertificates() para notificar o navegador sobre essas mudanças.
  • Durante um handshake de TLS, o navegador recebe uma solicitação de certificado do cliente. Com um evento onCertificatesUpdateRequested, o navegador pede à extensão que informe todos os certificados oferecidos.
  • A extensão gera relatórios com os certificados disponíveis no momento usando o método setCertificates().
  • O navegador associa todos os certificados disponíveis à solicitação de certificado do cliente do host remoto. As correspondências são apresentadas ao usuário em uma caixa de diálogo de seleção.
  • O usuário pode selecionar um certificado e, assim, aprovar ou cancelar a autenticação.
.
Caixa de diálogo de seleção de certificado
Caixa de diálogo de seleção de certificado.
  • Se o usuário cancelar a autenticação ou se nenhum certificado corresponder à solicitação, a autenticação do cliente TLS será cancelada.
  • Caso contrário, se o usuário aprovar a autenticação com um certificado fornecido por essa extensão, o navegador solicitará que a extensão assine os dados para continuar o handshake de TLS. A solicitação é enviada como um evento onSignatureRequested.
  • Esse evento contém dados de entrada, declara qual algoritmo deve ser usado para gerar a assinatura e faz referência a um dos certificados relatados por esta extensão. A extensão deve criar uma assinatura para os dados fornecidos usando a chave privada associada ao certificado referenciado. A criação da assinatura pode exigir o prefixo DigestInfo e o preenchimento do resultado antes da assinatura em si.
  • A extensão retorna a assinatura ao navegador usando o método reportSignature(). Se não for possível calcular a assinatura, o método terá que ser chamado sem assinatura.
  • Se a assinatura foi fornecida, o navegador conclui o handshake de TLS.

A sequência real das etapas pode ser diferente. Por exemplo, o usuário não precisará selecionar um certificado se a política corporativa para selecionar automaticamente um certificado for usada. Consulte AutoSelectCertificateForUrls e Políticas do Chrome para usuários.

Na extensão, isso pode ser semelhante ao seguinte snippet:

function collectAvailableCertificates() {
  // Return all certificates that this Extension can currently provide.
  // For example:
  return [{
    certificateChain: [new Uint8Array(...)],
    supportedAlgorithms: ['RSASSA_PKCS1_v1_5_SHA256']
  }];
}

// The Extension calls this function every time the currently available list of
// certificates changes, and also once after the Extension's initialization.
function onAvailableCertificatesChanged() {
  chrome.certificateProvider.setCertificates({
    clientCertificates: collectAvailableCertificates()
  });
}

function handleCertificatesUpdateRequest(request) {
  // Report the currently available certificates as a response to the request
  // event. This is important for supporting the case when the Extension is
  // unable to detect the changes proactively.
  chrome.certificateProvider.setCertificates({
    certificatesRequestId: request.certificatesRequestId,
    clientCertificates: collectAvailableCertificates()
  });
}

// Returns a private key handle for the given DER-encoded certificate.
// |certificate| is an ArrayBuffer.
function getPrivateKeyHandle(certificate) {...}

// Digests and signs |input| with the given private key. |input| is an
// ArrayBuffer. |algorithm| is an Algorithm.
// Returns the signature as ArrayBuffer.
function signUnhashedData(privateKey, input, algorithm) {...}

function handleSignatureRequest(request) {
  // Look up the handle to the private key of |request.certificate|.
  const key = getPrivateKeyHandle(request.certificate);
  if (!key) {
    // Handle if the key isn't available.
    console.error('Key for requested certificate no available.');

    // Abort the request by reporting the error to the API.
    chrome.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  chrome.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
chrome.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

Tipos

Algorithm

Chrome 86 ou versão mais recente

Tipos de algoritmos de assinatura criptográfica com suporte.

Enumeração

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Especifica o algoritmo de assinatura RSASSA PKCS#1 v1.5 com o hash MD5-SHA-1. A extensão não pode preceder um prefixo DigestInfo, apenas adicionar padding PKCS#1. Esse algoritmo foi descontinuado e nunca será solicitado pelo Chrome a partir da versão 109.

"RSASSA_PKCS1_v1_5_SHA1"
Especifica o algoritmo de assinatura RSASSA PKCS#1 v1.5 com a função de hash SHA-1.

"RSASSA_PKCS1_v1_5_SHA256"
Especifica o algoritmo de assinatura RSASSA PKCS#1 v1.5 com a função de hash SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Especifica o algoritmo de assinatura RSASSA PKCS#1 v1.5 com a função de hash SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Especifica o algoritmo de assinatura RSASSA PKCS#1 v1.5 com a função de hash SHA-512.

"RSASSA_PSS_SHA256"
Especifica o algoritmo de assinatura RSASSA PSS com a função de hash SHA-256, a função de geração da máscara MGF1 e o sal do mesmo tamanho que o hash.

"RSASSA_PSS_SHA384"
Especifica o algoritmo de assinatura RSASSA PSS com a função de hash SHA-384, a função de geração da máscara MGF1 e o sal do mesmo tamanho que o hash.

"RSASSA_PSS_SHA512"
Especifica o algoritmo de assinatura RSASSA PSS com a função de hash SHA-512, a função de geração da máscara MGF1 e o sal do mesmo tamanho que o hash.

CertificateInfo

Propriedades

  • certificado

    Buffer de matriz

    Precisa ser a codificação DER de um certificado X.509. Atualmente, apenas certificados de chaves RSA são compatíveis.

  • supportedHashes

    Hash[]

    Precisa ser definido como todos os hashes compatíveis com este certificado. Esta extensão só será solicitada para assinaturas de resumos calculados com um desses algoritmos de hash. Isso deve estar em ordem de preferência de hash decrescente.

CertificatesUpdateRequest

Chrome 86 ou versão mais recente

Propriedades

  • certificatesRequestId

    number

    O identificador de solicitação a ser transmitido para setCertificates.

ClientCertificateInfo

Chrome 86 ou versão mais recente

Propriedades

  • certificateChain

    ArrayBuffer[]

    A matriz precisa conter a codificação DER do certificado do cliente X.509 como o primeiro elemento.

    Isso precisa incluir exatamente um certificado.

  • supportedAlgorithms

    Algoritmo[]

    Todos os algoritmos compatíveis com este certificado. A extensão só será solicitada quanto a assinaturas usando um desses algoritmos.

Error

Chrome 86 ou versão mais recente

Tipos de erros que a extensão pode informar.

Valor

"GENERAL_ERROR"

Hash

Obsoleto. Substituído por Algorithm.

Enumeração

"MD5_SHA1"
Especifica os algoritmos de hash MD5 e SHA1.

"SHA1"
Especifica o algoritmo de hash SHA1.

"SHA256"
Especifica o algoritmo de hash SHA256.

"SHA384"
Especifica o algoritmo de hash SHA384.

"SHA512"
Especifica o algoritmo de hash SHA512.

PinRequestErrorType

Chrome 57 ou superior

Os tipos de erros que podem ser apresentados ao usuário pela função requestPin.

Enumeração

"INVALID_PIN"
Especifica que o PIN é inválido.

"INVALID_PUK"
Especifica que o PUK é inválido.

"MAX_ATTEMPTS_EXCEEDED"
Especifica que o número máximo de tentativas foi excedido.

"UNKNOWN_ERROR"
Especifica que o erro não pode ser representado pelos tipos acima.

PinRequestType

Chrome 57 ou superior

O tipo de código solicitado pela extensão com a função requestPin.

Enumeração

"PIN"
Especifica que o código solicitado é um PIN.

"PUK"
Especifica que o código solicitado é uma PUK.

PinResponseDetails

Chrome 57 ou superior

Propriedades

  • userInput

    string opcional

    Código fornecido pelo usuário. Vai ser vazio se o usuário tiver fechado a caixa de diálogo ou se tiver ocorrido algum outro erro.

ReportSignatureDetails

Chrome 86 ou versão mais recente

Propriedades

  • erro

    "GENERAL_ERROR"
     opcional

    Erro que ocorreu ao gerar a assinatura, se houver.

  • signRequestId

    number

    O identificador de solicitação que foi recebido pelo evento onSignatureRequested.

  • assinatura

    ArrayBuffer opcional

    A assinatura, se gerada com sucesso.

RequestPinDetails

Chrome 57 ou superior

Propriedades

  • attemptsLeft

    número opcional

    O número de tentativas restantes. Isso é fornecido para que qualquer interface possa apresentar essas informações ao usuário. Não se espera que o Chrome aplique isso. Em vez disso, stopPinRequest deve ser chamado pela extensão com errorType = MAX_ATTEMPTS_EXCEEDED quando o número de solicitações de PIN é excedido.

  • errorType

    PinRequestErrorType optional

    O modelo de erro exibido ao usuário. Deve ser definido se a solicitação anterior falhou, para notificar o usuário sobre o motivo da falha.

  • requestType

    PinRequestType opcional

    O tipo de código solicitado. O padrão é PIN.

  • signRequestId

    number

    O ID fornecido pelo Chrome na SignRequest.

SetCertificatesDetails

Chrome 86 ou versão mais recente

Propriedades

  • certificatesRequestId

    número opcional

    Quando chamado em resposta a onCertificatesUpdateRequested, precisa conter o valor certificatesRequestId recebido. Caso contrário, não deve ser definido.

  • clientCertificates

    ClientCertificateInfo[]

    Lista de certificados do cliente disponíveis no momento.

  • erro

    "GENERAL_ERROR"
     opcional

    Erro que ocorreu ao extrair os certificados, se houver. Esse erro será exibido ao usuário quando apropriado.

SignatureRequest

Chrome 86 ou versão mais recente

Propriedades

  • algoritmo

    Algorithm

    Algoritmo de assinatura a ser usado.

  • certificado

    Buffer de matriz

    A codificação DER de um certificado X.509. A extensão precisa assinar input usando a chave privada associada.

  • entrada

    Buffer de matriz

    Dados a serem assinados. Vale lembrar que os dados não estão criptografados com hash.

  • signRequestId

    number

    O identificador de solicitação a ser transmitido para reportSignature.

SignRequest

Propriedades

  • certificado

    Buffer de matriz

    A codificação DER de um certificado X.509. A extensão precisa assinar digest usando a chave privada associada.

  • resumo

    Buffer de matriz

    O resumo que precisa ser assinado.

  • jogo da velha

    Hash

    Refere-se ao algoritmo de hash usado para criar digest.

  • signRequestId

    number

    Chrome 57 ou superior

    O ID exclusivo a ser usado pela extensão caso ela precise chamar um método que o exija, por exemplo, requestPin.

StopPinRequestDetails

Chrome 57 ou superior

Propriedades

  • errorType

    PinRequestErrorType optional

    O modelo de erro. Se estiver presente, ele será exibido para o usuário. Destina-se a conter o motivo para interromper o fluxo se ele tiver sido causado por um erro, por exemplo, MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    number

    O ID fornecido pelo Chrome na SignRequest.

Métodos

reportSignature()

Promessa Chrome 86 ou versão mais recente 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Precisa ser chamado como uma resposta a onSignatureRequested.

A extensão precisa chamar essa função para cada evento onSignatureRequested. a implementação da API deixará de esperar por essa chamada após algum tempo e responderá com um erro de tempo limite quando essa função for chamada.

Parâmetros

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou versão mais recente

    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 ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

requestPin()

Promessa Chrome 57 ou versão mais recente 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Solicita o PIN ao usuário. Só é permitida uma solicitação em andamento por vez. As solicitações emitidas enquanto outro fluxo está em andamento são rejeitadas. É responsabilidade da extensão tentar novamente mais tarde se outro fluxo estiver em andamento.

Parâmetros

Retorna

  • Promise&lt;PinResponseDetails | indefinido>

    Chrome 96 ou versão mais recente

    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 ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

setCertificates()

Promessa Chrome 86 ou versão mais recente 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Define uma lista de certificados para uso no navegador.

A extensão precisa chamar essa função após a inicialização e em cada alteração no conjunto de certificados disponíveis no momento. A extensão também precisa chamar essa função em resposta a onCertificatesUpdateRequested sempre que esse evento for recebido.

Parâmetros

  • Os certificados a serem definidos. Certificados inválidos serão ignorados.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou versão mais recente

    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 ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

stopPinRequest()

Promessa Chrome 57 ou versão mais recente 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Interrompe a solicitação de fixação iniciada pela função requestPin.

Parâmetros

  • Contém detalhes sobre o motivo para interromper o fluxo de solicitações.

  • callback

    função opcional

    O parâmetro callback tem esta aparência: 

    () => void

Retorna

  • Promessa<void>

    Chrome 96 ou versão mais recente

    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 ambos na mesma chamada de função. A promessa é resolvida com o mesmo tipo passado ao retorno de chamada.

Eventos

onCertificatesRequested

Chrome 47 ou superior &amp;leq; MV2 Descontinuado desde o Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Use onCertificatesUpdateRequested.

Esse evento é disparado sempre que o navegador solicita a lista atual de certificados fornecidos por essa extensão. A extensão precisa chamar reportCallback exatamente uma vez com a lista atual de certificados.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (reportCallback: function) => void

    • reportCallback

      função

      O parâmetro reportCallback tem esta aparência: 

      (certificates: CertificateInfo[], callback: function) => void

      • certificados

        CertificateInfo[]

      • callback

        função

        O parâmetro callback tem esta aparência: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 ou versão mais recente 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Este evento é disparado se os certificados definidos por setCertificates forem insuficientes ou se o navegador solicitar informações atualizadas. A extensão precisa chamar setCertificates com a lista atualizada de certificados e o certificatesRequestId recebido.

Parâmetros

onSignatureRequested

Chrome 86 ou versão mais recente 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Esse evento é disparado sempre que o navegador precisar assinar uma mensagem usando um certificado fornecido por essa extensão via setCertificates.

A extensão precisa assinar os dados de entrada de request usando o algoritmo e a chave privada adequados e retorná-los chamando reportSignature com o signRequestId recebido.

Parâmetros

onSignDigestRequested

&amp;leq; MV2 Descontinuado desde o Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Use onSignatureRequested.

Esse evento é disparado sempre que o navegador precisar assinar uma mensagem usando um certificado fornecido por essa extensão em resposta a um evento onCertificatesRequested. A extensão precisa assinar os dados no request usando o algoritmo e a chave privada adequados e retorná-los chamando reportCallback. reportCallback precisa ser chamado exatamente uma vez.

Parâmetros

  • callback

    função

    O parâmetro callback tem esta aparência: 

    (request: SignRequest, reportCallback: function) => void

    • solicitação

      SignRequest

    • reportCallback

      função

      Chrome 47 ou superior

      O parâmetro reportCallback tem esta aparência: 

      (signature?: ArrayBuffer) => void

      • assinatura

        ArrayBuffer opcional