chrome.certificateProvider

Beschreibung

Mit dieser API können Sie Zertifikate für die Plattform freigeben, die diese Zertifikate für TLS-Authentifizierungen verwenden kann.

Berechtigungen

certificateProvider

Verfügbarkeit

Chrome 46 und höher Nur ChromeOS

Konzepte und Nutzung

Für die Verwendung dieser API werden normalerweise die folgenden Schritte verwendet, um Clientzertifikate für ChromeOS verfügbar zu machen:

  • Die Erweiterung wird für die Ereignisse onCertificatesUpdateRequested und onSignatureRequested registriert.
  • Die Erweiterung ruft setCertificates() auf, um nach der Initialisierung eine anfängliche Liste von Zertifikaten bereitzustellen.
  • Die Erweiterung überwacht die Änderungen in der Liste der verfügbaren Zertifikate und ruft setCertificates() auf, um den Browser über jede solche Änderung zu informieren.
  • Während eines TLS-Handshakes empfängt der Browser eine Clientzertifikatsanfrage. Bei einem onCertificatesUpdateRequested-Ereignis fordert der Browser die Erweiterung auf, alle derzeit bereitgestellten Zertifikate zu melden.
  • Die Erweiterung meldet mit der Methode setCertificates() die aktuell verfügbaren Zertifikate.
  • Der Browser gleicht alle verfügbaren Zertifikate mit der Clientzertifikatsanfrage vom Remote-Host ab. Die Übereinstimmungen werden dem Nutzer in einem Auswahldialogfeld angezeigt.
  • Der Nutzer kann ein Zertifikat auswählen und damit die Authentifizierung genehmigen oder die Authentifizierung abbrechen.
Dialogfeld zur Zertifikatsauswahl
Dialogfeld zur Zertifikatsauswahl.
  • Wenn der Nutzer die Authentifizierung abbricht oder kein Zertifikat mit der Anfrage übereinstimmt, wird die TLS-Clientauthentifizierung abgebrochen.
  • Falls der Nutzer die Authentifizierung mit einem von dieser Erweiterung bereitgestellten Zertifikat genehmigt, fordert der Browser die Erweiterung auf, die Daten zu signieren, um den TLS-Handshake fortzusetzen. Die Anfrage wird als onSignatureRequested-Ereignis gesendet.
  • Dieses Ereignis enthält Eingabedaten, gibt an, welcher Algorithmus zum Generieren der Signatur verwendet werden muss, und verweist auf eines der Zertifikate, die von dieser Erweiterung gemeldet wurden. Die Erweiterung muss eine Signatur für die angegebenen Daten mit dem privaten Schlüssel erstellen, der mit dem referenzierten Zertifikat verknüpft ist. Zum Erstellen der Signatur muss möglicherweise ein DigestInfo vorangestellt und das Ergebnis vor der eigentlichen Signatur aufgefüllt werden.
  • Die Erweiterung sendet die Signatur mit der Methode reportSignature() an den Browser zurück. Wenn die Signatur nicht berechnet werden konnte, muss die Methode ohne Signatur aufgerufen werden.
  • Wenn die Signatur bereitgestellt wurde, vervollständigt der Browser den TLS-Handshake.

Die tatsächliche Abfolge der Schritte kann davon abweichen. Beispielsweise wird der Nutzer nicht zur Auswahl eines Zertifikats aufgefordert, wenn die Unternehmensrichtlinie zur automatischen Auswahl eines Zertifikats verwendet wird (siehe AutoSelectCertificateForUrls und Chrome-Richtlinien für Nutzer).

In der Erweiterung kann das wie das folgende Snippet aussehen:

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

Chrome 86 und höher

Arten unterstützter kryptografischer Signaturalgorithmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit dem MD5-SHA-1-Hash an. Der Erweiterung darf kein DigestInfo-Präfix vorangestellt werden, sondern nur ein PKCS#1-Padding. Dieser Algorithmus wurde eingestellt und wird ab Version 109 nie von Chrome angefordert.

"RSASSA_PKCS1_v1_5_SHA1"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit der SHA-1-Hash-Funktion an.

"RSASSA_PKCS1_v1_5_SHA256"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit der SHA-256-Hash-Funktion an.

"RSASSA_PKCS1_v1_5_SHA384"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit der SHA-384-Hash-Funktion an.

"RSASSA_PKCS1_v1_5_SHA512"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit der SHA-512-Hash-Funktion an.

"RSASSA_PSS_SHA256"
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-256-Hash-Funktion, der Funktion zur MGF1-Maskengenerierung und dem Salt von derselben Größe wie der Hash an.

"RSASSA_PSS_SHA384"
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-384-Hash-Funktion, der Funktion zur MGF1-Maskengenerierung und dem Salt von derselben Größe wie der Hash an.

"RSASSA_PSS_SHA512"
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-512-Hashfunktion, der Funktion zur MGF1-Maskengenerierung und dem Salt von derselben Größe wie der Hash an.

CertificateInfo

Attribute

  • Zertifikat

    ArrayBuffer

    Muss die DER-Codierung eines X.509-Zertifikats sein. Derzeit werden nur Zertifikate für RSA-Schlüssel unterstützt.

  • supportedHashes

    Hash[]

    Muss auf alle Hashes festgelegt sein, die für dieses Zertifikat unterstützt werden. Diese Erweiterung wird nur nach Signaturen von Digests gefragt, die mit einem dieser Hash-Algorithmen berechnet wurden. Dies sollte in der abnehmenden Reihenfolge der Hash-Einstellung erfolgen.

CertificatesUpdateRequest

Chrome 86 und höher

Attribute

  • certificatesRequestId

    Zahl

    Anfrage-ID, die an setCertificates übergeben werden soll

ClientCertificateInfo

Chrome 86 und höher

Attribute

  • certificateChain

    Array-Zwischenspeicher[]

    Das Array muss als erstes Element die DER-Codierung des X.509-Clientzertifikats enthalten.

    Es muss genau ein Zertifikat enthalten sein.

  • supportedAlgorithms

    Algorithmus[]

    Alle für dieses Zertifikat unterstützten Algorithmen. Die Erweiterung fragt nur über einen dieser Algorithmen nach Signaturen.

Error

Chrome 86 und höher

Fehlertypen, die von der Erweiterung gemeldet werden können.

Wert

"GENERAL_ERROR"

Hash

Veraltet. Ersetzt durch Algorithm.

Enum

"MD5_SHA1"
Gibt den MD5- und SHA1-Hash-Algorithmus an.

"SHA1"
Gibt den SHA1-Hash-Algorithmus an.

"SHA256"
Gibt den SHA256-Hash-Algorithmus an.

"SHA384"
Gibt den SHA384-Hash-Algorithmus an.

"SHA512"
Gibt den SHA512-Hash-Algorithmus an.

PinRequestErrorType

Chrome 57 und höher

Die Fehlertypen, die dem Nutzer über die requestPin-Funktion angezeigt werden können.

Enum

"INVALID_PIN"
Gibt an, dass die PIN ungültig ist.

"INVALID_PUK"
Gibt an, dass der PUK ungültig ist.

"MAX_ATTEMPTS_EXCEEDED"
Gibt an, dass die maximale Anzahl an Versuchen überschritten wurde.

"UNKNOWN_ERROR"
Gibt an, dass der Fehler nicht durch die oben genannten Typen dargestellt werden kann.

PinRequestType

Chrome 57 und höher

Der Codetyp, der von der Erweiterung mit der requestPin-Funktion angefordert wird.

Enum

"PIN"
Gibt an, dass es sich bei dem angeforderten Code um eine PIN handelt.

"PUK"
Gibt an, dass es sich bei dem angeforderten Code um einen PUK handelt.

PinResponseDetails

Chrome 57 und höher

Attribute

  • userInput

    String optional

    Der vom Nutzer bereitgestellte Code. Leer, wenn der Nutzer das Dialogfeld geschlossen hat oder ein anderer Fehler aufgetreten ist.

ReportSignatureDetails

Chrome 86 und höher

Attribute

  • error

    "GENERAL_ERROR"
     optional

    Fehler, der beim Generieren der Signatur aufgetreten ist, falls vorhanden.

  • signRequestId

    Zahl

    Anfrage-ID, die über das Ereignis onSignatureRequested empfangen wurde.

  • Signatur

    ArrayBuffer optional

    Die Signatur, wenn sie erfolgreich erstellt wurde.

RequestPinDetails

Chrome 57 und höher

Attribute

  • attemptsLeft

    Nummer optional

    Die Anzahl der verbleibenden Versuche. Dies ist erforderlich, damit diese Informationen dem Nutzer auf jeder Benutzeroberfläche präsentiert werden können. Es wird davon ausgegangen, dass Chrome dies nicht erzwingt. Stattdessen sollte stopPinRequest von der Erweiterung mit dem Fehlertyp „errorType = MAX_ATTEMPTS_EXCEEDED“ aufgerufen werden, wenn die Anzahl der PIN-Anfragen überschritten wird.

  • errorType

    PinRequestErrorType optional

    Die Fehlervorlage, die dem Nutzer angezeigt wird. Diese sollte festgelegt werden, wenn die vorherige Anfrage fehlgeschlagen ist, um den Nutzer über den Grund für den Fehler zu informieren.

  • requestType

    PinRequestType optional

    Die Art des angeforderten Codes. Die Standardeinstellung ist PIN.

  • signRequestId

    Zahl

    Die von Chrome in SignRequest bereitgestellte ID.

SetCertificatesDetails

Chrome 86 und höher

Attribute

  • certificatesRequestId

    Nummer optional

    Sollte beim Aufruf als Antwort auf onCertificatesUpdateRequested den empfangenen certificatesRequestId-Wert enthalten. Andernfalls sollte sie nicht festgelegt werden.

  • clientCertificates

    ClientCertificateInfo[]

    Liste der derzeit verfügbaren Clientzertifikate.

  • error

    "GENERAL_ERROR"
     optional

    Fehler, der beim Extrahieren der Zertifikate (falls vorhanden) aufgetreten ist. Dieser Fehler wird dem Nutzer gegebenenfalls angezeigt.

SignatureRequest

Chrome 86 und höher

Attribute

  • Algorithmus

    Algorithmus

    Zu verwendender Signaturalgorithmus.

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats. Die Erweiterung muss input mit dem zugehörigen privaten Schlüssel signieren.

  • Eingabe

    ArrayBuffer

    Zu signierende Daten. Die Daten sind nicht gehasht.

  • signRequestId

    Zahl

    Anfrage-ID, die an reportSignature übergeben werden soll

SignRequest

Attribute

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats. Die Erweiterung muss digest mit dem zugehörigen privaten Schlüssel signieren.

  • Hashwert

    ArrayBuffer

    Der zu signierende Digest.

  • Hash

    Hash

    Bezieht sich auf den Hash-Algorithmus, mit dem digest erstellt wurde.

  • signRequestId

    Zahl

    Chrome 57 und höher

    Die eindeutige ID, die von der Erweiterung verwendet wird, falls sie eine Methode aufrufen muss, die dies erfordert, z.B. „requestPin“.

StopPinRequestDetails

Chrome 57 und höher

Attribute

  • errorType

    PinRequestErrorType optional

    Die Fehlervorlage. Falls vorhanden, wird es dem Nutzer angezeigt. Sie sollte den Grund für das Anhalten des Datenflusses enthalten, wenn dieser durch einen Fehler verursacht wurde, z.B. MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    Zahl

    Die von Chrome in SignRequest bereitgestellte ID.

Methoden

reportSignature()

Versprechen Chrome 86 oder höher 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
)

Sollte als Antwort auf onSignatureRequested aufgerufen werden.

Die Erweiterung muss diese Funktion schließlich für jedes onSignatureRequested-Ereignis aufrufen. Die API-Implementierung wartet nach einiger Zeit nicht mehr auf diesen Aufruf und antwortet mit einem Zeitüberschreitungsfehler, wenn diese Funktion aufgerufen wird.

Parameters

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

requestPin()

Versprechen Chrome 57 oder höher 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
)

Fordert die PIN vom Nutzer an Es ist jeweils nur eine laufende Anfrage zulässig. Die Anfragen, die während eines anderen Ablaufs gestellt wurden, werden abgelehnt. Es liegt in der Verantwortung der Erweiterung, es später noch einmal zu versuchen, wenn ein anderer Ablauf läuft.

Parameters

Rückgaben

  • Promise<PinResponseDetails|undefined>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

setCertificates()

Versprechen Chrome 86 oder höher 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
)

Legt eine Liste von Zertifikaten fest, die im Browser verwendet werden sollen.

Die Erweiterung sollte diese Funktion nach der Initialisierung und bei jeder Änderung in den aktuell verfügbaren Zertifikaten aufrufen. Die Erweiterung sollte diese Funktion außerdem jedes Mal als Antwort auf onCertificatesUpdateRequested aufrufen, wenn dieses Ereignis empfangen wird.

Parameters

  • Die festzulegenden Zertifikate. Ungültige Zertifikate werden ignoriert.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

stopPinRequest()

Versprechen Chrome 57 oder höher 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Stoppt die von der Funktion requestPin gestartete PIN-Anfrage.

Parameters

  • Enthält die Details zum Grund für das Beenden des Anfrageflusses.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    ()=>void

Rückgaben

  • Promise<void>

    Chrome 96 oder höher

    Promise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.

Veranstaltungen

onCertificatesRequested

Chrome 47 oder höher &leq; MV2 Seit Chrome 86 eingestellt
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Verwenden Sie stattdessen onCertificatesUpdateRequested.

Dieses Ereignis wird jedes Mal ausgelöst, wenn der Browser die aktuelle Liste der Zertifikate anfordert, die von dieser Erweiterung bereitgestellt werden. Die Erweiterung muss reportCallback genau einmal mit der aktuellen Liste der Zertifikate aufrufen.

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (reportCallback: function)=>void

    • reportCallback

      Funktion

      Der Parameter reportCallback sieht so aus: 

      (certificates: CertificateInfo[],callback: function)=>void

      • Zertifikate

        CertificateInfo[]

      • callback

        Funktion

        Der Parameter callback sieht so aus: 

        (rejectedCertificates: ArrayBuffer[])=>void

        • rejectedCertificates

          Array-Zwischenspeicher[]

onCertificatesUpdateRequested

Chrome 86 und höher 
chrome.certificateProvider.onCertificatesUpdateRequested.addListener(
  callback: function,
)

Dieses Ereignis wird ausgelöst, wenn die über setCertificates festgelegten Zertifikate nicht ausreichen oder der Browser aktualisierte Informationen anfordert. Die Erweiterung muss setCertificates mit der aktualisierten Liste der Zertifikate und der empfangenen certificatesRequestId aufrufen.

Parameters

onSignatureRequested

Chrome 86 und höher 
chrome.certificateProvider.onSignatureRequested.addListener(
  callback: function,
)

Dieses Ereignis wird jedes Mal ausgelöst, wenn der Browser eine Nachricht mit einem von dieser Erweiterung über setCertificates bereitgestellten Zertifikat signieren muss.

Die Erweiterung muss die Eingabedaten von request mit dem entsprechenden Algorithmus und dem privaten Schlüssel signieren und durch Aufrufen von reportSignature mit der empfangenen signRequestId zurückgeben.

Parameters

onSignDigestRequested

&leq; MV2 Seit Chrome 86 eingestellt
chrome.certificateProvider.onSignDigestRequested.addListener(
  callback: function,
)

Verwenden Sie stattdessen onSignatureRequested.

Dieses Ereignis wird jedes Mal ausgelöst, wenn der Browser eine Nachricht mit einem von dieser Erweiterung bereitgestellten Zertifikat als Antwort auf ein onCertificatesRequested-Ereignis signieren muss. Die Erweiterung muss die Daten in request mit dem entsprechenden Algorithmus und dem privaten Schlüssel signieren und durch Aufrufen von reportCallback zurückgeben. reportCallback muss genau einmal aufgerufen werden.

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (request: SignRequest,reportCallback: function)=>void

    • Request

      SignRequest

    • reportCallback

      Funktion

      Chrome 47 und höher

      Der Parameter reportCallback sieht so aus: 

      (signature?: ArrayBuffer)=>void

      • Signatur

        ArrayBuffer optional