chrome.certificateProvider

Importante: questa API funziona solo su ChromeOS.

Descrizione

Utilizza questa API per esporre alla piattaforma i certificati che possono essere utilizzati 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 prevede i seguenti passaggi:

• L'estensione si registra per gli eventi onCertificatesUpdateRequested e onSignatureRequested.
• L'estensione chiama setCertificates per fornire l'elenco iniziale dei 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 attualmente forniti.
• L'estensione restituisce i certificati attualmente disponibili utilizzando il metodo setCertificates.
• Il browser abbina tutti i certificati disponibili alla richiesta di certificato client dell'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.

• Se l'utente interrompe l'autenticazione o nessun certificato corrisponde alla richiesta, l'autenticazione client TLS viene interrotta.
• In caso contrario, se l'utente approva l'autenticazione con un certificato fornito da questa estensione, il browser chiede all'estensione di firmare i dati per continuare l'handshake TLS. La richiesta viene inviata come evento onSignatureRequested.
• Questo evento contiene i dati di input, dichiara l'algoritmo da utilizzare 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 a cui si fa riferimento. La creazione della firma potrebbe richiedere l'anteposizione 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 la firma è stata fornita, 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, può avere un aspetto simile allo snippet seguente:

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 di crittografia 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 il padding 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 RSASSA PSS 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 RSASSA PSS con la funzione di hashing SHA-384, la funzione di generazione della maschera MGF1 e il salt delle stesse dimensioni dell'hash.

"RSASSA_PSS_SHA512"
Specifica l'algoritmo di firma RSASSA PSS con la funzione di hashing SHA-512, la funzione di generazione della maschera MGF1 e il valore salt 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 delle 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 calcolati con uno di questi algoritmi di hashing. Devono essere in ordine decrescente di preferenza di hash.

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 esattamente un certificato.

• supportedAlgorithms

  Algorithm[]

  Tutti gli algoritmi supportati per questo certificato. All'estensione verranno chieste firme che utilizzano 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 il numero massimo di tentativi è stato superato.

"UNKNOWN_ERROR"
Specifica che l'errore non può essere rappresentato dai tipi precedenti.

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 facoltativa

  Il codice fornito dall'utente. Vuoto 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

  Errore, se presente, che si è verificato durante la generazione della firma.

• 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

  number facoltativo

  Il numero di tentativi rimanenti. Questo viene fornito in modo che qualsiasi interfaccia utente possa presentare queste informazioni all'utente. Chrome non dovrebbe applicare questa limitazione, ma l'estensione deve chiamare stopPinRequest con errorType = MAX_ATTEMPTS_EXCEEDED quando viene superato il numero di richieste di PIN.

• errorType

  PinRequestErrorType facoltativo

  Il modello di errore visualizzato all'utente. Questo valore deve essere impostato se la richiesta precedente non è andata a buon fine per notificare all'utente il motivo dell'errore.

• requestType

  PinRequestType facoltativo

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

• signRequestId

  numero

  L'ID assegnato da Chrome in SignRequest.

SetCertificatesDetails

Chrome 86 e versioni successive

Proprietà

• certificatesRequestId

  number facoltativo

  Se viene chiamato in risposta a onCertificatesUpdateRequested, deve contenere il valore certificatesRequestId ricevuto. In caso contrario, non deve essere impostato.

• clientCertificates

  ClientCertificateInfo[]

  Elenco dei certificati client attualmente disponibili.

• errore

  "GENERAL_ERROR"
   facoltativo

  Errore eventualmente verificato durante l'estrazione dei certificati. Questo errore verrà mostrato all'utente, se 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

  Si riferisce all'algoritmo di hash utilizzato per creare digest.

• signRequestId

  numero

  Chrome 57 e versioni successive

  L'ID univoco da utilizzare dall'estensione se deve chiamare un metodo che lo richiede, ad esempio requestPin.

StopPinRequestDetails

Chrome 57 e versioni successive

Proprietà

• errorType

  PinRequestErrorType facoltativo

  Il modello di errore. Se presente, viene mostrato all'utente. Deve contenere il motivo dell'interruzione del flusso se è stato causato da un errore, ad esempio MAX_ATTEMPTS_EXCEEDED.

• signRequestId

  numero

  L'ID assegnato da Chrome in SignRequest.

Metodi

reportSignature()

Promessa Chrome 86 e versioni successive

chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Deve essere chiamato in risposta a onSignatureRequested.

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 viene chiamata questa funzione.

Parametri

• dettagli

  ReportSignatureDetails

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<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()

Promessa Chrome 57 e versioni successive

chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Richiede il PIN all'utente. È consentita una sola richiesta in corso alla volta. Le richieste inviate mentre è in corso un altro flusso vengono rifiutate. È responsabilità dell'estensione riprovare più tardi se è in corso un altro flusso.

Parametri

• dettagli

  RequestPinDetails

  Contiene i dettagli della finestra di dialogo richiesta.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  (details?: PinResponseDetails) => void

  • dettagli

    PinResponseDetails facoltativo

Resi

• Promise<PinResponseDetails | undefined>

  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()

Promessa Chrome 86 e versioni successive

chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Imposta un elenco di certificati da utilizzare nel browser.

L'estensione deve chiamare questa funzione dopo l'inizializzazione e a ogni modifica dell'insieme di certificati attualmente disponibili. L'estensione deve chiamare questa funzione anche in risposta a onCertificatesUpdateRequested ogni volta che viene ricevuto questo evento.

Parametri

• dettagli

  SetCertificatesDetails

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

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<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()

Promessa Chrome 57 e versioni successive

chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Interrompe la richiesta di PIN avviata dalla funzione requestPin.

Parametri

• dettagli

  StopPinRequestDetails

  Contiene i dettagli del motivo dell'interruzione del flusso di richieste.

• callback

  function facoltativa

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<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 &leq; MV2 Ritirato da Chrome 86

chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Utilizza invece onCertificatesUpdateRequested.

Questo evento viene attivato ogni volta che il browser richiede l'elenco corrente dei 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

    • 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

• callback

  funzione

  Il parametro callback ha il seguente aspetto:

  (request: CertificatesUpdateRequest) => void

  • richiesta

    CertificatesUpdateRequest

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

    SignatureRequest

onSignDigestRequested

&leq; MV2 Ritirato da Chrome 86

chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Utilizza 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