chrome.certificateProvider

Beschrijving

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

Machtigingen

certificateProvider

Beschikbaarheid

Chrome 46+ Alleen ChromeOS

Concepten en gebruik

Typisch gebruik van deze API om clientcertificaten beschikbaar te maken voor ChromeOS volgt deze stappen:

  • De Extensie registreert voor de gebeurtenissen onCertificatesUpdateRequested en onSignatureRequested .
  • De extensie roept setCertificates() aan om na de initialisatie de initiële lijst met certificaten op te geven.
  • De extensie controleert de wijzigingen in de lijst met beschikbare certificaten en roept setCertificates() aan om de browser op de hoogte te stellen van dergelijke wijzigingen.
  • Tijdens een TLS-handshake ontvangt de browser een clientcertificaatverzoek. Met een onCertificatesUpdateRequested gebeurtenis vraagt ​​de browser de extensie om alle certificaten te rapporteren die deze momenteel levert.
  • De extensie rapporteert terug met de momenteel beschikbare certificaten, met behulp van de setCertificates() -methode.
  • De browser vergelijkt alle beschikbare certificaten met het clientcertificaatverzoek van de externe host. De overeenkomsten worden aan de gebruiker gepresenteerd in een selectiedialoogvenster.
  • De gebruiker kan een certificaat selecteren en daarmee de authenticatie goedkeuren of de authenticatie afbreken.
Dialoogvenster voor certificaatselectie
Dialoogvenster voor certificaatselectie.
  • Als de gebruiker de authenticatie afbreekt of als er geen certificaat overeenkomt met het verzoek, wordt de TLS-clientauthenticatie afgebroken.
  • Anders, als de gebruiker de authenticatie 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 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 voor de gegeven gegevens creëren met behulp van de privésleutel die is gekoppeld aan het certificaat waarnaar wordt verwezen. Voor het maken van de handtekening kan het nodig zijn om een ​​DigestInfo voor te voegen en het resultaat op te vullen 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 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 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 in 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() {
  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

Chroom 86+

Typen ondersteunde algoritmen voor cryptografische handtekeningen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Specificeert het handtekeningalgoritme RSASSA PKCS#1 v1.5 met de MD5-SHA-1-hashing. De extensie mag geen DigestInfo-voorvoegsel voorafgaan, maar alleen PKCS#1-opvulling toevoegen. Dit algoritme is verouderd en zal vanaf versie 109 nooit meer door Chrome worden aangevraagd.

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

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

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

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

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

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

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

CertificateInfo

Eigenschappen

  • certificaat

    ArrayBuffer

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

  • ondersteundHashes

    Hasj []

    Moet worden ingesteld op alle hashes die voor dit certificaat worden ondersteund. Deze extensie zal alleen worden gevraagd om handtekeningen van samenvattingen die zijn berekend met een van deze hash-algoritmen. Dit zou moeten gebeuren in volgorde van afnemende hasjvoorkeur.

CertificatesUpdateRequest

Chroom 86+

Eigenschappen

  • certificatenRequestId

    nummer

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

    Hierbij moet precies één certificaat zijn inbegrepen.

  • ondersteunde algoritmen

    algoritme []

    Alle algoritmen die voor dit certificaat worden ondersteund. Alleen bij gebruik van een van deze algoritmen wordt de extensie om handtekeningen gevraagd.

Error

Chroom 86+

Soorten fouten die de extensie kan rapporteren.

Waarde

"GENERAL_ERROR"

Hash

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

Chroom 57+

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

Enum

"INVALID_PIN"
Geeft aan dat de pincode ongeldig is.

"INVALID_PUK"
Geeft aan dat de PUK ongeldig is.

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

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

PinRequestType

Chroom 57+

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

Enum

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

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

PinResponseDetails

Chroom 57+

Eigenschappen

  • gebruikerInvoer

    tekenreeks optioneel

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

ReportSignatureDetails

Chroom 86+

Eigenschappen

  • fout

    "GENERAL_ERROR"
    optioneel

    Fout die is opgetreden tijdens het genereren van de handtekening, indien aanwezig.

  • signRequestId

    nummer

    Verzoek-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. Er wordt niet verwacht dat Chrome dit afdwingt, maar stopPinRequest moet worden aangeroepen door de extensie met errorType = MAX_ATTEMPTS_EXCEEDED wanneer het aantal pinverzoeken wordt overschreden.

  • fouttype

    PinRequestErrorType optioneel

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

  • verzoekType

    PinRequestType optioneel

    Het type code dat wordt aangevraagd. Standaard is pincode.

  • signRequestId

    nummer

    De ID die door Chrome is opgegeven in SignRequest.

SetCertificatesDetails

Chroom 86+

Eigenschappen

  • certificatenRequestId

    nummer optioneel

    Wanneer aangeroepen als reactie op onCertificatesUpdateRequested , moet dit de ontvangen waarde certificatesRequestId bevatten. Anders moet het uitgeschakeld zijn.

  • klantCertificaten

    ClientCertificaatInfo []

    Lijst met momenteel beschikbare clientcertificaten.

  • fout

    "GENERAL_ERROR"
    optioneel

    Fout die is opgetreden tijdens het extraheren van de certificaten, indien aanwezig. Deze fout wordt indien nodig aan de gebruiker getoond.

SignatureRequest

Chroom 86+

Eigenschappen

  • algoritme

    Algoritme

    Handtekeningalgoritme dat moet worden gebruikt.

  • certificaat

    ArrayBuffer

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

  • invoer

    ArrayBuffer

    Gegevens te ondertekenen. Houd er rekening mee dat de gegevens niet zijn gehasht.

  • signRequestId

    nummer

    Verzoek-ID die 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.

  • verteren

    ArrayBuffer

    De samenvatting die moet worden ondertekend.

  • hasj

    Hasj

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

  • signRequestId

    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

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

  • signRequestId

    nummer

    De ID die door Chrome is opgegeven in SignRequest.

Methoden

reportSignature()

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

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

Retouren

  • Beloof <nietig>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

requestPin()

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

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

Parameters

Retouren

  • Belofte< PinResponseDetails | ongedefinieerd>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

setCertificates()

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

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 momenteel beschikbare certificaten. De extensie moet deze functie ook aanroepen als reactie op onCertificatesUpdateRequested telkens wanneer deze gebeurtenis wordt ontvangen.

Parameters

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

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

stopPinRequest()

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

Stopt het pinverzoek dat is gestart door de requestPin -functie.

Parameters

  • Bevat de details over de reden voor het stoppen van de aanvraagstroom.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 96+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

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 om bijgewerkte informatie vraagt. 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 elke keer geactiveerd wanneer 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 juiste privésleutel en deze retourneren door reportSignature aan te roepen met de ontvangen signRequestId .

Parameters