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 Verwendung

So verwenden Sie diese API üblicherweise, 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 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 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 derzeit verfügbaren Zertifikate mit der Methode setCertificates() zurück.
  • Der Browser gleicht alle verfügbaren Zertifikate mit der Clientzertifikatsanfrage vom Remotehost ab. Die Übereinstimmungen werden dem Nutzer in einem Auswahldialogfeld angezeigt.
  • Der Nutzer kann ein Zertifikat auswählen und damit die Authentifizierung genehmigen oder abbrechen.
Dialogfeld für die Zertifikatsauswahl
Dialogfeld für die Zertifikatsauswahl
  • Wenn der Nutzer die Authentifizierung abbricht oder kein Zertifikat mit der Anfrage übereinstimmt, wird die TLS-Clientauthentifizierung abgebrochen.
  • Andernfalls, 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. Für die Erstellung der Signatur muss möglicherweise vor der eigentlichen Signatur eine DigestInfo 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. Beispielsweise wird der Nutzer 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 könnte 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 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 von unterstützten kryptografischen Signaturalgorithmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Gibt den RSASSA PKCS#1 v1.5-Signaturalgorithmus mit MD5-SHA-1-Hash an. Die Erweiterung darf kein DigestInfo-Präfix vorangestellt haben, sondern nur PKCS#1-Padding. Dieser Algorithmus wird eingestellt und wird ab Chrome-Version 109 nicht mehr von Chrome 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-Hash-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-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, das der Größe des Hashwerts entspricht.

RSASSA_PSS_SHA512
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-512-Hash-Funktion, der MGF1-Maskengenerierungsfunktion und dem Salt an, das der Größe des Hashwerts entspricht.

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 um Signaturen von Digests gebeten, die mit einem dieser Hash-Algorithmen berechnet wurden. Die Reihenfolge sollte absteigend nach Hash-Präferenz 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

    ArrayBuffer[]

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

    Diese muss genau ein Zertifikat enthalten.

  • supportedAlgorithms

    Algorithmus[]

    Alle für dieses Zertifikat unterstützten Algorithmen. Die Erweiterung wird nur mithilfe eines dieser Algorithmen um Signaturen gebeten.

Error

Chrome 86 und 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-Hash-Algorithmus an.

SHA256
Gibt den SHA256-Hash-Algorithmus an.

SHA384
Gibt den Hash-Algorithmus SHA384 an.

SHA512
Gibt den Hash-Algorithmus SHA512 an.

PinRequestErrorType

Chrome 57 und 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 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 ein PUK-Code ist.

PinResponseDetails

Chrome 57 und höher

Attribute

  • userInput

    String optional

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

ReportSignatureDetails

Chrome 86 und 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, falls sie erfolgreich generiert wurde.

RequestPinDetails

Chrome 57 und höher

Attribute

  • attemptsLeft

    number optional

    Die Anzahl der verbleibenden Versuche. So können diese Informationen auf jeder Benutzeroberfläche angezeigt werden. Chrome sollte dies nicht erzwingen. Stattdessen sollte die Erweiterung „stopPinRequest“ mit „errorType“ = „MAX_ATTEMPTS_EXCEEDED“ aufrufen, wenn die Anzahl der PIN-Anfragen überschritten wird.

  • errorType

    PinRequestErrorType optional

    Die Fehlervorlage, die dem Nutzer angezeigt wird. Dieser Wert 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 angeforderte Codetyp. Standardmäßig ist „PIN“ ausgewählt.

  • signRequestId

    Zahl

    Die von Chrome in SignRequest angegebene ID.

SetCertificatesDetails

Chrome 86 und höher

Attribute

  • certificatesRequestId

    number optional

    Wenn sie als Antwort auf onCertificatesUpdateRequested aufgerufen wird, sollte sie den empfangenen certificatesRequestId-Wert enthalten. 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 zutreffend). Dieser Fehler wird dem Nutzer gegebenenfalls angezeigt.

SignatureRequest

Chrome 86 und höher

Attribute

  • Algorithmus

    Algorithmus

    Der zu verwendende 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 werden 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 und höher

    Die eindeutige ID, die von der Erweiterung verwendet werden soll, wenn eine Methode aufgerufen werden muss, für die sie erforderlich ist, z.B. requestPin.

StopPinRequestDetails

Chrome 57 und höher

Attribute

  • errorType

    PinRequestErrorType optional

    Die Fehlervorlage. Wenn vorhanden, wird sie dem Nutzer angezeigt. Enthält den Grund für das Beenden des Ablaufs, falls dies durch einen Fehler verursacht wurde, z.B. MAX_ATTEMPTS_EXCEEDED.

  • signRequestId

    Zahl

    Die von Chrome in SignRequest angegebene ID.

Methoden

reportSignature()

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

Wird als Antwort auf onSignatureRequested aufgerufen.

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

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

requestPin()

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

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

Parameter

Ausgabe

  • Promise<PinResponseDetails | undefined>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

setCertificates()

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

Legt eine Liste der Zertifikate fest, die im Browser verwendet werden sollen.

Die Erweiterung sollte diese Funktion nach der Initialisierung und bei jeder Änderung der derzeit verfügbaren Zertifikate aufrufen. Die Erweiterung sollte diese Funktion auch als Reaktion auf onCertificatesUpdateRequested aufrufen, sobald dieses Ereignis empfangen wird.

Parameter

  • Die zu setzenden Zertifikate. Ungültige Zertifikate werden ignoriert.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Ausgabe

  • Promise<void>

    Chrome 96 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

stopPinRequest()

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

Stoppt die von der Funktion requestPin gestartete Markierungsanfrage.

Parameter

  • 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 und höher

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks sind für die Abwärtskompatibilität verfügbar. Sie können nicht beide für denselben Funktionsaufruf verwenden. Das Versprechen wird mit demselben Typ aufgelöst, der an den Rückruf übergeben wird.

Ereignisse

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.

Parameter

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 Zertifikat signieren muss, das von dieser Erweiterung über setCertificates bereitgestellt wird.

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

Parameter