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 mais recente Somente no ChromeOS

Conceitos e uso

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

  • A extensão se registra nos 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 disponíveis e chama setCertificates() para notificar o navegador sobre cada mudança.
  • Durante um handshake de TLS, o navegador recebe uma solicitação de certificado do cliente. Com um evento onCertificatesUpdateRequested, o navegador pede que a extensão informe todos os certificados que ela fornece no momento.
  • A extensão envia um relatório com os certificados disponíveis no momento usando o método setCertificates().
  • O navegador corresponde a todos os certificados disponíveis com a 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 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 vai pedir que ela 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 precisa ser usado para gerar a assinatura e se refere a um dos certificados informados por essa extensão. A extensão precisa criar uma assinatura para os dados fornecidos usando a chave privada associada ao certificado referenciado. A criação da assinatura pode exigir a adição de um DigestInfo e o preenchimento do resultado antes da assinatura real.
  • A extensão envia a assinatura de volta ao navegador usando o método reportSignature(). Se não for possível calcular a assinatura, o método precisará ser chamado sem ela.
  • Se a assinatura foi fornecida, o navegador conclui o handshake de TLS.

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

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

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+

Tipos de algoritmos de assinatura criptográfica compatíveis.

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 adicionar um prefixo DigestInfo, apenas o padding PKCS#1. Esse algoritmo está 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 de máscara MGF1 e o salt do mesmo tamanho do 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 de máscara MGF1 e o salt do mesmo tamanho do 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 de máscara MGF1 e o salt do mesmo tamanho do hash.

CertificateInfo

Propriedades

  • certificado

    ArrayBuffer

    Precisa ser a codificação DER de um certificado X.509. No momento, só há suporte para certificados de chaves RSA.

  • supportedHashes

    Hash[]

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

CertificatesUpdateRequest

Chrome 86+

Propriedades

  • certificatesRequestId

    número

    Identificador da solicitação a ser transmitido para setCertificates.

ClientCertificateInfo

Chrome 86+

Propriedades

  • certificateChain

    ArrayBuffer[]

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

    Isso precisa incluir exatamente um certificado.

  • supportedAlgorithms

    Algorithm[]

    Todos os algoritmos compatíveis com este certificado. A extensão só vai pedir assinaturas usando um desses algoritmos.

Error

Chrome 86+

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

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 a PUK é inválida.

"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 mais recente

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 é um PUK.

PinResponseDetails

Chrome 57 ou mais recente

Propriedades

  • userInput

    string opcional

    O código fornecido pelo usuário. Fica vazio se o usuário fechar a caixa de diálogo ou se ocorrer algum outro erro.

ReportSignatureDetails

Chrome 86+

Propriedades

  • erro

    "GENERAL_ERROR"
     optional

    Erro que ocorreu ao gerar a assinatura, se houver.

  • signRequestId

    número

    Identificador da solicitação recebida pelo evento onSignatureRequested.

  • assinatura

    ArrayBuffer opcional

    A assinatura, se gerada com sucesso.

RequestPinDetails

Chrome 57 ou mais recente

Propriedades

  • attemptsLeft

    number optional

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

  • errorType

    PinRequestErrorType opcional

    O modelo de erro exibido ao usuário. Isso precisa 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

    número

    O ID fornecido pelo Chrome no SignRequest.

SetCertificatesDetails

Chrome 86+

Propriedades

  • certificatesRequestId

    number optional

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

  • clientCertificates

    ClientCertificateInfo[]

    Lista dos certificados de cliente disponíveis no momento.

  • erro

    "GENERAL_ERROR"
     optional

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

SignatureRequest

Chrome 86+

Propriedades

  • algoritmo

    Algorithm

    Algoritmo de assinatura a ser usado.

  • certificado

    ArrayBuffer

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

  • entrada

    ArrayBuffer

    Dados a serem assinados. Os dados não são criptografados com hash.

  • signRequestId

    número

    Identificador da solicitação a ser transmitido para reportSignature.

SignRequest

Propriedades

  • certificado

    ArrayBuffer

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

  • resumo

    ArrayBuffer

    O resumo que precisa ser assinado.

  • jogo da velha

    Hash

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

  • signRequestId

    número

    Chrome 57 ou mais recente

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

Propriedades

  • errorType

    PinRequestErrorType opcional

    O modelo de erro. Se estiver presente, será exibido para o usuário. Destinado a conter o motivo da interrupção do fluxo se ela foi causada por um erro, por exemplo, MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    número

    O ID fornecido pelo Chrome no SignRequest.

Métodos

reportSignature()

Chrome 86+ 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

Deve ser chamado como uma resposta a onSignatureRequested.

A extensão precisa chamar essa função para cada evento onSignatureRequested. A implementação da API para de aguardar essa chamada após algum tempo e responde com um erro de tempo limite quando essa função é chamada.

Parâmetros

Retorna

  • Promise<void>

    Chrome 96+

requestPin()

Chrome 57 ou mais recente 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

Solicita o PIN do usuário. Só é permitido um pedido 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

  • Contém os detalhes sobre a caixa de diálogo solicitada.

Retorna

setCertificates()

Chrome 86+ 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

Define uma lista de certificados para usar no navegador.

A extensão precisa chamar essa função após a inicialização e sempre que houver uma mudança 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.

Retorna

  • Promise<void>

    Chrome 96+

stopPinRequest()

Chrome 57 ou mais recente 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

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

Parâmetros

  • Contém detalhes sobre o motivo da interrupção do fluxo de solicitação.

Retorna

  • Promise<void>

    Chrome 96+

Eventos

onCertificatesUpdateRequested

Chrome 86+ 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Esse evento é disparado se os certificados definidos via 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+ 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Esse evento é disparado sempre que o navegador precisa 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 retornar chamando reportSignature com o signRequestId recebido.

Parâmetros