chrome.certificateProvider

Beschrijving

Gebruik deze API om certificaten beschikbaar te stellen aan het platform, dat deze certificaten vervolgens kan gebruiken voor TLS-authenticatie.

Toestemmingen

certificateProvider

Beschikbaarheid

Chrome 46+ alleen voor ChromeOS

Concepten en gebruik

Het gebruikelijke gebruik van deze API om clientcertificaten beschikbaar te stellen aan ChromeOS verloopt volgens deze stappen:

  • De extensie registreert zich voor de gebeurtenissen onCertificatesUpdateRequested en onSignatureRequested .
  • De extensie roept setCertificates() aan om de initiële lijst met certificaten te verstrekken na de initialisatie.
  • De extensie controleert de wijzigingen in de lijst met beschikbare certificaten en roept setCertificates() aan om de browser op de hoogte te stellen van elke dergelijke wijziging.
  • Tijdens een TLS-handshake ontvangt de browser een certificaatverzoek van de client. Met een onCertificatesUpdateRequested -gebeurtenis vraagt ​​de browser de extensie om alle certificaten te rapporteren die deze momenteel beschikbaar stelt.
  • De extensie geeft de momenteel beschikbare certificaten terug via de methode setCertificates() .
  • De browser vergelijkt alle beschikbare certificaten met het certificaatverzoek van de client vanaf de externe host. De overeenkomsten worden aan de gebruiker getoond in een selectiedialoogvenster.
  • De gebruiker kan een certificaat selecteren en daarmee de authenticatie goedkeuren of annuleren.
Dialoogvenster voor certificaatselectie
Dialoogvenster voor certificaatselectie.
  • Als de gebruiker de authenticatie afbreekt of als er geen certificaat is gevonden dat overeenkomt met het verzoek, wordt de TLS-clientauthenticatie afgebroken.
  • Als de gebruiker de authenticatie met een certificaat van deze extensie goedkeurt, vraagt ​​de browser de extensie om de gegevens te ondertekenen om de TLS-handshake voort te zetten. Dit verzoek wordt verzonden 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 genereren voor de gegeven gegevens met behulp van de privésleutel die is gekoppeld aan het betreffende certificaat. Het genereren van de handtekening kan vereisen dat een DigestInfo wordt toegevoegd en dat het resultaat wordt opgevuld voordat de daadwerkelijke ondertekening plaatsvindt.
  • De extensie stuurt de handtekening terug naar de browser met behulp van de methode reportSignature() . Als de handtekening niet kon worden berekend, moet de methode zonder handtekening worden aangeroepen.
  • Als de handtekening is verstrekt, voltooit de browser de TLS-handshake.

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

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

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

Soorten

Algorithm

Chrome 86+

Ondersteunde typen cryptografische handtekeningalgoritmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Specificeert het RSASSA PKCS#1 v1.5-handtekeningalgoritme met MD5-SHA-1-hashing. De extensie mag geen DigestInfo-prefix toevoegen, maar alleen PKCS#1-padding. Dit algoritme is verouderd en zal vanaf versie 109 niet meer door Chrome worden opgevraagd.

"RSASSA_PKCS1_v1_5_SHA1"
Specificeert het RSASSA PKCS#1 v1.5-ondertekeningsalgoritme met de SHA-1-hashfunctie.

"RSASSA_PKCS1_v1_5_SHA256"
Specificeert het RSASSA PKCS#1 v1.5-ondertekeningsalgoritme met de SHA-256-hashfunctie.

"RSASSA_PKCS1_v1_5_SHA384"
Specificeert het RSASSA PKCS#1 v1.5-ondertekeningsalgoritme met de SHA-384-hashfunctie.

"RSASSA_PKCS1_v1_5_SHA512"
Specificeert het RSASSA PKCS#1 v1.5-ondertekeningsalgoritme met de SHA-512-hashfunctie.

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

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

"RSASSA_PSS_SHA512"
Specificeert het RSASSA PSS-handtekeningalgoritme met de SHA-512-hashfunctie, de MGF1-maskergeneratiefunctie en een salt van dezelfde grootte als de hash.

CertificateInfo

Eigenschappen

  • certificaat

    ArrayBuffer

    Het certificaat moet de DER-codering van een X.509-certificaat hebben. Momenteel worden alleen certificaten met RSA-sleutels ondersteund.

  • ondersteunde hashes

    Hash []

    Moet worden ingesteld op alle hashfuncties die voor dit certificaat worden ondersteund. Deze extensie zal alleen om handtekeningen vragen van hashwaarden die zijn berekend met een van deze hash-algoritmen. Deze moeten in volgorde van afnemende voorkeur voor hashfuncties worden opgegeven.

CertificatesUpdateRequest

Chrome 86+

Eigenschappen

  • certificatenAanvraagID

    nummer

    De aanvraag-ID die moet worden doorgegeven aan setCertificates .

ClientCertificateInfo

Chrome 86+

Eigenschappen

  • certificaatketen

    ArrayBuffer[]

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

    Dit moet precies één certificaat bevatten.

  • ondersteunde algoritmen

    Algoritme []

    Alle algoritmen worden ondersteund voor dit certificaat. De extensie zal alleen om handtekeningen vragen die gebruikmaken van een van deze algoritmen.

Error

Chrome 86+

Soorten fouten die de extensie kan rapporteren.

Waarde

"ALGEMENE_FOUT"

Hash

Verouderd. Vervangen door Algorithm .

Enum

"MD5_SHA1"
Specificeert de hash-algoritmen MD5 en SHA1.

"SHA1"
Specificeert het SHA1-hashalgoritme.

"SHA256"
Specificeert het SHA256-hashalgoritme.

"SHA384"
Specificeert het SHA384-hashalgoritme.

"SHA512"
Specificeert het SHA512-hashalgoritme.

PinRequestErrorType

Chrome 57+

De soorten foutmeldingen die aan de gebruiker kunnen worden getoond via de requestPin-functie.

Enum

"ONGELDIGE_PIN"
Geeft aan dat de pincode ongeldig is.

"ONGELDIGE_PUK"
Geeft aan dat de PUK ongeldig is.

"MAX_POGINGEN_OVERSCHREDEN"
Geeft aan dat het maximale aantal pogingen is overschreden.

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

PinRequestType

Chrome 57+

Het type code dat wordt opgevraagd 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 PUK is.

PinResponseDetails

Chrome 57+

Eigenschappen

  • gebruikersinvoer

    string optioneel

    De code is door de gebruiker ingevoerd. Deze is leeg als de gebruiker het dialoogvenster heeft gesloten of als er een andere fout is opgetreden.

ReportSignatureDetails

Chrome 86+

Eigenschappen

  • fout

    "ALGEMENE_FOUT"
    optioneel

    Een eventuele fout die is opgetreden tijdens het genereren van de handtekening.

  • signRequestId

    nummer

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

  • handtekening

    ArrayBuffer optioneel

    De handtekening, indien succesvol gegenereerd.

RequestPinDetails

Chrome 57+

Eigenschappen

  • pogingenLinks

    nummer optioneel

    Het aantal resterende pogingen. Deze informatie wordt weergegeven zodat elke gebruikersinterface deze aan de gebruiker kan tonen. Chrome hoeft dit niet af te dwingen; in plaats daarvan moet de extensie `stopPinRequest` aanroepen met `errorType = MAX_ATTEMPTS_EXCEEDED` wanneer het aantal pinpogingen is overschreden.

  • fouttype

    PinRequestErrorType optioneel

    De foutmelding die aan de gebruiker wordt getoond. Deze moet worden ingesteld als het vorige verzoek is mislukt, om de gebruiker te informeren over de reden van de fout.

  • verzoektype

    PinRequestType optioneel

    Het type code dat wordt aangevraagd. Standaard is een pincode.

  • signRequestId

    nummer

    De ID die Chrome in SignRequest heeft opgegeven.

SetCertificatesDetails

Chrome 86+

Eigenschappen

  • certificatenAanvraagID

    nummer optioneel

    Wanneer deze functie wordt aangeroepen als reactie op onCertificatesUpdateRequested , moet deze de ontvangen certificatesRequestId waarde bevatten. Anders moet deze niet ingesteld zijn.

  • klantCertificaten

    ClientCertificateInfo []

    Lijst met momenteel beschikbare klantcertificaten.

  • fout

    "ALGEMENE_FOUT"
    optioneel

    Een eventuele fout die is opgetreden tijdens het extraheren van de certificaten. Deze fout wordt indien nodig aan de gebruiker getoond.

SignatureRequest

Chrome 86+

Eigenschappen

  • algoritme

    Algoritme

    Te gebruiken handtekeningalgoritme.

  • certificaat

    ArrayBuffer

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

  • invoer

    ArrayBuffer

    De gegevens moeten worden ondertekend. Let op: de gegevens zijn niet gehasht.

  • signRequestId

    nummer

    Verzoek-identificatiecode die moet worden doorgegeven aan reportSignature .

SignRequest

Eigenschappen

  • certificaat

    ArrayBuffer

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

  • verteren

    ArrayBuffer

    Het document dat ondertekend moet worden.

  • hash

    Hash

    Verwijst naar het hash-algoritme dat werd gebruikt om digest te creëren.

  • signRequestId

    nummer

    Chrome 57+

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

StopPinRequestDetails

Chrome 57+

Eigenschappen

  • fouttype

    PinRequestErrorType optioneel

    Het foutensjabloon. Indien aanwezig, wordt het aan de gebruiker getoond. Het is bedoeld om de reden voor het stoppen van de workflow te bevatten als dit door een fout is veroorzaakt, bijvoorbeeld MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    nummer

    De ID die Chrome in SignRequest heeft opgegeven.

Methoden

reportSignature()

Chrome 86+
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

Deze functie moet worden aangeroepen als reactie op onSignatureRequested .

De extensie moet deze functie uiteindelijk aanroepen voor elke onSignatureRequested -gebeurtenis; de API-implementatie stopt na enige tijd met wachten op deze aanroep en reageert met een time-outfout wanneer deze functie wordt aangeroepen.

Parameters

Retourneert

  • Promise<void>

    Chrome 96+

requestPin()

Chrome 57+
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): Promise<PinResponseDetails | undefined>

Vraagt ​​de gebruiker om de pincode. Er is slechts één verzoek tegelijk toegestaan. Verzoeken die worden ingediend terwijl een ander proces al gaande is, worden geweigerd. Het is de verantwoordelijkheid van de extensie om het later opnieuw te proberen als er een ander proces gaande is.

Parameters

Retourneert

  • Promise< PinResponseDetails | undefined>

    Chrome 96+

    Retourneert een Promise die wordt opgelost wanneer de gebruiker de pincode invoert. Weigert met een foutmelding als het dialoogvensterverzoek niet succesvol wordt afgerond (bijvoorbeeld als het dialoogvenster door de gebruiker is geannuleerd of niet mocht worden weergegeven).

setCertificates()

Chrome 86+
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): Promise<void>

Hiermee wordt een lijst met certificaten ingesteld die in de browser gebruikt moeten worden.

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

Parameters

Retourneert

  • Promise<void>

    Chrome 96+

    Retourneert een Promise die wordt opgelost zodra de uitvoering is voltooid.

stopPinRequest()

Chrome 57+
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

Stopt het pincodeverzoek dat is gestart door de functie requestPin .

Parameters

Retourneert

  • Promise<void>

    Chrome 96+

    Retourneert een Promise die wordt opgelost wanneer het verzoek om het PIN-dialoogvenster te sluiten is voltooid.

Evenementen

onCertificatesUpdateRequested

Chrome 86+
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Deze gebeurtenis wordt geactiveerd als de via setCertificates ingestelde certificaten onvoldoende zijn of als de browser om bijgewerkte informatie vraagt. De extensie moet setCertificates aanroepen met de bijgewerkte lijst met certificaten en de ontvangen certificatesRequestId .

Parameters

onSignatureRequested

Chrome 86+
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Deze gebeurtenis wordt geactiveerd telkens wanneer de browser een bericht moet ondertekenen met behulp van een certificaat dat door deze extensie via setCertificates wordt verstrekt.

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

Parameters