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
Konzepte und Nutzung
Für die Verwendung dieser API werden normalerweise die folgenden Schritte verwendet, um Clientzertifikate für ChromeOS verfügbar zu machen:
- Die Erweiterung wird für die Ereignisse
onCertificatesUpdateRequested
undonSignatureRequested
registriert. - Die Erweiterung ruft
setCertificates()
auf, um nach der Initialisierung eine anfängliche Liste von Zertifikaten 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. Bei einem
onCertificatesUpdateRequested
-Ereignis fordert der Browser die Erweiterung auf, alle derzeit bereitgestellten Zertifikate zu melden. - Die Erweiterung meldet mit der Methode
setCertificates()
die aktuell verfügbaren Zertifikate. - 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 zur Zertifikatsauswahl](https://developer.chrome.com/static/docs/extensions/reference/api/images/certificate_provider_selection_dialog.png?authuser=6&hl=de)
- Wenn der Nutzer die Authentifizierung abbricht oder kein Zertifikat mit der Anfrage übereinstimmt, wird die TLS-Clientauthentifizierung abgebrochen.
- Falls 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 ein DigestInfo vorangestellt und das Ergebnis vor der eigentlichen Signatur 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, vervollständigt der Browser den TLS-Handshake.
Die tatsächliche Abfolge der Schritte kann davon abweichen. Beispielsweise wird der Nutzer 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 das 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
Arten unterstützter kryptografischer Signaturalgorithmen.
Enum
"RSASSA_PKCS1_v1_5_MD5_SHA1"
Gibt den Signaturalgorithmus RSASSA PKCS#1 v1.5 mit dem MD5-SHA-1-Hash an. Der Erweiterung darf kein DigestInfo-Präfix vorangestellt werden, sondern nur ein PKCS#1-Padding. Dieser Algorithmus wurde eingestellt und wird ab Version 109 nie 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 SHA-256-Hash-Funktion 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 Funktion zur MGF1-Maskengenerierung und dem Salt von derselben Größe wie der Hash an.
"RSASSA_PSS_SHA384"
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-384-Hash-Funktion, der Funktion zur MGF1-Maskengenerierung und dem Salt von derselben Größe wie der Hash an.
"RSASSA_PSS_SHA512"
Gibt den RSASSA-PSS-Signaturalgorithmus mit der SHA-512-Hashfunktion, der Funktion zur MGF1-Maskengenerierung und dem Salt von derselben Größe wie der Hash an.
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 nach Signaturen von Digests gefragt, die mit einem dieser Hash-Algorithmen berechnet wurden. Dies sollte in der abnehmenden Reihenfolge der Hash-Einstellung erfolgen.
CertificatesUpdateRequest
Attribute
-
certificatesRequestId
Zahl
Anfrage-ID, die an
setCertificates
übergeben werden soll
ClientCertificateInfo
Attribute
-
certificateChain
Array-Zwischenspeicher[]
Das Array muss als erstes Element die DER-Codierung des X.509-Clientzertifikats enthalten.
Es muss genau ein Zertifikat enthalten sein.
-
supportedAlgorithms
Alle für dieses Zertifikat unterstützten Algorithmen. Die Erweiterung fragt nur über einen dieser Algorithmen nach Signaturen.
Error
Fehlertypen, die von der Erweiterung gemeldet werden können.
Wert
"GENERAL_ERROR"
Hash
Veraltet. Ersetzt durch Algorithm
.
Enum
"MD5_SHA1"
Gibt den MD5- und SHA1-Hash-Algorithmus 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
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 an Versuchen überschritten wurde.
"UNKNOWN_ERROR"
Gibt an, dass der Fehler nicht durch die oben genannten Typen dargestellt werden kann.
PinRequestType
Der Codetyp, der von der Erweiterung mit der requestPin-Funktion angefordert wird.
Enum
"PIN"
Gibt an, dass es sich bei dem angeforderten Code um eine PIN handelt.
"PUK"
Gibt an, dass es sich bei dem angeforderten Code um einen PUK handelt.
PinResponseDetails
Attribute
-
userInput
String optional
Der vom Nutzer bereitgestellte Code. Leer, wenn der Nutzer das Dialogfeld geschlossen hat oder ein anderer Fehler aufgetreten ist.
ReportSignatureDetails
Attribute
-
error
"GENERAL_ERROR"
optionalFehler, 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 erstellt wurde.
RequestPinDetails
Attribute
-
attemptsLeft
Nummer optional
Die Anzahl der verbleibenden Versuche. Dies ist erforderlich, damit diese Informationen dem Nutzer auf jeder Benutzeroberfläche präsentiert werden können. Es wird davon ausgegangen, dass Chrome dies nicht erzwingt. Stattdessen sollte stopPinRequest von der Erweiterung mit dem Fehlertyp „errorType = MAX_ATTEMPTS_EXCEEDED“ aufgerufen werden, wenn die Anzahl der PIN-Anfragen überschritten wird.
-
errorType
PinRequestErrorType optional
Die Fehlervorlage, die dem Nutzer angezeigt wird. Diese sollte festgelegt werden, wenn die vorherige Anfrage fehlgeschlagen ist, um den Nutzer über den Grund für den Fehler zu informieren.
-
requestType
PinRequestType optional
Die Art des angeforderten Codes. Die Standardeinstellung ist PIN.
-
signRequestId
Zahl
Die von Chrome in SignRequest bereitgestellte ID.
SetCertificatesDetails
Attribute
-
certificatesRequestId
Nummer optional
Sollte beim Aufruf als Antwort auf
onCertificatesUpdateRequested
den empfangenencertificatesRequestId
-Wert enthalten. Andernfalls sollte sie nicht festgelegt werden. -
clientCertificates
Liste der derzeit verfügbaren Clientzertifikate.
-
error
"GENERAL_ERROR"
optionalFehler, der beim Extrahieren der Zertifikate (falls vorhanden) aufgetreten ist. Dieser Fehler wird dem Nutzer gegebenenfalls angezeigt.
SignatureRequest
Attribute
-
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 zu signierende Digest.
-
Hash
Bezieht sich auf den Hash-Algorithmus, mit dem
digest
erstellt wurde. -
signRequestId
Zahl
Chrome 57 und höherDie eindeutige ID, die von der Erweiterung verwendet wird, falls sie eine Methode aufrufen muss, die dies erfordert, z.B. „requestPin“.
StopPinRequestDetails
Attribute
-
errorType
PinRequestErrorType optional
Die Fehlervorlage. Falls vorhanden, wird es dem Nutzer angezeigt. Sie sollte den Grund für das Anhalten des Datenflusses enthalten, wenn dieser durch einen Fehler verursacht wurde, z.B. MAX_ATTEMPTS_EXCEEDED.
-
signRequestId
Zahl
Die von Chrome in SignRequest bereitgestellte ID.
Methoden
reportSignature()
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
-
Details
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
requestPin()
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 während eines anderen Ablaufs gestellt wurden, werden abgelehnt. Es liegt in der Verantwortung der Erweiterung, es später noch einmal zu versuchen, wenn ein anderer Ablauf läuft.
Parameter
-
Details
Enthält die Details zum angeforderten Dialogfeld.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:(details?: PinResponseDetails) => void
-
Details
PinResponseDetails optional
-
Rückgabe
-
Promise<PinResponseDetails | undefined>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
setCertificates()
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 in den aktuell verfügbaren Zertifikaten aufrufen. Die Erweiterung sollte diese Funktion außerdem jedes Mal als Antwort auf onCertificatesUpdateRequested
aufrufen, wenn dieses Ereignis empfangen wird.
Parameter
-
Details
Die festzulegenden Zertifikate. Ungültige Zertifikate werden ignoriert.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
stopPinRequest()
chrome.certificateProvider.stopPinRequest(
details: StopPinRequestDetails,
callback?: function,
)
Stoppt die von der Funktion requestPin
gestartete PIN-Anfrage.
Parameter
-
Details
Enthält die Details zum Grund für das Beenden des Anfrageflusses.
-
callback
Funktion optional
Der Parameter
callback
sieht so aus:() => void
Rückgabe
-
Promise<void>
Chrome 96 und höherPromise-Objekte werden in Manifest V3 und höher unterstützt, Callbacks werden jedoch aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können nicht beide in einem Funktionsaufruf verwenden. Das Promise wird mit demselben Typ aufgelöst, der an den Callback übergeben wird.
Veranstaltungen
onCertificatesRequested
chrome.certificateProvider.onCertificatesRequested.addListener(
callback: function,
)
Verwenden Sie stattdessen onCertificatesUpdateRequested
.
Dieses Ereignis wird jedes Mal ausgelöst, wenn der Browser die aktuelle Liste der Zertifikate anfordert, die von dieser Erweiterung bereitgestellt werden. 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
-
callback
Funktion
Der Parameter
callback
sieht so aus:(rejectedCertificates: ArrayBuffer[]) => void
-
rejectedCertificates
Array-Zwischenspeicher[]
-
-
-
onCertificatesUpdateRequested
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
-
onSignatureRequested
chrome.certificateProvider.onSignatureRequested.addListener(
callback: function,
)
Dieses Ereignis wird jedes Mal ausgelöst, wenn der Browser eine Nachricht mit einem von dieser Erweiterung über setCertificates
bereitgestellten Zertifikat signieren muss.
Die Erweiterung muss die Eingabedaten von request
mit dem entsprechenden Algorithmus und dem privaten Schlüssel signieren und durch Aufrufen von reportSignature
mit der empfangenen signRequestId
zurückgeben.
Parameter
-
callback
Funktion
Der Parameter
callback
sieht so aus:(request: SignatureRequest) => void
-
Anfrage
-
onSignDigestRequested
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 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
-
reportCallback
Funktion
Chrome 47 und höherDer Parameter
reportCallback
sieht so aus:(signature?: ArrayBuffer) => void
-
Signatur
ArrayBuffer optional
-
-