Descrizione
Utilizza questa API per esporre i certificati alla piattaforma che li può usare per le autenticazioni TLS.
Autorizzazioni
certificateProvider
Disponibilità
Utilizzo
L'utilizzo tipico di questa API per esporre i certificati client a ChromeOS segue questi passaggi:
- L'estensione viene registrata per gli eventi onCertificatesUpdateRequested e onSignatureRequested.
- L'estensione chiama setCertificates per fornire l'elenco iniziale di certificati dopo l'inizializzazione.
- L'estensione monitora le modifiche nell'elenco dei certificati disponibili e chiama setCertificates per notificare al browser ogni modifica di questo tipo.
- Durante un handshake TLS, il browser riceve una richiesta di certificato client. Con un evento onCertificatesUpdateRequested, il browser chiede all'estensione di segnalare tutti i certificati che fornisce attualmente.
- L'estensione genera report con i certificati attualmente disponibili, utilizzando il metodo setCertificates.
- Il browser associa tutti i certificati disponibili alla richiesta di certificato client dall'host remoto. Le corrispondenze vengono presentate all'utente in una finestra di dialogo di selezione.
- L'utente può selezionare un certificato e quindi approvare o interrompere l'autenticazione.
- Se l'utente interrompe l'autenticazione o se non esistono certificati corrispondenti alla richiesta, l'autenticazione client TLS viene interrotta.
- Altrimenti, se l'utente approva l'autenticazione con un certificato fornito da questa estensione, il browser richiede all'estensione di firmare i dati per continuare l'handshake TLS. La richiesta viene inviata come evento onSignatureRequested.
- Questo evento contiene dati di input, dichiara quale algoritmo deve essere utilizzato per generare la firma e fa riferimento a uno dei certificati segnalati da questa estensione. L'estensione deve creare una firma per i dati specificati utilizzando la chiave privata associata al certificato di riferimento. La creazione della firma potrebbe richiedere la presenza di un DigestInfo e il riempimento del risultato prima della firma effettiva.
- L'estensione restituisce la firma al browser utilizzando il metodo reportSignature. Se non è stato possibile calcolare la firma, il metodo deve essere chiamato senza firma.
- Se è stata fornita la firma, il browser completa l'handshake TLS.
La sequenza effettiva dei passaggi può essere diversa. Ad esempio, all'utente non verrà chiesto di selezionare un certificato se viene utilizzato il criterio aziendale per la selezione automatica di un certificato (vedi AutoSelectCertificateForUrls e Criteri di Chrome per gli utenti).
Nell'estensione, l'aspetto potrebbe essere simile al seguente 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);
Tipi
Algorithm
Tipi di algoritmi di firma crittografica supportati.
Enum
"RSASSA_PKCS1_v1_5_MD5_SHA1"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con l'hashing MD5-SHA-1. L'estensione non deve anteporre un prefisso DigestInfo, ma solo aggiungere una spaziatura interna PKCS#1. Questo algoritmo è deprecato e non verrà mai richiesto da Chrome a partire dalla versione 109.
"RSASSA_PKCS1_v1_5_SHA1"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con la funzione hash SHA-1.
"RSASSA_PKCS1_v1_5_SHA256"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con la funzione di hashing SHA-256.
"RSASSA_PKCS1_v1_5_SHA384"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con la funzione di hashing SHA-384.
"RSASSA_PKCS1_v1_5_SHA512"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con la funzione di hashing SHA-512.
"RSASSA_PSS_SHA256"
Specifica l'algoritmo di firma PSS RSASSA con la funzione di hashing SHA-256, la funzione di generazione della maschera MGF1 e il sale delle stesse dimensioni dell'hash.
"RSASSA_PSS_SHA384"
Specifica l'algoritmo di firma PSS RSASSA con la funzione di hashing SHA-384, la funzione di generazione della maschera MGF1 e il sale delle stesse dimensioni dell'hash.
"RSASSA_PSS_SHA512"
Specifica l'algoritmo di firma PSS RSASSA con la funzione di hashing SHA-512, la funzione di generazione della maschera MGF1 e il sale delle stesse dimensioni dell'hash.
CertificateInfo
Proprietà
-
certificato
ArrayBuffer
Deve essere la codifica DER di un certificato X.509. Al momento sono supportati solo i certificati di chiavi RSA.
-
supportedHashes
Hash[]
Deve essere impostato su tutti gli hash supportati per questo certificato. A questa estensione verranno richieste solo le firme dei digest calcolati con uno di questi algoritmi di hash. L'ordine deve essere decrescente in base alla preferenza di hash.
CertificatesUpdateRequest
Proprietà
-
certificatesRequestId
numero
Identificatore della richiesta da trasmettere a
setCertificates
.
ClientCertificateInfo
Proprietà
-
certificateChain
ArrayBuffer[]
L'array deve contenere la codifica DER del certificato client X.509 come primo elemento.
Deve includere esattamente un certificato.
-
supportedAlgorithms
Tutti gli algoritmi supportati per questo certificato. All'estensione verrà chiesto di fornire le firme solo utilizzando uno di questi algoritmi.
Error
Tipi di errori che l'estensione può segnalare.
Valore
"GENERAL_ERROR"
Hash
Deprecato. Sostituito da Algorithm
.
Enum
"MD5_SHA1"
Specifica gli algoritmi di hashing MD5 e SHA1.
"SHA1"
Specifica l'algoritmo di hashing SHA1.
"SHA256"
Specifica l'algoritmo di hashing SHA256.
"SHA384"
Specifica l'algoritmo di hashing SHA384.
"SHA512"
Specifica l'algoritmo di hashing SHA512.
PinRequestErrorType
I tipi di errori che possono essere presentati all'utente tramite la funzione requestPin.
Enum
"INVALID_PIN"
Specifica che il PIN non è valido.
"INVALID_PUK"
Specifica che il PUK non è valido.
"MAX_ATTEMPTS_EXCEEDED"
Specifica che è stato superato il numero massimo di tentativi.
"UNKNOWN_ERROR"
Specifica che l'errore non può essere rappresentato dai tipi precedenti.
PinRequestType
Il tipo di codice richiesto dall'estensione con la funzione requestPin.
Enum
"PIN"
Specifica che il codice richiesto è un PIN.
"PUK"
Specifica che il codice richiesto è un PUK.
PinResponseDetails
Proprietà
-
userInput
stringa facoltativo
Il codice fornito dall'utente. Vuota se l'utente ha chiuso la finestra di dialogo o si è verificato un altro errore.
ReportSignatureDetails
Proprietà
-
errore
facoltativo
Errore che si è verificato durante la generazione della firma, se presente.
-
signRequestId
numero
Identificatore della richiesta ricevuto tramite l'evento
onSignatureRequested
. -
firma
ArrayBuffer facoltativo
La firma, se generata correttamente.
RequestPinDetails
Proprietà
-
attemptsLeft
numero facoltativo
Il numero di tentativi rimanenti. Questo viene fornito in modo che qualsiasi UI possa presentare queste informazioni all'utente. Non è previsto che Chrome applichi questa impostazione, ma stopPinRequest deve essere chiamato dall'estensione con errorType = MAX_ATTEMPTS_EXCEEDED quando viene superato il numero di richieste PIN.
-
errorType
PinRequestErrorType facoltativo
Il modello di errore mostrato all'utente. Deve essere impostato se la richiesta precedente non è andata a buon fine, per informare l'utente del motivo dell'errore.
-
requestType
Facoltativo PinRequestType
Il tipo di codice richiesto. Il valore predefinito è PIN.
-
signRequestId
numero
L'ID fornito da Chrome in SignRequest.
SetCertificatesDetails
Proprietà
-
certificatesRequestId
numero facoltativo
Quando chiamato in risposta a
onCertificatesUpdateRequested
, deve contenere il valorecertificatesRequestId
ricevuto. In caso contrario, l'impostazione deve essere annullata. -
clientCertificates
Elenco dei certificati client attualmente disponibili.
-
errore
facoltativo
Errore che si è verificato durante l'estrazione degli eventuali certificati. Questo errore verrà mostrato all'utente quando opportuno.
SignatureRequest
Proprietà
-
algoritmo
Algoritmo di firma da utilizzare.
-
certificato
ArrayBuffer
La codifica DER di un certificato X.509. L'estensione deve firmare
input
con la chiave privata associata. -
input
ArrayBuffer
Dati da firmare. Tieni presente che i dati non sono sottoposti ad hashing.
-
signRequestId
numero
Identificatore della richiesta da trasmettere a
reportSignature
.
SignRequest
Proprietà
-
certificato
ArrayBuffer
La codifica DER di un certificato X.509. L'estensione deve firmare
digest
con la chiave privata associata. -
digest
ArrayBuffer
Il digest che deve essere firmato.
-
cancelletto
Fa riferimento all'algoritmo hash utilizzato per creare
digest
. -
signRequestId
numero
Chrome 57 e versioni successiveL'ID univoco che deve essere utilizzato dall'estensione se deve chiamare un metodo che lo richiede, ad esempio requestPin.
StopPinRequestDetails
Proprietà
-
errorType
PinRequestErrorType facoltativo
Il modello di errore. Se presente, viene mostrata all'utente. Destinato a contenere il motivo per l'interruzione del flusso se è stato causato da un errore, ad esempio MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
numero
L'ID fornito da Chrome in SignRequest.
Metodi
reportSignature()
chrome.certificateProvider.reportSignature(
details: ReportSignatureDetails,
callback?: function,
)
Deve essere chiamato in risposta a onSignatureRequested
.
L'estensione alla fine deve chiamare questa funzione per ogni evento onSignatureRequested
; l'implementazione dell'API smetterà di attendere questa chiamata dopo un po' di tempo e risponderà con un errore di timeout quando questa funzione viene richiamata.
Parametri
-
dettagli
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
requestPin()
chrome.certificateProvider.requestPin(
details: RequestPinDetails,
callback?: function,
)
Richiede il PIN all'utente. È consentita una sola richiesta in corso alla volta. Le richieste emesse mentre è in corso un altro flusso vengono rifiutate. È responsabilità dell'estensione riprovare più tardi se è in corso un altro flusso.
Parametri
-
dettagli
Contiene i dettagli sulla finestra di dialogo richiesta.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:(details?: PinResponseDetails) => void
-
dettagli
PinResponseDetails facoltativo
-
Ritorni
-
Promise<PinResponseDetails | undefined>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
setCertificates()
chrome.certificateProvider.setCertificates(
details: SetCertificatesDetails,
callback?: function,
)
Consente di impostare un elenco di certificati da utilizzare nel browser.
L'estensione deve chiamare questa funzione dopo l'inizializzazione e a ogni modifica nel set di certificati attualmente disponibili. L'estensione deve chiamare questa funzione anche in risposta a onCertificatesUpdateRequested
ogni volta che viene ricevuto questo evento.
Parametri
-
dettagli
I certificati da impostare. I certificati non validi verranno ignorati.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Interrompe la richiesta di PIN avviata dalla funzione requestPin
.
Parametri
-
dettagli
Contiene i dettagli sul motivo dell'interruzione del flusso di richiesta.
-
callback
funzione facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Ritorni
-
Promise<void>
Chrome 96 e versioni successiveLe promesse sono supportate solo per Manifest V3 e versioni successive; altre piattaforme devono utilizzare i callback.
Eventi
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Usa invece onCertificatesUpdateRequested
.
Questo evento si attiva ogni volta che il browser richiede l'elenco corrente di certificati forniti da questa estensione. L'estensione deve chiamare reportCallback
esattamente una volta con l'elenco corrente dei certificati.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(reportCallback: function) => void
-
reportCallback
funzione
Il parametro
reportCallback
ha il seguente aspetto:(certificates: CertificateInfo[], callback: function) => void
-
certificates
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
ArrayBuffer[]
-
-
-
onCertificatesUpdateRequested
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
callback: function,
)
Questo evento si attiva se i certificati impostati tramite setCertificates
non sono sufficienti o se il browser richiede informazioni aggiornate. L'estensione deve chiamare setCertificates
con l'elenco aggiornato dei certificati e il valore certificatesRequestId
ricevuto.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(request: CertificatesUpdateRequest) => void
-
richiesta
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
Questo evento si attiva ogni volta che il browser deve firmare un messaggio utilizzando un certificato fornito da questa estensione tramite setCertificates
.
L'estensione deve firmare i dati di input di request
utilizzando l'algoritmo e la chiave privata appropriati e restituirli chiamando reportSignature
con il signRequestId
ricevuto.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(request: SignatureRequest) => void
-
richiesta
-
onSignDigestRequested
chrome.certificateProvider.onSignDigestRequested.addListener(
callback: function,
)
Usa invece onSignatureRequested
.
Questo evento si attiva ogni volta che il browser deve firmare un messaggio utilizzando un certificato fornito da questa estensione in risposta a un evento onCertificatesRequested
. L'estensione deve firmare i dati in request
utilizzando l'algoritmo e la chiave privata appropriati e restituirli chiamando reportCallback
. reportCallback
deve essere chiamato esattamente una volta.
Parametri
-
callback
funzione
Il parametro
callback
ha il seguente aspetto:(request: SignRequest, reportCallback: function) => void
-
richiesta
-
reportCallback
funzione
Chrome 47 e versioni successiveIl parametro
reportCallback
ha il seguente aspetto:(signature?: ArrayBuffer) => void
-
firma
ArrayBuffer facoltativo
-
-