Descrição
Use essa API para expor certificados para a plataforma que pode usar esses certificados para autenticações TLS.
Permissões
certificateProvider
Disponibilidade
Conceitos e uso
O uso comum dessa API para expor certificados do cliente ao ChromeOS segue estas etapas:
- A extensão é registrada nos eventos
onCertificatesUpdateRequested
eonSignatureRequested
. - 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 à extensão para informar todos os certificados oferecidos no momento. - A extensão retorna os relatórios com os certificados disponíveis 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](https://developer.chrome.google.cn/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=5&hl=pt)
- 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á a extensão para assinar os dados e 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 o prefixo 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 assinatura. - Se a assinatura tiver sido fornecida, o navegador concluirá 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 corporativa que seleciona 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
Tipos de algoritmos de assinatura criptográfica compatíveis.
Tipo enumerado
"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 prefixar um prefixo DigestInfo, mas 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 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 PSS da RSASSA com a função de hash SHA-256, a função de geração de máscara MGF1 e o sal do mesmo tamanho que o hash.
"RSASSA_PSS_SHA384"
Especifica o algoritmo de assinatura PSS da RSASSA com a função de hash SHA-384, a função de geração de máscara MGF1 e o sal do mesmo tamanho que o hash.
"RSASSA_PSS_SHA512"
Especifica o algoritmo de assinatura PSS da RSASSA com a função de hash SHA-512, a função de geração de máscara MGF1 e o sal do mesmo tamanho que o hash.
CertificateInfo
Propriedades
-
certificado
ArrayBuffer
Precisa ser a codificação DER de um certificado X.509. Atualmente, apenas certificados de Chaves RSA são aceitos.
-
supportedHashes
Hash[]
Precisa ser definido para todos os hashes compatíveis com este certificado. Essa extensão só vai solicitar assinaturas de resumos calculados com um desses algoritmos de hash. Isso precisa estar em ordem de preferência de hash decrescente.
CertificatesUpdateRequest
Propriedades
-
certificatesRequestId
number
Identificador de solicitação a ser transmitido para
setCertificates
.
ClientCertificateInfo
Propriedades
-
certificateChain
ArrayBuffer[]
A matriz deve conter a codificação DER do certificado do cliente X.509 como seu primeiro elemento.
É necessário incluir exatamente um certificado.
-
supportedAlgorithms
Todos os algoritmos são compatíveis com este certificado. A extensão só vai solicitar assinaturas usando um desses algoritmos.
Error
Tipos de erros que a extensão pode informar.
Valor
"GENERAL_ERROR"
Hash
Obsoleto. Substituído por Algorithm
.
Tipo enumerado
"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
Os tipos de erros que podem ser apresentados ao usuário por meio da função requestPin.
Tipo enumerado
"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
O tipo de código solicitado pela extensão com a função requestPin.
Tipo enumerado
PIN
Especifica que o código solicitado é um PIN.
"PUK"
Especifica que o código solicitado é um PUK.
PinResponseDetails
Propriedades
-
userInput
string opcional
O código fornecido pelo usuário. Vai ser vazio se o usuário tiver fechado a caixa de diálogo ou se ocorrer algum outro erro.
ReportSignatureDetails
Propriedades
-
error
opcional
Erro que ocorreu ao gerar a assinatura, se houver.
-
signRequestId
number
O identificador da solicitação que foi recebido pelo evento
onSignatureRequested
. -
assinatura
ArrayBuffer opcional
A assinatura, se gerada.
RequestPinDetails
Propriedades
-
attemptsLeft
número opcional
O número de tentativas restantes. Ele é 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 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. Deve ser definido se a solicitação anterior falhar, para notificar o usuário sobre o motivo da falha.
-
requestType
PinRequestType opcional
O tipo de código solicitado. O padrão é o PIN.
-
signRequestId
number
O ID fornecido pelo Chrome em SignRequest.
SetCertificatesDetails
Propriedades
-
certificatesRequestId
número opcional
Quando chamado em resposta a
onCertificatesUpdateRequested
, precisa conter o valorcertificatesRequestId
recebido. Caso contrário, ela não deve ser definida. -
clientCertificates
Lista de certificados do cliente disponíveis no momento.
-
error
opcional
Erro que ocorreu ao extrair os certificados, se houver. Esse erro será exibido ao usuário quando apropriado.
SignatureRequest
Propriedades
-
algoritmo
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
number
Identificador de 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
Refere-se ao algoritmo de hash usado para criar o
digest
. -
signRequestId
number
Chrome 57 ou mais recenteO ID exclusivo a ser usado pela extensão caso ela precise chamar um método que exija isso, por exemplo, requestPin.
StopPinRequestDetails
Propriedades
-
errorType
PinRequestErrorType opcional
O modelo de erro. Se estiver presente, ele será exibido ao usuário. Destina-se a conter o motivo da interrupção do fluxo se ele foi causado por um erro, por exemplo, MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
number
O ID fornecido pelo Chrome em SignRequest.
Métodos
reportSignature()
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
-
detalhes
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para 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 que é passado para o callback.
requestPin()
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
-
detalhes
Contém os detalhes sobre a caixa de diálogo solicitada.
-
callback
função optional
O parâmetro
callback
tem esta aparência:(details?: PinResponseDetails) => void
-
detalhes
PinResponseDetails opcional
-
Retorna
-
Promise<PinResponseDetails | undefined>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para 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 que é passado para o callback.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Define uma lista de certificados a ser usada 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
-
detalhes
Os certificados a serem definidos. Certificados inválidos serão ignorados.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para 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 que é passado para o callback.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Interrompe a solicitação de fixação iniciada pela função requestPin
.
Parâmetros
-
detalhes
Contém os detalhes sobre o motivo para interromper o fluxo de solicitação.
-
callback
função optional
O parâmetro
callback
tem esta aparência:() => void
Retorna
-
Promise<void>
Chrome 96 ou mais recentePromessas são compatíveis com o Manifest V3 e versões mais recentes, mas callbacks são fornecidos para 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 que é passado para o callback.
Eventos
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Use onCertificatesUpdateRequested
.
Este 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
-
certificates
-
callback
função
O parâmetro
callback
tem esta aparência:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
Esse evento é disparado se os certificados definidos em setCertificates
forem insuficientes ou o navegador solicitar informações atualizadas. A extensão precisa chamar setCertificates
com a lista atualizada de certificados e o certificatesRequestId
recebido.
Parâmetros
-
callback
função
O parâmetro
callback
tem esta aparência:(request: CertificatesUpdateRequest) => void
-
request
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
Este evento é disparado sempre que o navegador precisa assinar uma mensagem usando um certificado fornecido pela 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
-
callback
função
O parâmetro
callback
tem esta aparência:(request: SignatureRequest) => void
-
request
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
Use onSignatureRequested
.
Este evento é disparado sempre que o navegador precisa assinar uma mensagem usando um certificado fornecido por essa extensão em resposta a um evento onCertificatesRequested
. A extensão precisa assinar os dados em 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
-
request
-
reportCallback
função
Chrome 47 ou mais recenteO parâmetro
reportCallback
tem esta aparência:(signature?: ArrayBuffer) => void
-
assinatura
ArrayBuffer opcional
-
-