chrome.certificateProvider

Beschreibung

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

Berechtigungen

certificateProvider

Verfügbarkeit

Chrome 46 und höher Nur ChromeOS

Konzepte und Verwendung

Die typische Verwendung dieser API zum Bereitstellen von Clientzertifikaten für ChromeOS 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 erhält der Browser eine Clientzertifikatsanfrage. Bei einem onCertificatesUpdateRequested-Ereignis fordert der Browser die Erweiterung auf, alle Zertifikate zu melden, die sie derzeit bereitstellt.
  • Die Erweiterung meldet die aktuell verfügbaren Zertifikate mit der Methode setCertificates() zurück.
  • Der Browser gleicht alle verfügbaren Zertifikate mit der Clientzertifikatsanfrage des Remotehosts ab. Die Übereinstimmungen werden dem Nutzer in einem Auswahlfeld präsentiert.
  • Der Nutzer kann ein Zertifikat auswählen und damit die Authentifizierung genehmigen oder abbrechen.
Dialogfeld für die Zertifikatsauswahl
Dialogfeld zur Zertifikatauswahl
  • 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, deklariert, 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 dem referenzierten Zertifikat zugeordnet ist. Zum Erstellen der Signatur muss möglicherweise ein DigestInfo vorangestellt und das Ergebnis vor der eigentlichen Signierung 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 Reihenfolge der Schritte kann abweichen. Der Nutzer wird beispielsweise nicht aufgefordert, ein Zertifikat auszuwählen, wenn die Unternehmensrichtlinie zum automatischen Auswählen 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 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

Typen der unterstützten kryptografischen Signaturalgorithmen.

Enum

"RSASSA_PKCS1_v1_5_MD5_SHA1"
Gibt den RSASSA PKCS#1 v1.5-Signaturalgorithmus mit dem MD5-SHA-1-Hashing an. Die Erweiterung darf kein DigestInfo-Präfix voranstellen, sondern nur PKCS#1-Padding hinzufügen. Dieser Algorithmus ist veraltet und wird ab Chrome-Version 109 nie 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-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 in der gleichen 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 in der gleichen 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 in der gleichen 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. Für diese Erweiterung werden nur Signaturen von Digests angefordert, die mit einem dieser Hash-Algorithmen berechnet wurden. Die Reihenfolge sollte absteigend nach Hash-Präferenz sein.

CertificatesUpdateRequest

Chrome 86 und höher

Attribute

  • certificatesRequestId

    Zahl

    Anfragekennung, 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.

    Sie muss genau ein Zertifikat enthalten.

  • supportedAlgorithms

    Algorithmus[]

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

Error

Chrome 86 und höher

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

Wert

"GENERAL_ERROR"

Hash

Verworfen. Ersetzt durch Algorithm.

Enum

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

„SHA1“
Gibt den SHA1-Hash-Algorithmus an.

„SHA256“
Gibt den SHA256-Hash-Algorithmus an.

"SHA384"
Gibt den SHA384-Hashalgorithmus an.

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

PinRequestErrorType

Chrome 57 und höher

Die Fehlertypen, 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 von der Erweiterung mit der Funktion „requestPin“ angeforderte Code.

Enum

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

„PUK“
Gibt an, dass der angeforderte Code ein PUK ist.

PinResponseDetails

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

Attribute

  • Fehler

    "GENERAL_ERROR"
     optional

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

  • signRequestId

    Zahl

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

  • Signatur

    ArrayBuffer optional

    Die Signatur, sofern sie erfolgreich generiert wurde.

RequestPinDetails

Chrome 57 und höher

Attribute

  • attemptsLeft

    number optional

    Die Anzahl der verbleibenden Versuche. So kann jede Benutzeroberfläche diese Informationen dem Nutzer präsentieren. Chrome soll dies 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. 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. Der Standardwert ist „PIN“.

  • signRequestId

    Zahl

    Die ID, die von Chrome in SignRequest angegeben wird.

SetCertificatesDetails

Chrome 86 und höher

Attribute

  • certificatesRequestId

    number optional

    Wenn die Funktion als Reaktion auf onCertificatesUpdateRequested aufgerufen wird, sollte sie den empfangenen certificatesRequestId-Wert enthalten. Andernfalls sollte sie nicht festgelegt werden.

  • 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 bei Bedarf 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 sind nicht gehasht.

  • signRequestId

    Zahl

    Anfragekennung, 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, 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 sie eine Methode aufrufen muss, für die sie erforderlich ist, z.B. „requestPin“.

StopPinRequestDetails

Chrome 57 und höher

Attribute

  • errorType

    PinRequestErrorType optional

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

  • signRequestId

    Zahl

    Die ID, die von Chrome in SignRequest angegeben wird.

Methoden

reportSignature()

Chrome 86 und höher 
chrome.certificateProvider.reportSignature(
  details: ReportSignatureDetails,
): Promise<void>

Sollte als Reaktion 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

Ausgabe

  • Promise<void>

    Chrome 96 und höher

requestPin()

Chrome 57 und höher 
chrome.certificateProvider.requestPin(
  details: RequestPinDetails,
): 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. Die Erweiterung muss es später noch einmal versuchen, wenn ein anderer Ablauf gerade ausgeführt wird.

Parameter

Ausgabe

setCertificates()

Chrome 86 und höher 
chrome.certificateProvider.setCertificates(
  details: SetCertificatesDetails,
): 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 Menge der derzeit verfügbaren Zertifikate aufrufen. Die Erweiterung sollte diese Funktion auch als Reaktion auf onCertificatesUpdateRequested aufrufen, wenn dieses Ereignis empfangen wird.

Parameter

Ausgabe

  • Promise<void>

    Chrome 96 und höher

stopPinRequest()

Chrome 57 und höher 
chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
): Promise<void>

Beendet die von der Funktion requestPin gestartete PIN-Anfrage.

Parameter

Ausgabe

  • Promise<void>

    Chrome 96 und höher

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 dem 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 aus request mit dem entsprechenden Algorithmus und privaten Schlüssel signieren und zurückgeben, indem sie reportSignature mit dem empfangenen signRequestId aufruft.

Parameter