chrome.certificateProvider

refresh date: 2026-09-25 robots: noindex

Wichtig: Diese API funktioniert nur unter ChromeOS.

Beschreibung

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

Berechtigungen

certificateProvider

Verfügbarkeit

Chrome 46 und höher Nur ChromeOS

Nutzung

Die typische Verwendung dieser API, um Clientzertifikate für ChromeOS bereitzustellen, umfasst die folgenden Schritte:

• Die Erweiterung registriert sich für die Ereignisse onCertificatesUpdateRequested und onSignatureRequested.
• Die Erweiterung ruft setCertificates auf, um nach der Initialisierung die erste 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 empfängt der Browser eine Clientzertifikatsanfrage. Mit einem onCertificatesUpdateRequested-Ereignis fordert der Browser die Erweiterung auf, alle Zertifikate zu melden, die sie derzeit bereitstellt.
• Die Erweiterung meldet die derzeit verfügbaren Zertifikate mit der Methode setCertificates zurück.
• Der Browser gleicht alle verfügbaren Zertifikate mit der Clientzertifikatsanfrage des Remote-Hosts ab. Die Übereinstimmungen werden dem Nutzer in einem Auswahldialogfeld angezeigt.
• Der Nutzer kann ein Zertifikat auswählen und so die Authentifizierung genehmigen oder abbrechen.

• 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 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 vor dem eigentlichen Signieren ein DigestInfo-Wert vorangestellt und das Ergebnis 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, schließt der Browser den TLS-Handshake ab.

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

In der Erweiterung kann das so 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 not 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 oder höher

Arten von unterstützten kryptografischen Signaturalgorithmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Gibt den RSASSA PKCS#1 v1.5-Signaturalgorithmus mit MD5-SHA-1-Hashing an. Die Erweiterung darf kein DigestInfo-Präfix voranstellen, sondern nur ein PKCS#1-Padding hinzufügen. Dieser Algorithmus wird nicht mehr unterstützt und ab Chrome-Version 109 nicht mehr angefordert.

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

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

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

"RSASSA_PKCS1_v1_5_SHA512"
Gibt den RSASSA PKCS#1 v1.5-Signaturalgorithmus mit der SHA-512-Hashing-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 derselben Größe wie der Hash an.

"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

  Hash[]

  Muss auf alle für dieses Zertifikat unterstützten Hashes festgelegt werden. Diese Erweiterung wird nur nach Signaturen von Digests gefragt, die mit einem dieser Hash-Algorithmen berechnet wurden. Die Reihenfolge sollte nach absteigender Hash-Präferenz erfolgen.

CertificatesUpdateRequest

Chrome 86 oder höher

Attribute

• certificatesRequestId

  Zahl

  Anfrage-ID, die an setCertificates übergeben werden soll.

ClientCertificateInfo

Chrome 86 oder höher

Attribute

• certificateChain

  ArrayBuffer[]

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

  Diese muss genau ein Zertifikat enthalten.

• supportedAlgorithms

  Algorithmus[]

  Alle für dieses Zertifikat unterstützten Algorithmen. Die Erweiterung wird nur nach Signaturen mit einem dieser Algorithmen gefragt.

Error

Chrome 86 oder höher

Arten von Fehlern, die die Erweiterung melden kann.

Wert

"GENERAL_ERROR"

Hash

Verworfen. Ersetzt durch Algorithm.

Enum

"MD5_SHA1"
Gibt die Hash-Algorithmen MD5 und SHA1 an.

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

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

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

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

PinRequestErrorType

Chrome 57 oder höher

Die Arten von Fehlern, die dem Nutzer über die Funktion „requestPin“ 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 oder höher

Der Typ des Codes, 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 ein PUK ist.

PinResponseDetails

Chrome 57 oder höher

Attribute

• userInput

  String optional

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

ReportSignatureDetails

Chrome 86 oder höher

Attribute

• Fehler

  "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 generiert wurde.

RequestPinDetails

Chrome 57 oder höher

Attribute

• attemptsLeft

  number optional

  Die Anzahl der verbleibenden Versuche. Diese Informationen werden bereitgestellt, damit sie in jeder Benutzeroberfläche angezeigt werden können. Chrome wird dies voraussichtlich nicht erzwingen. Stattdessen sollte „stopPinRequest“ von der Erweiterung mit „errorType = MAX_ATTEMPTS_EXCEEDED“ aufgerufen werden, wenn die Anzahl der PIN-Anfragen überschritten wird.

• errorType

  PinRequestErrorType optional

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

• requestType

  PinRequestType optional

  Der Typ des angeforderten Codes. Der Standardwert ist „PIN“.

• signRequestId

  Zahl

  Die von Chrome in SignRequest angegebene ID.

SetCertificatesDetails

Chrome 86 oder höher

Attribute

• certificatesRequestId

  number optional

  Wenn der Aufruf als Antwort auf onCertificatesUpdateRequested erfolgt, sollte der empfangene certificatesRequestId-Wert enthalten sein. Andernfalls sollte es nicht festgelegt sein.

• clientCertificates

  ClientCertificateInfo[]

  Liste der derzeit verfügbaren Clientzertifikate.

• Fehler

  "GENERAL_ERROR"
   optional

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

SignatureRequest

Chrome 86 oder 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 Digest, der signiert werden muss.

• Hash

  Hash

  Bezieht sich auf den Hash-Algorithmus, der zum Erstellen von digest verwendet wurde.

• signRequestId

  Zahl

  Chrome 57 oder höher

  Die eindeutige ID, die von der Erweiterung verwendet werden soll, wenn sie eine Methode aufrufen muss, die diese ID erfordert, z.B. requestPin.

StopPinRequestDetails

Chrome 57 oder höher

Attribute

• errorType

  PinRequestErrorType optional

  Die Fehlervorlage. Falls vorhanden, wird sie dem Nutzer angezeigt. Soll den Grund für das Beenden des Ablaufs enthalten, wenn er durch einen Fehler verursacht wurde, z.B. MAX_ATTEMPTS_EXCEEDED.

• signRequestId

  Zahl

  Die von Chrome in SignRequest angegebene ID.

Methoden

reportSignature()

Promise Chrome 86 oder höher

chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
  callback?: function,
): Promise<void>

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

• Details

  ReportSignatureDetails

• callback

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 96 oder höher

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

requestPin()

Promise Chrome 57 und höher

chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
  callback?: function,
): Promise<PinResponseDetails | undefined>

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

Parameter

• Details

  RequestPinDetails

  Enthält die Details zum angeforderten Dialog.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (details?: PinResponseDetails) => void

  • Details

    PinResponseDetails optional

Ausgabe

• Promise<PinResponseDetails | undefined>

  Chrome 96 oder höher

  Gibt ein Promise zurück, das aufgelöst wird, wenn die PIN vom Nutzer angegeben wird. Wird mit einem Fehler abgelehnt, wenn die Dialogfeldanfrage nicht erfolgreich abgeschlossen wird (z.B. wenn das Dialogfeld vom Nutzer abgebrochen wurde oder nicht angezeigt werden durfte).

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

setCertificates()

Promise Chrome 86 oder höher

chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
  callback?: function,
): Promise<void>

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

Die Erweiterung sollte diese Funktion nach der Initialisierung und bei jeder Änderung der aktuell verfügbaren Zertifikate aufrufen. Die Erweiterung sollte diese Funktion auch jedes Mal als Antwort auf onCertificatesUpdateRequested aufrufen, wenn dieses Ereignis empfangen wird.

Parameter

• Details

  SetCertificatesDetails

  Die festzulegenden Zertifikate. Ungültige Zertifikate werden ignoriert.

• callback

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 96 oder höher

  Gibt ein Promise zurück, das nach Abschluss aufgelöst wird.

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

stopPinRequest()

Promise Chrome 57 und höher

chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
): Promise<void>

Beendet die PIN-Anfrage, die von der Funktion requestPin gestartet wurde.

Parameter

• Details

  StopPinRequestDetails

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

• callback

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 96 oder höher

  Gibt ein Promise zurück, das aufgelöst wird, wenn die Anfrage zum Schließen des PIN-Dialogfelds abgeschlossen ist.

  Promises 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 &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:

  (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

        ArrayBuffer[]

onCertificatesUpdateRequested

Chrome 86 oder 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.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (request: CertificatesUpdateRequest) => void

  • Anfrage

    CertificatesUpdateRequest

onSignatureRequested

Chrome 86 oder höher

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 privaten Schlüssel signieren und sie durch Aufrufen von reportSignature mit dem empfangenen signRequestId zurückgeben.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (request: SignatureRequest) => void

  • Anfrage

    SignatureRequest

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 Zertifikat signieren muss, das von dieser Erweiterung als Antwort auf ein onCertificatesRequested-Ereignis bereitgestellt wird. Die Erweiterung muss die Daten in request mit dem entsprechenden Algorithmus und privaten Schlüssel signieren und durch Aufrufen von reportCallback zurückgeben. reportCallback muss genau einmal aufgerufen werden.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

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

  • Anfrage

    SignRequest

  • reportCallback

    Funktion

    Chrome 47 oder höher

    Der Parameter reportCallback sieht so aus:

    (signature?: ArrayBuffer) => void

    • Signatur

      ArrayBuffer optional