chrome.certificateProvider

Beschreibung

Verwenden Sie diese API, um der Plattform Zertifikate zur Verfügung zu stellen, die diese Zertifikate für TLS-Authentifizierungen verwenden können.

Berechtigungen

certificateProvider

Verfügbarkeit

Chrome (ab Version 46) Nur ChromeOS

Nutzung

Diese API wird üblicherweise so verwendet, um Clientzertifikate für ChromeOS freizugeben:

  • Die Erweiterung registriert sich für die Ereignisse onCertificatesUpdateRequested und onSignatureRequested.
  • Die Erweiterung ruft setCertificates auf, um nach der Initialisierung die ursprüngliche Liste der Zertifikate 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 erhält der Browser eine Clientzertifikatsanfrage. Bei einem onCertificatesUpdateRequested-Ereignis fordert der Browser die Erweiterung auf, alle derzeit bereitgestellten Zertifikate zu melden.
  • Die Erweiterung meldet die aktuell verfügbaren Zertifikate mithilfe der Methode setCertificates.
  • 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 für die Zertifikatsauswahl

  • Wenn der Nutzer die Authentifizierung abbricht oder kein Zertifikat mit der Anfrage übereinstimmt, wird die TLS-Clientauthentifizierung abgebrochen.
  • Wenn der Nutzer die Authentifizierung mit einem von dieser Erweiterung bereitgestellten Zertifikat genehmigt, fordert der Browser die Erweiterung an, die Daten zu signieren, um den TLS-Handshake fortzusetzen. Die Anfrage wird als onSignatureRequested-Ereignis gesendet.
  • Dieses Ereignis enthält Eingabedaten, deklariert, welcher Algorithmus zum Generieren der Signatur verwendet werden muss, und verweist auf eines der von dieser Erweiterung gemeldeten Zertifikate. Die Erweiterung muss mithilfe des privaten Schlüssels, der mit dem referenzierten Zertifikat verknüpft ist, eine Signatur für die angegebenen Daten erstellen. Zum Erstellen der Signatur kann es erforderlich sein, ein DigestInfo voranzustellen und das Ergebnis vor der eigentlichen Signatur auffüllen zu lassen.
  • Die Erweiterung sendet die Signatur mithilfe 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, schließt der Browser den TLS-Handshake ab.

Die tatsächliche Abfolge der Schritte kann abweichen. Der Nutzer wird beispielsweise 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 dies 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 (ab Version 86)

Typen unterstützter kryptografischer Signaturalgorithmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit dem MD5-SHA-1-Hashing an. Die Erweiterung darf kein DigestInfo-Präfix voranstellen, sondern darf nur PKCS#1-Padding hinzufügen. Dieser Algorithmus ist veraltet und wird ab Version 109 nicht mehr 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 Hash-Funktion SHA-256 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 MGF1-Maskengenerierungsfunktion und dem Salt mit derselben Größe wie der Hash an.

"RSASSA_PSS_SHA384"
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-384-Hash-Funktion, der MGF1-Maskengenerierungsfunktion und dem Salt an, dessen Größe dem Hash entspricht.

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

CertificateInfo

Attribute

  • Zertifikat

    ArrayBuffer

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

  • supportedHashes

    Hashen[]

    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 Reihenfolge der abnehmenden Hash-Einstellung erfolgen.

CertificatesUpdateRequest

Chrome (ab Version 86)

Attribute

ClientCertificateInfo

Chrome (ab Version 86)

Attribute

  • certificateChain

    ArrayBuffer[]

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

    Dies muss genau ein Zertifikat enthalten.

  • supportedAlgorithms

    Algorithmus[]

    Alle für dieses Zertifikat unterstützten Algorithmen. Die Erweiterung wird nur nach Signaturen gefragt, die einen dieser Algorithmen verwenden.

Error

Chrome (ab Version 86)

Arten von Fehlern, die von der Erweiterung gemeldet werden können.

Wert

"GENERAL_ERROR"

Hash

Verworfen. Ersetzt durch Algorithm.

Enum

"MD5_SHA1"
Gibt die Hash-Algorithmen MD5 und SHA1 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 von 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 Funktion „requestPin“ angefordert wird.

Enum

"PIN"
Gibt an, dass der angeforderte Code eine PIN ist.

"PUK"
Gibt an, dass der angeforderte Code eine PUK ist.

PinResponseDetails

Chrome 57 und höher

Attribute

  • userInput

    String optional

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

ReportSignatureDetails

Chrome (ab Version 86)

Attribute

  • Fehler

    "GENERAL_ERROR"
     optional

    Fehler beim Generieren der Signatur, falls vorhanden.

  • signRequestId

    Zahl

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

  • Signatur

    ArrayBuffer optional

    Die Signatur, wenn sie erfolgreich generiert wurde.

RequestPinDetails

Chrome 57 und höher

Attribute

  • attemptsLeft

    Zahl optional

    Die Anzahl der verbleibenden Versuche. Dieser wird bereitgestellt, damit jede Benutzeroberfläche dem Nutzer diese Informationen anzeigen kann. Es wird nicht erwartet, dass Chrome diese Anforderung erzwingt. Stattdessen sollte stopPinRequest von der Erweiterung mit dem Fehlertyp MAX_ATTEMPTS_EXCEEDED aufgerufen werden, wenn die Anzahl der PIN-Anfragen überschritten wird.

  • errorType

    PinRequestErrorType optional

    Die Fehlervorlage, die dem Nutzer angezeigt wird. Sollte festgelegt werden, wenn die vorherige Anfrage fehlgeschlagen ist, um den Nutzer über die Fehlerursache zu informieren.

  • requestType

    PinRequestType optional

    Der Typ des angeforderten Codes. Die Standardeinstellung ist die PIN.

  • signRequestId

    Zahl

    Die von Chrome in SignRequest bereitgestellte ID.

SetCertificatesDetails

Chrome (ab Version 86)

Attribute

  • certificatesRequestId

    Zahl optional

    Wenn er als Antwort auf onCertificatesUpdateRequested aufgerufen wird, sollte er den empfangenen certificatesRequestId-Wert enthalten. Sollte andernfalls nicht festgelegt werden.

  • clientCertificates

    ClientCertificateInfo[]

    Liste der derzeit verfügbaren Clientzertifikate.

  • Fehler

    "GENERAL_ERROR"
     optional

    Beim Extrahieren der Zertifikate ist ein Fehler aufgetreten, falls vorhanden. Dieser Fehler wird dem Nutzer gegebenenfalls angezeigt.

SignatureRequest

Chrome (ab Version 86)

Attribute

  • Algorithmus

    Algorithmus

    Zu verwendender Signaturalgorithmus.

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats Die Erweiterung muss input mit dem verknüpften privaten Schlüssel signieren.

  • Eingabe

    ArrayBuffer

    Zu signierende Daten. Die Daten sind nicht gehasht.

  • signRequestId

    Zahl

    Anfrage-ID zur Übergabe an reportSignature.

SignRequest

Attribute

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats Die Erweiterung muss digest mit dem verknüpften 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 werden soll, falls sie eine Methode aufrufen muss, die dies erfordert, z.B. requestPin fest.

StopPinRequestDetails

Chrome 57 und höher

Attribute

  • errorType

    PinRequestErrorType optional

    Die Fehlervorlage. Falls vorhanden, wird es dem Nutzer angezeigt. Gibt den Grund für das Anhalten des Ablaufs an, wenn dieser durch einen Fehler verursacht wurde, z.B. MAX_ATTEMPTS_EXCEEDED beschränkt.

  • signRequestId

    Zahl

    Die von Chrome in SignRequest bereitgestellte ID.

Methoden

reportSignature()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 86 und 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.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

requestPin()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 57 und 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 gesendet werden, während ein anderer Ablauf ausgeführt wird, werden abgelehnt. Es liegt in der Verantwortung der Erweiterung, es später noch einmal zu versuchen, wenn ein anderer Ablauf ausgeführt wird.

Parameter

Gibt Folgendes zurück:

  • Promise&lt;PinResponseDetails | nicht definiert>

    Chrome 96 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

setCertificates()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 86 und 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 des Satzes der aktuell verfügbaren Zertifikate aufrufen. Die Erweiterung sollte diese Funktion auch als Reaktion auf onCertificatesUpdateRequested aufrufen, wenn dieses Ereignis empfangen wird.

Parameter

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

stopPinRequest()

<ph type="x-smartling-placeholder"></ph> Versprechen Chrome 57 und höher 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Stoppt die von der Funktion requestPin gestartete PIN-Anfrage.

Parameter

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

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    () => void

Gibt Folgendes zurück:

  • Versprechen<void>

    Chrome 96 und höher

    Promise-Objekte werden nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

Ereignisse

onCertificatesRequested

Chrome 47 und höher &amp;leq; MV2 Eingestellt seit Chrome 86
chrome.certificateProvider.onCertificatesRequested.addListener(
  callback: function,
)

Verwenden Sie stattdessen onCertificatesUpdateRequested.

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (reportCallback: function) => void

    • reportCallback

      Funktion

      Der Parameter reportCallback sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

      • Zertifikate

        CertificateInfo[]

      • callback

        Funktion

        Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

        (rejectedCertificates: ArrayBuffer[]) => void

        • rejectedCertificates

          ArrayBuffer[]

onCertificatesUpdateRequested

Chrome (ab Version 86) 
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.

Parameter

onSignatureRequested

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

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

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

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

    (request: SignatureRequest) => void

onSignDigestRequested

<ph type="x-smartling-placeholder"></ph> &amp;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 privatem Schlüssel signieren und durch Aufrufen von reportCallback die Daten zurückgeben. reportCallback muss genau einmal aufgerufen werden.

Parameter

  • callback

    Funktion

    Der Parameter callback sieht so aus: <ph type="x-smartling-placeholder"></ph>

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

    • Anfrage

      SignRequest

    • reportCallback

      Funktion

      Chrome 47 und höher

      Der Parameter reportCallback sieht so aus: <ph type="x-smartling-placeholder"></ph>

      (signature?: ArrayBuffer) => void

      • Signatur

        ArrayBuffer optional