chrome.certificateProvider

Descrizione

Utilizza questa API per esporre i certificati alla piattaforma che possono utilizzarli per le autenticazioni TLS.

Autorizzazioni

certificateProvider

Disponibilità

Chrome 46 e versioni successive Solo ChromeOS

Utilizzo

L'utilizzo tipico di questa API per esporre i certificati client a ChromeOS segue questi passaggi:

  • L'estensione si registra 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.
  • 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 segnala 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 l'autenticazione o interromperla.

Finestra di dialogo per la selezione del certificato

  • Se l'utente interrompe l'autenticazione o se nessun certificato corrisponde alla richiesta, l'autenticazione del client TLS viene interrotta.
  • In caso contrario, 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. Per creare la firma potrebbe essere necessario anteporre un DigestInfo e aggiungere una spaziatura interna al risultato prima della firma effettiva.
  • L'estensione invia 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 selezionarne automaticamente (vedi AutoSelectCertificateForUrls e Criteri di Chrome per gli utenti).

Nell'estensione, questo può avere un aspetto 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

Chrome 86 e versioni successive .

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 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 hash SHA-256.

"RSASSA_PKCS1_v1_5_SHA384"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con la funzione di hash SHA-384.

"RSASSA_PKCS1_v1_5_SHA512"
Specifica l'algoritmo di firma RSASSA PKCS#1 v1.5 con la funzione di hash SHA-512.

"RSASSA_PSS_SHA256"
Specifica l'algoritmo di firma PSS RSASSA con la funzione di hash SHA-256, la funzione di generazione della maschera MGF1 e il sale della stessa dimensione dell'hash.

"RSASSA_PSS_SHA384"
Specifica l'algoritmo di firma PSS RSASSA con la funzione di hash SHA-384, la funzione di generazione della maschera MGF1 e il sale della stessa dimensione dell'hash.

"RSASSA_PSS_SHA512"
Specifica l'algoritmo di firma PSS RSASSA con la funzione di hash SHA-512, la funzione di generazione della maschera MGF1 e il sale della stessa dimensione dell'hash.

CertificateInfo

Proprietà

  • certificato

    ArrayBuffer

    Deve essere la codifica DER di un certificato X.509. Al momento sono supportati solo i certificati per le chiavi RSA.

  • supportedHashes

    Hash[]

    Deve essere impostato su tutti gli hash supportati per questo certificato. A questa estensione verranno chieste solo le firme dei digest calcolate con uno di questi algoritmi hash. Questa preferenza deve essere ordinata in ordine decrescente.

CertificatesUpdateRequest

Chrome 86 e versioni successive .

Proprietà

  • certificatesRequestId

    numero

    Identificatore della richiesta da passare a setCertificates.

ClientCertificateInfo

Chrome 86 e versioni successive .

Proprietà

  • certificateChain

    ArrayBuffer[]

    L'array deve contenere la codifica DER del certificato client X.509 come primo elemento.

    Deve includere un solo certificato.

  • supportedAlgorithms

    Algoritmo[]

    Tutti gli algoritmi sono supportati per questo certificato. All'estensione verranno richieste le firme soltanto utilizzando uno di questi algoritmi.

Error

Chrome 86 e versioni successive .

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

Chrome 57 e versioni successive .

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 indicati sopra.

PinRequestType

Chrome 57 e versioni successive .

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

Chrome 57 e versioni successive .

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

Chrome 86 e versioni successive .

Proprietà

  • errore

    "GENERAL_ERROR"
     facoltativo

    Si è verificato un errore 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

Chrome 57 e versioni successive .

Proprietà

  • attemptsLeft

    numero facoltativo

    Il numero di tentativi rimanenti. Viene fornito in modo che qualsiasi UI possa presentare queste informazioni all'utente. Non è previsto che Chrome esegua l'applicazione forzata di questa funzione. La chiamata invece stopPinRequest deve essere chiamata dall'estensione con errorType = MAX_ATTEMPTS_EXCEEDED quando viene superato il numero di richieste di PIN.

  • errorType

    PinRequestErrorType optional

    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

    PinRequestType facoltativo

    Il tipo di codice richiesto. Il valore predefinito è PIN.

  • signRequestId

    numero

    L'ID fornito da Chrome in SignRequest.

SetCertificatesDetails

Chrome 86 e versioni successive .

Proprietà

  • certificatesRequestId

    numero facoltativo

    Quando viene chiamato in risposta a onCertificatesUpdateRequested, deve contenere il valore certificatesRequestId ricevuto. In caso contrario, deve essere annullata.

  • clientCertificates

    ClientCertificateInfo[]

    Elenco dei certificati client attualmente disponibili.

  • errore

    "GENERAL_ERROR"
     facoltativo

    Errore che si è verificato durante l'estrazione degli eventuali certificati. Questo errore verrà mostrato all'utente quando opportuno.

SignatureRequest

Chrome 86 e versioni successive .

Proprietà

  • algoritmo

    Algoritmo

    Algoritmo di firma da utilizzare.

  • certificato

    ArrayBuffer

    La codifica DER di un certificato X.509. L'estensione deve firmare input utilizzando 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 passare a reportSignature.

SignRequest

Proprietà

  • certificato

    ArrayBuffer

    La codifica DER di un certificato X.509. L'estensione deve firmare digest utilizzando la chiave privata associata.

  • digest

    ArrayBuffer

    Il digest che deve essere firmato.

  • hash

    Hash

    Fa riferimento all'algoritmo hash utilizzato per creare digest.

  • signRequestId

    numero

    Chrome 57 e versioni successive .

    L'ID univoco che deve essere utilizzato dall'estensione nel caso in cui questa debba chiamare un metodo che lo richiede, ad esempio requestPin.

StopPinRequestDetails

Chrome 57 e versioni successive .

Proprietà

  • errorType

    PinRequestErrorType optional

    Il modello di errore. Se presente, viene mostrato all'utente. Destinato a contenere il motivo per l'interruzione del flusso se è stato causato da un errore, ad es. MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    numero

    L'ID fornito da Chrome in SignRequest.

Metodi

reportSignature()

Promesso Chrome 86 e versioni successive 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Deve essere chiamato in risposta a onSignatureRequested.

Alla fine, l'estensione 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 chiamata.

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

requestPin()

Promesso Chrome 57 e versioni successive 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Consente di richiedere 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 in un secondo momento se è in corso un altro flusso.

Parametri

Resi

  • Promise&lt;PinResponseDetails | non definito>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

setCertificates()

Promesso Chrome 86 e versioni successive 
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 anche chiamare questa funzione in risposta a onCertificatesUpdateRequested ogni volta che viene ricevuto questo evento.

Parametri

  • I certificati da impostare. I certificati non validi verranno ignorati.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

stopPinRequest()

Promesso Chrome 57 e versioni successive 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Arresta la richiesta di PIN avviata dalla funzione requestPin.

Parametri

  • Contiene i dettagli sul motivo per l'interruzione del flusso di richiesta.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promesso<void>

    Chrome 96 e versioni successive .

    Le promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.

Eventi

onCertificatesRequested

Chrome 47 e versioni successive &amp;leq; MV2 Ritirato da Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Usa invece onCertificatesUpdateRequested.

Questo evento viene attivato 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 di certificati corrente.

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

      • certificati

        CertificateInfo[]

      • callback

        funzione

        Il parametro callback ha il seguente aspetto: 

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 e versioni successive .
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Questo evento viene attivato 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 certificatesRequestId ricevuto.

Parametri

onSignatureRequested

Chrome 86 e versioni successive .
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Questo evento viene attivato 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 da request utilizzando l'algoritmo e la chiave privata appropriati e restituirli chiamando reportSignature con il signRequestId ricevuto.

Parametri

onSignDigestRequested

&amp;leq; MV2 Ritirato da Chrome 86
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Usa invece onSignatureRequested.

Questo evento viene attivato 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

      SignRequest

    • reportCallback

      funzione

      Chrome 47 e versioni successive .

      Il parametro reportCallback ha il seguente aspetto: 

      (signature?: ArrayBuffer) => void

      • firma

        ArrayBuffer facoltativo