chrome.certificateProvider

Beschrijving

Met deze API kunt u certificaten beschikbaar stellen aan het platform, dat deze certificaten kan gebruiken voor TLS-authenticatie.

Machtigingen

certificateProvider

Beschikbaarheid

Chrome 46+ Alleen ChromeOS

Begrippen en gebruik

Het typische gebruik van deze API om clientcertificaten beschikbaar te maken voor ChromeOS verloopt als volgt:

  • De extensie registreert zich voor de gebeurtenissen onCertificatesUpdateRequested en onSignatureRequested .
  • De extensie roept setCertificates() aan om de initiële lijst met certificaten na de initialisatie te verstrekken.
  • De extensie houdt de wijzigingen in de lijst met beschikbare certificaten in de gaten en roept setCertificates() aan om de browser op de hoogte te stellen van elke wijziging.
  • Tijdens een TLS-handshake ontvangt de browser een aanvraag voor een clientcertificaat. Met een onCertificatesUpdateRequested -gebeurtenis vraagt de browser de extensie om alle certificaten te rapporteren die momenteel worden aangeboden.
  • De extensie rapporteert met de momenteel beschikbare certificaten, met behulp van de setCertificates() methode.
  • De browser vergelijkt alle beschikbare certificaten met de clientcertificaataanvraag van de externe host. De overeenkomsten worden aan de gebruiker gepresenteerd in een selectiedialoog.
  • De gebruiker kan een certificaat selecteren en daarmee de authenticatie goedkeuren of afbreken.
Dialoogvenster Certificaatselectie
Dialoogvenster voor certificaatselectie.
  • Als de gebruiker de authenticatie afbreekt of er geen certificaat overeenkomt met de aanvraag, wordt de TLS-clientauthenticatie afgebroken.
  • Anders, als de gebruiker de authenticatie goedkeurt met een certificaat dat door deze extensie wordt verstrekt, verzoekt de browser de extensie om de gegevens te ondertekenen om de TLS-handshake voort te zetten. Het 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 aanmaken voor de opgegeven gegevens met behulp van de persoonlijke sleutel die aan het betreffende certificaat is gekoppeld. Het aanmaken van de handtekening vereist mogelijk het toevoegen van een DigestInfo en het aanvullen van het resultaat vóór de daadwerkelijke ondertekening.
  • De extensie stuurt de handtekening terug naar de browser met behulp van de reportSignature() methode. Als de handtekening niet kon worden berekend, moet de methode zonder handtekening worden aangeroepen.
  • Als de handtekening is meegegeven, voltooit de browser de TLS-handshake.

De daadwerkelijke volgorde van de stappen kan afwijken. 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:

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

Typen

Algorithm

Chroom 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-handtekeningalgoritme met de SHA-1-hashfunctie.

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

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

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

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

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

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

CertificateInfo

Eigenschappen

  • certificaat

    ArrayBuffer

    Moet de DER-codering van een X.509-certificaat zijn. Momenteel worden alleen certificaten met RSA-sleutels ondersteund.

  • ondersteundeHashes

    Hash []

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

CertificatesUpdateRequest

Chroom 86+

Eigenschappen

  • certificatenAanvraag-ID

    nummer

    Verzoek-ID die moet worden doorgegeven aan setCertificates .

ClientCertificateInfo

Chroom 86+

Eigenschappen

  • certificaatChain

    ArrayBuffer[]

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

    Dit moet precies één certificaat bevatten.

  • ondersteunde algoritmen

    Algoritme []

    Alle algoritmen worden voor dit certificaat ondersteund. De extensie vraagt alleen om handtekeningen met behulp van een van deze algoritmen.

Error

Chroom 86+

Soorten fouten die de extensie kan rapporteren.

Waarde

"ALGEMENE_FOUT"

Hash

Verouderd. Vervangen door Algorithm .

Enum

"MD5_SHA1"
Geeft de MD5- en SHA1-hashalgoritmen op.

"SHA1"
Geeft het SHA1-hashalgoritme op.

"SHA256"
Geeft het SHA256-hashalgoritme aan.

"SHA384"
Geeft het SHA384-hashalgoritme op.

"SHA512"
Geeft het SHA512-hashalgoritme aan.

PinRequestErrorType

Chroom 57+

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

Enum

"ONGELDIGE_PIN"
Geeft aan dat de pincode ongeldig is.

"ONGELDIGE_PUK"
Geeft aan dat de PUK-code ongeldig is.

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

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

PinRequestType

Chroom 57+

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

Enum

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

"PUK"
Geeft aan dat de gevraagde code een PUK-code is.

PinResponseDetails

Chroom 57+

Eigenschappen

  • gebruikersinvoer

    string optioneel

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

ReportSignatureDetails

Chroom 86+

Eigenschappen

  • fout

    "ALGEMENE_FOUT"
    optioneel

    Er is een fout opgetreden tijdens het genereren van de handtekening, indien van toepassing.

  • tekenAanvraagId

    nummer

    Aanvraag-ID die is ontvangen via de onSignatureRequested -gebeurtenis.

  • handtekening

    ArrayBuffer optioneel

    De handtekening, indien succesvol gegenereerd.

RequestPinDetails

Chroom 57+

Eigenschappen

  • pogingenLinks

    nummer optioneel

    Het aantal resterende pogingen. Dit wordt gedaan zodat elke gebruikersinterface deze informatie aan de gebruiker kan presenteren. Chrome hoeft dit niet af te dwingen; stopPinRequest moet in plaats daarvan door de extensie worden aangeroepen met errorType = MAX_ATTEMPTS_EXCEEDED wanneer het aantal pinverzoeken wordt overschreden.

  • foutType

    PinRequestErrorType optioneel

    De foutsjabloon die aan de gebruiker wordt weergegeven. Deze moet worden ingesteld als de vorige aanvraag is mislukt, om de gebruiker op de hoogte te stellen van de reden van de mislukking.

  • aanvraagtype

    PinRequestType optioneel

    Het type code dat wordt opgevraagd. Standaard is dit PIN.

  • tekenAanvraagId

    nummer

    De ID die Chrome heeft meegegeven in SignRequest.

SetCertificatesDetails

Chroom 86+

Eigenschappen

  • certificatenAanvraag-ID

    nummer optioneel

    Wanneer aangeroepen als reactie op onCertificatesUpdateRequested , moet dit de ontvangen waarde certificatesRequestId bevatten. Anders moet het ongedaan worden gemaakt.

  • clientCertificaten

    ClientCertificateInfo []

    Lijst met momenteel beschikbare clientcertificaten.

  • fout

    "ALGEMENE_FOUT"
    optioneel

    Er is een fout opgetreden tijdens het extraheren van de certificaten, indien van toepassing. Deze fout wordt indien nodig aan de gebruiker getoond.

SignatureRequest

Chroom 86+

Eigenschappen

  • algoritme

    Algoritme

    Het 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

    Te ondertekenen gegevens. Let op: de gegevens zijn niet gehasht.

  • tekenAanvraagId

    nummer

    Verzoek-ID die doorgegeven moet worden aan reportSignature .

SignRequest

Eigenschappen

  • certificaat

    ArrayBuffer

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

  • verteren

    ArrayBuffer

    Het overzicht dat ondertekend moet worden.

  • hasj

    Hasj

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

  • tekenAanvraagId

    nummer

    Chroom 57+

    De unieke ID die door de extensie moet worden gebruikt als deze een methode moet aanroepen die dit vereist, bijvoorbeeld requestPin.

StopPinRequestDetails

Chroom 57+

Eigenschappen

  • foutType

    PinRequestErrorType optioneel

    De foutsjabloon. Indien aanwezig, wordt deze aan de gebruiker getoond. Bedoeld om de reden voor het stoppen van de stroom te bevatten als deze werd veroorzaakt door een fout, bijvoorbeeld MAX_ATTEMPTS_EXCEEDED.

  • tekenAanvraagId

    nummer

    De ID die Chrome heeft meegegeven in SignRequest.

Methoden

reportSignature()

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

Moet worden aangeroepen als reactie op onSignatureRequested .

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

Parameters

Retourneren

  • Belofte<leegte>

    Chroom 96+

requestPin()

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

Vraagt de pincode op bij de gebruiker. Er is slechts één lopend verzoek tegelijk toegestaan. Verzoeken die worden verzonden terwijl er een andere stroom actief is, worden afgewezen. Het is de verantwoordelijkheid van de extensie om het later opnieuw te proberen als er een andere stroom actief is.

Parameters

Retourneren

setCertificates()

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

Stelt een lijst met certificaten in die in de browser moeten worden gebruikt.

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 in reactie op onCertificatesUpdateRequested , telkens wanneer deze gebeurtenis wordt ontvangen.

Parameters

Retourneren

  • Belofte<leegte>

    Chroom 96+

stopPinRequest()

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

Stopt de pin-aanvraag die is gestart door de functie requestPin .

Parameters

Retourneren

  • Belofte<leegte>

    Chroom 96+

Evenementen

onCertificatesUpdateRequested

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

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

Parameters

onSignatureRequested

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

Deze gebeurtenis wordt telkens geactiveerd 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