browser.certificateProvider

Beschrijving

Gebruik deze API om certificaten beschikbaar te maken voor het platform, dat deze certificaten kan gebruiken voor TLS-verificaties.

Rechten

certificateProvider

Beschikbaarheid

Chrome 46+ browser.* sinds Chrome 148 Alleen ChromeOS

Concepten en gebruik

Het gebruikelijke gebruik van deze API om clientcertificaten beschikbaar te maken voor ChromeOS bestaat uit de volgende stappen:

  • De extensie registreert zich voor de gebeurtenissen onCertificatesUpdateRequested en onSignatureRequested.
  • De extensie roept setCertificates() aan om de eerste lijst met certificaten te leveren na de initialisatie.
  • De extensie houdt de wijzigingen in de lijst met beschikbare certificaten bij en roept setCertificates() aan om de browser op de hoogte te stellen van elke wijziging.
  • Tijdens een TLS-handshake krijgt de browser een verzoek voor een clientcertificaat. Bij een onCertificatesUpdateRequested-gebeurtenis vraagt de browser de extensie om alle certificaten te melden die deze op dat moment biedt.
  • De extensie meldt de momenteel beschikbare certificaten met de methode setCertificates().
  • De browser vergelijkt alle beschikbare certificaten met het verzoek om een clientcertificaat van de externe host. De overeenkomsten worden aan de gebruiker getoond in een selectiedialoogvenster.
  • De gebruiker kan een certificaat selecteren en daarmee de verificatie goedkeuren of afbreken.
Dialoogvenster voor certificaatselectie
Dialoogvenster voor certificaatselectie.
  • Als de gebruiker de verificatie afbreekt of als er geen certificaat overeenkomt met het verzoek, wordt de TLS-clientverificatie afgebroken.
  • Als de gebruiker de verificatie goedkeurt met een certificaat dat door deze extensie wordt geleverd, vraagt de browser de extensie om de gegevens te ondertekenen om de TLS-handshake voort te zetten. Het verzoek wordt gestuurd als een onSignatureRequested-gebeurtenis.
  • Deze gebeurtenis bevat invoergegevens, geeft aan welk algoritme moet worden gebruikt om de handtekening te genereren en verwijst naar een van de certificaten die door deze extensie zijn gerapporteerd. De extensie moet een handtekening voor de gegeven gegevens maken met de privésleutel die is gekoppeld aan het certificaat waarnaar wordt verwezen. Voor het maken van de handtekening moet je misschien een DigestInfo toevoegen en het resultaat opvullen voordat je de handtekening zet.
  • De extensie stuurt de handtekening terug naar de browser met de methode reportSignature(). Als de handtekening niet kan worden berekend, moet de methode zonder handtekening worden aangeroepen.
  • Als de handtekening is verstrekt, rondt de browser de TLS-handshake af.

De daadwerkelijke volgorde van de stappen kan anders zijn. De gebruiker wordt bijvoorbeeld niet gevraagd een certificaat te selecteren als het bedrijfsbeleid om automatisch een certificaat te selecteren wordt gebruikt (zie AutoSelectCertificateForUrls en Chrome-beleid voor gebruikers).

In de extensie kan dit er ongeveer zo uitzien als het volgende fragment:

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() {
  browser.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.
  browser.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.
    browser.certificateProvider.reportSignature({
      signRequestId: request.signRequestId,
      error: 'GENERAL_ERROR'
    });
    return;
  }

  const signature = signUnhashedData(key, request.input, request.algorithm);
  browser.certificateProvider.reportSignature({
    signRequestId: request.signRequestId,
    signature: signature
  });
}

browser.certificateProvider.onCertificatesUpdateRequested.addListener(
    handleCertificatesUpdateRequest);
browser.certificateProvider.onSignatureRequested.addListener(
    handleSignatureRequest);

Typen

Algorithm

Chrome 86+ browser.* sinds Chrome 148

Typen ondersteunde cryptografische handtekeningalgoritmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Hiermee wordt het RSASSA PKCS#1 v1.5-handtekeningalgoritme met de MD5-SHA-1-hashing aangegeven. De extensie mag geen DigestInfo-prefix toevoegen, maar alleen PKCS#1-opvulling. Dit algoritme is beëindigd en wordt vanaf versie 109 nooit meer aangevraagd door Chrome.

"RSASSA_PKCS1_v1_5_SHA1"
Hiermee wordt het RSASSA PKCS#1 v1.5-handtekeningalgoritme met de SHA-1-hashfunctie aangegeven.

"RSASSA_PKCS1_v1_5_SHA256"
Hiermee wordt het RSASSA PKCS#1 v1.5-handtekeningalgoritme met de SHA-256-hashfunctie aangegeven.

"RSASSA_PKCS1_v1_5_SHA384"
Hiermee wordt het RSASSA PKCS#1 v1.5-handtekeningalgoritme met de SHA-384-hashfunctie gespecificeerd.

"RSASSA_PKCS1_v1_5_SHA512"
Hiermee wordt het RSASSA PKCS#1 v1.5-handtekeningalgoritme met de SHA-512-hashfunctie gespecificeerd.

"RSASSA_PSS_SHA256"
Hiermee wordt het RSASSA PSS-handtekeningalgoritme aangegeven met de SHA-256-hashfunctie, de MGF1-maskergeneratiefunctie en de salt van dezelfde grootte als de hash.

"RSASSA_PSS_SHA384"
Hiermee wordt het RSASSA PSS-handtekeningalgoritme gespecificeerd met de SHA-384-hashfunctie, de MGF1-maskergeneratiefunctie en de salt van dezelfde grootte als de hash.

"RSASSA_PSS_SHA512"
Hiermee wordt het RSASSA PSS-handtekeningalgoritme gespecificeerd met de SHA-512-hash-functie, de MGF1-maskergeneratiefunctie en de salt van dezelfde grootte als de hash.

CertificateInfo

Eigenschappen

  • certificaat

    ArrayBuffer

    Moet de DER-codering van een X.509-certificaat zijn. Op dit moment worden alleen certificaten van RSA-sleutels ondersteund.

  • supportedHashes

    Hash[]

    Moet worden ingesteld op alle hashes die worden ondersteund voor dit certificaat. Deze extensie wordt alleen gevraagd om handtekeningen van overzichten die zijn berekend met een van deze hash-algoritmen. Dit moet in volgorde van afnemende hash-voorkeur zijn.

CertificatesUpdateRequest

Chrome 86+ browser.* sinds Chrome 148

Eigenschappen

  • certificatesRequestId

    getal

    ID van het verzoek dat moet worden doorgegeven aan setCertificates.

ClientCertificateInfo

Chrome 86+ browser.* sinds Chrome 148

Eigenschappen

  • certificateChain

    ArrayBuffer[]

    De array moet de DER-codering van het X.509-clientcertificaat als eerste element bevatten.

    Dit moet precies één certificaat bevatten.

  • supportedAlgorithms

    Algoritme[]

    Alle algoritmen die worden ondersteund voor dit certificaat. De extensie wordt alleen gevraagd om handtekeningen met een van deze algoritmen.

Error

Chrome 86+ browser.* sinds Chrome 148

Typen fouten die de extensie kan melden.

Waarde

"GENERAL_ERROR"

Hash

Beëindigd. Vervangen door Algorithm.

Enum

"MD5_SHA1"
Hiermee worden de MD5- en SHA1-hashing-algoritmen aangegeven.

SHA1
Hiermee wordt het SHA1-hashingalgoritme aangegeven.

"SHA256"
Hiermee wordt het SHA256-hashingalgoritme aangegeven.

SHA384
Hiermee wordt het SHA384-hash-algoritme aangegeven.

"SHA512"
Hiermee wordt het SHA512-hashingalgoritme aangegeven.

PinRequestErrorType

Chrome 57+ browser.* sinds Chrome 148

De typen fouten die aan de gebruiker kunnen worden getoond via de functie requestPin.

Enum

INVALID_PIN
Geeft aan dat de pincode ongeldig is.

INVALID_PUK
Geeft aan dat de pukcode ongeldig is.

MAX_ATTEMPTS_EXCEEDED
Geeft aan dat het maximale aantal pogingen is overschreden.

UNKNOWN_ERROR
Geeft aan dat de fout niet kan worden weergegeven door de bovenstaande typen.

PinRequestType

Chrome 57+ browser.* sinds Chrome 148

Het type code dat wordt aangevraagd door de extensie met de functie requestPin.

Enum

"PIN"
Geeft aan dat de gevraagde code een pincode is.

PUK
Geeft aan dat de gevraagde code een pukcode is.

PinResponseDetails

Chrome 57+ browser.* sinds Chrome 148

Eigenschappen

  • userInput

    tekenreeks optioneel

    De code die de gebruiker heeft ingevoerd. Leeg als de gebruiker het dialoogvenster heeft gesloten of als er een andere fout is opgetreden.

ReportSignatureDetails

Chrome 86+ browser.* sinds Chrome 148

Eigenschappen

  • fout

    "GENERAL_ERROR"
     optioneel

    De fout die is opgetreden tijdens het genereren van de handtekening, indien van toepassing.

  • signRequestId

    getal

    De verzoek-ID die is ontvangen via de gebeurtenis onSignatureRequested.

  • handtekening

    ArrayBuffer optioneel

    De handtekening, als deze is gegenereerd.

RequestPinDetails

Chrome 57+ browser.* sinds Chrome 148

Eigenschappen

  • attemptsLeft

    number optioneel

    Het aantal resterende pogingen. Deze informatie wordt verstrekt zodat elke UI deze informatie aan de gebruiker kan presenteren. Chrome dwingt dit niet af. In plaats daarvan moet stopPinRequest worden aangeroepen door de extensie met errorType = MAX_ATTEMPTS_EXCEEDED als het aantal pincodeverzoeken wordt overschreden.

  • errorType

    PinRequestErrorType optioneel

    De fouttemplate die aan de gebruiker wordt getoond. Dit moet worden ingesteld als het vorige verzoek is mislukt, om de gebruiker op de hoogte te stellen van de reden van de fout.

  • requestType

    PinRequestType optioneel

    Het type code dat is aangevraagd. De standaard is pincode.

  • signRequestId

    getal

    De ID die Chrome geeft in SignRequest.

SetCertificatesDetails

Chrome 86+ browser.* sinds Chrome 148

Eigenschappen

  • certificatesRequestId

    number optioneel

    Als deze wordt aangeroepen als reactie op onCertificatesUpdateRequested, moet deze de ontvangen waarde certificatesRequestId bevatten. Anders moet deze niet worden ingesteld.

  • clientCertificates

    ClientCertificateInfo[]

    Lijst met op dit moment beschikbare clientcertificaten.

  • fout

    "GENERAL_ERROR"
     optioneel

    De fout die is opgetreden tijdens het uitpakken van de certificaten, indien van toepassing. Deze fout wordt aan de gebruiker getoond wanneer dat nodig is.

SignatureRequest

Chrome 86+ browser.* sinds Chrome 148

Eigenschappen

  • algoritme

    Algoritme

    Het algoritme voor de handtekening dat moet worden gebruikt.

  • certificaat

    ArrayBuffer

    De DER-codering van een X.509-certificaat. De extensie moet input ondertekenen met de bijbehorende privésleutel.

  • invoer

    ArrayBuffer

    Gegevens die moeten worden ondertekend. De gegevens zijn niet gehasht.

  • signRequestId

    getal

    ID van het verzoek dat moet worden doorgegeven aan reportSignature.

SignRequest

Eigenschappen

  • certificaat

    ArrayBuffer

    De DER-codering van een X.509-certificaat. De extensie moet digest ondertekenen met de bijbehorende privésleutel.

  • digest

    ArrayBuffer

    De digest die moet worden ondertekend.

  • hash

    Hash

    Verwijst naar het hash-algoritme dat is gebruikt om digest te maken.

  • signRequestId

    getal

    Chrome 57+ browser.* sinds Chrome 148

    De unieke ID die de extensie moet gebruiken als deze een methode moet aanroepen waarvoor de ID is vereist, bijvoorbeeld requestPin.

StopPinRequestDetails

Chrome 57+ browser.* sinds Chrome 148

Eigenschappen

  • errorType

    PinRequestErrorType optioneel

    De fouttemplate. Als deze aanwezig is, wordt deze aan de gebruiker getoond. Bedoeld om de reden te bevatten waarom het proces is gestopt als dit is veroorzaakt door een fout, bijvoorbeeld MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    getal

    De ID die Chrome geeft in SignRequest.

Methoden

reportSignature()

Chrome 86+ browser.* sinds Chrome 148 
browser.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

Moet worden aangeroepen als reactie op onSignatureRequested.

De extensie moet deze functie uiteindelijk aanroepen voor elke onSignatureRequested-gebeurtenis. De API-implementatie wacht na enige tijd niet meer op deze aanroep en reageert met een time-outfout als deze functie wordt aangeroepen.

Parameters

Retourzendingen

  • Promise<void>

    Chrome 96+ browser.* sinds Chrome 148

requestPin()

Chrome 57+ browser.* sinds Chrome 148 
browser.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

Vraagt de pincode aan de gebruiker. Er is maar één lopend verzoek tegelijk toegestaan. Verzoeken die worden ingediend terwijl een ander proces loopt, worden geweigerd. Het is de verantwoordelijkheid van de extensie om het later opnieuw te proberen als er een ander proces wordt uitgevoerd.

Parameters

Retourzendingen

  • Promise<PinResponseDetails | undefined>

    Chrome 96+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt opgelost als de pincode door de gebruiker wordt verstrekt. Wordt afgewezen met een fout als het dialoogvensterverzoek niet is afgerond (bijvoorbeeld als het dialoogvenster is geannuleerd door de gebruiker of niet mocht worden getoond).

setCertificates()

Chrome 86+ browser.* sinds Chrome 148 
browser.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

Hiermee stel je een lijst met certificaten in die je in de browser wilt gebruiken.

De extensie moet deze functie aanroepen na de initialisatie en bij elke wijziging in de set van momenteel beschikbare certificaten. De extensie moet deze functie ook aanroepen als reactie op onCertificatesUpdateRequested elke keer dat deze gebeurtenis wordt ontvangen.

Parameters

  • De certificaten die moeten worden ingesteld. Ongeldige certificaten worden genegeerd.

Retourzendingen

  • Promise<void>

    Chrome 96+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt opgelost na voltooiing.

stopPinRequest()

Chrome 57+ browser.* sinds Chrome 148 
browser.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

Stopt het pincodeverzoek dat is gestart door de functie requestPin.

Parameters

Retourzendingen

  • Promise<void>

    Chrome 96+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt opgelost als het verzoek om het pincodedialoogvenster te sluiten is afgerond.

Evenementen

onCertificatesUpdateRequested

Chrome 86+ browser.* sinds Chrome 148 
browser.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Deze gebeurtenis wordt geactiveerd als de certificaten die zijn ingesteld via setCertificates onvoldoende zijn of als de browser om geüpdatete informatie vraagt. De extensie moet setCertificates aanroepen met de geüpdatete lijst met certificaten en de ontvangen certificatesRequestId.

Parameters

onSignatureRequested

Chrome 86+ browser.* sinds Chrome 148 
browser.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Deze gebeurtenis wordt elke keer geactiveerd als de browser een bericht moet ondertekenen met een certificaat dat door deze extensie wordt geleverd via setCertificates.

De extensie moet de invoergegevens van request ondertekenen met het juiste algoritme en de privésleutel en deze retourneren door reportSignature aan te roepen met de ontvangen signRequestId.

Parameters