chrome.certificateProvider

Wichtig:Diese API funktioniert nur unter ChromeOS.

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

Nutzung

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 anzugeben.
• Die Erweiterung überwacht die Änderungen in der Liste der verfügbaren Zertifikate und ruft setCertificates auf, um den Browser über jede solche Änderung zu benachrichtigen.
• Während eines TLS-Handshakes erhält der Browser eine Clientzertifikatsanfrage. Bei einem Ereignis vom Typ onCertificatesUpdateRequested fordert der Browser die Erweiterung auf, alle Zertifikate zu melden, die sie derzeit bereitstellt.
• Die Erweiterung meldet die derzeit verfügbaren Zertifikate mithilfe 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.

• 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 Ereignis vom Typ onSignatureRequested 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

• Details

  ReportSignatureDetails

• callback

  function optional

  Der Parameter callback sieht so aus:

  () => void

Ausgabe

• Promise<void>

  Chrome 96 und höher

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

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

• Details

  RequestPinDetails

  Enthält die Details zum angeforderten Dialogfeld.

• callback

  function optional

  Der Parameter callback sieht so aus:

  (details?: PinResponseDetails) => void

  • Details

    PinResponseDetails optional

Ausgabe

• Promise<PinResponseDetails | undefined>

  Chrome 96 und höher

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

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

• Details

  SetCertificatesDetails

  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 nur für Manifest V3 und höher unterstützt. Auf anderen Plattformen müssen Callbacks verwendet werden.

stopPinRequest()

Versprechen Chrome 57 und höher

chrome.certificateProvider.stopPinRequest(
  details: StopPinRequestDetails,
  callback?: function,
)

Stoppt die von der Funktion requestPin gestartete Markierungsanfrage.

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

  Versprechen 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 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 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 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

• callback

  Funktion

  Der Parameter callback sieht so aus:

  (request: CertificatesUpdateRequest) => void

  • Anfrage

    CertificatesUpdateRequest

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

• 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 von dieser Erweiterung bereitgestellten Zertifikat signieren muss, als Antwort auf ein onCertificatesRequested-Ereignis. 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.

Parameter

• callback

  Funktion

  Der Parameter callback sieht so aus:

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

  • Anfrage

    SignRequest

  • reportCallback

    Funktion

    Chrome 47 und höher

    Der Parameter reportCallback sieht so aus:

    (signature?: ArrayBuffer) => void

    • Signatur

      ArrayBuffer optional