browser.enterprise.platformKeys

Beschreibung

Verwenden Sie die chrome.enterprise.platformKeys API, um Schlüssel zu generieren und Zertifikate für diese Schlüssel zu installieren. Die Zertifikate werden von der Plattform verwaltet und können für die TLS-Authentifizierung, den Netzwerkzugriff oder von anderen Erweiterungen über chrome.platformKeys verwendet werden.

Berechtigungen

enterprise.platformKeys

Verfügbarkeit

Konzepte und Verwendung

Die typische Verwendung dieser API zum Registrieren eines Clientzertifikats umfasst die folgenden Schritte:

  • Rufen Sie alle verfügbaren Tokens mit enterprise.platformKeys.getTokens() ab.

  • Suchen Sie das Token, bei dem id gleich "user" ist. Verwenden Sie dieses Token anschließend.

  • Generieren Sie ein Schlüsselpaar mit der generateKey()-Token-Methode (definiert in SubtleCrypto). Dadurch wird ein Handle für den Schlüssel zurückgegeben.

  • Exportieren Sie den öffentlichen Schlüssel mit der exportKey()-Token-Methode (definiert in SubtleCrypto).

  • Erstellen Sie die Signatur der Daten der Zertifizierungsanfrage mit der sign()-Token-Methode (definiert in SubtleCrypto).

  • Füllen Sie die Zertifizierungsanfrage aus und senden Sie sie an die Zertifizierungsstelle.

  • Wenn ein Zertifikat empfangen wird, importieren Sie es mit [enterprise.platformKeys.importCertificate()`[3]

Hier ist ein Beispiel, das die wichtigsten API-Interaktionen zeigt, mit Ausnahme des Erstellens und Sendens der Zertifizierungsanfrage:

function getUserToken(callback) {
  browser.enterprise.platformKeys.getTokens(function(tokens) {
    for (var i = 0; i < tokens.length; i++) {
      if (tokens[i].id == "user") {
        callback(tokens[i]);
        return;
      }
    }
    callback(undefined);
  });
}

function generateAndSign(userToken) {
  var data = new Uint8Array([0, 5, 1, 2, 3, 4, 5, 6]);
  var algorithm = {
    name: "RSASSA-PKCS1-v1_5",
    // RsaHashedKeyGenParams
    modulusLength: 2048,
    publicExponent:
        new Uint8Array([0x01, 0x00, 0x01]),  // Equivalent to 65537
    hash: {
      name: "SHA-256",
    }
  };
  var cachedKeyPair;
  userToken.subtleCrypto.generateKey(algorithm, false, ["sign"])
    .then(function(keyPair) {
            cachedKeyPair = keyPair;
            return userToken.subtleCrypto.exportKey("spki", keyPair.publicKey);
          },
          console.log.bind(console))
    .then(function(publicKeySpki) {
            // Build the Certification Request using the public key.
            return userToken.subtleCrypto.sign(
                {name : "RSASSA-PKCS1-v1_5"}, cachedKeyPair.privateKey, data);
          },
          console.log.bind(console))
    .then(function(signature) {
              // Complete the Certification Request with |signature|.
              // Send out the request to the CA, calling back
              // onClientCertificateReceived.
          },
          console.log.bind(console));
}

function onClientCertificateReceived(userToken, certificate) {
  browser.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

Typen

Algorithm

Chrome 110 und höher browser.* seit Chrome 148

Typ des zu generierenden Schlüssels.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 und höher browser.* seit Chrome 148

Attribute

  • Challenge

    ArrayBuffer

    Eine Challenge, die von der Bestätigter Zugriff Web API ausgegeben wird.

  • registerKey

    RegisterKeyOptions optional

    Falls vorhanden, wird der angeforderte Schlüssel mit dem Token des angegebenen scope registriert. Der Schlüssel kann dann mit einem Zertifikat verknüpft und wie jeder andere Signaturschlüssel verwendet werden. Bei nachfolgenden Aufrufen dieser Funktion wird dann ein neuer Enterprise-Schlüssel im angegebenen scope generiert.

  • Bereich

    Einsatzbereich

    Welcher Enterprise-Schlüssel soll geprüft werden?

RegisterKeyOptions

Chrome 110 und höher browser.* seit Chrome 148

Attribute

  • Algorithmus

    Algorithmus

    Welcher Algorithmus für den registrierten Schlüssel verwendet werden soll.

Scope

Chrome 110 und höher browser.* seit Chrome 148

Gibt an, ob der Unternehmensnutzerschlüssel oder der Enterprise-Computerschlüssel verwendet werden soll.

Enum

"USER"

"MACHINE"

Token

Attribute

  • id

    String

    Eindeutige Kennung für diese Token.

    Statische IDs sind "user" und "system" und beziehen sich auf das nutzerspezifische bzw. systemweite Hardware-Token der Plattform. Alle anderen Tokens (mit anderen Kennungen) werden möglicherweise von enterprise.platformKeys.getTokens zurückgegeben.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 und höher browser.* seit Chrome 148

    Implementiert die SubtleCrypto-Schnittstelle von WebCrypto. Die kryptografischen Vorgänge, einschließlich der Schlüsselgenerierung, sind softwaregestützt. Der Schutz der Schlüssel und damit die Implementierung der nicht extrahierbaren Eigenschaft erfolgt in der Software. Die Schlüssel sind also weniger geschützt als hardwaregestützte Schlüssel.

    Es können nur nicht extrahierbare Schlüssel generiert werden. Der einzige unterstützte Schlüsseltyp ist RSASSA-PKCS1-V1_5 mit modulusLength bis zu 2048. Jeder Schlüssel kann höchstens einmal zum Signieren von Daten verwendet werden, es sei denn, die Erweiterung ist über die Richtlinie „KeyPermissions“ auf der Zulassungsliste. In diesem Fall kann der Schlüssel unbegrenzt verwendet werden.

    Schlüssel, die auf einem bestimmten Token generiert wurden, können nicht mit anderen Tokens oder mit window.crypto.subtle verwendet werden. Ebenso können Key-Objekte, die mit window.crypto.subtle erstellt wurden, nicht mit dieser Schnittstelle verwendet werden.

  • subtleCrypto

    SubtleCrypto

    Implementiert die SubtleCrypto-Schnittstelle von WebCrypto. Die kryptografischen Vorgänge, einschließlich der Schlüsselgenerierung, sind hardwaregestützt.

    Es können nur nicht extrahierbare Schlüssel generiert werden. Die unterstützten Schlüsseltypen sind RSASSA-PKCS1-V1_5 mit modulusLength bis zu 2048 und ECDSA mit namedCurve P-256. Jeder Schlüssel kann höchstens einmal zum Signieren von Daten verwendet werden, es sei denn, die Erweiterung ist in der Richtlinie „KeyPermissions“ auf der Zulassungsliste aufgeführt. In diesem Fall kann der Schlüssel unbegrenzt verwendet werden.

    Schlüssel, die auf einem bestimmten Token generiert wurden, können nicht mit anderen Tokens oder mit window.crypto.subtle verwendet werden. Ebenso können Key-Objekte, die mit window.crypto.subtle erstellt wurden, nicht mit dieser Schnittstelle verwendet werden.

Methoden

challengeKey()

Chrome 110 und höher browser.* seit Chrome 148 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

Ähnlich wie challengeMachineKey und challengeUserKey, ermöglicht aber die Angabe des Algorithmus eines registrierten Schlüssels. Fordert einen hardwaregestützten Enterprise-Maschinenschlüssel an und gibt die Antwort als Teil eines Remote-Attestierungsprotokolls aus. Nur unter ChromeOS und in Verbindung mit der Verified Access Web API nützlich, die sowohl Challenges ausgibt als auch Antworten verifiziert.

Eine erfolgreiche Bestätigung durch die Verified Access Web API ist ein starkes Signal dafür, dass das aktuelle Gerät ein legitimes ChromeOS-Gerät ist, das aktuelle Gerät von der bei der Bestätigung angegebenen Domain verwaltet wird, der aktuell angemeldete Nutzer von der bei der Bestätigung angegebenen Domain verwaltet wird und der aktuelle Gerätestatus den Geräterichtlinien des Unternehmens entspricht. In einer Richtlinie kann beispielsweise festgelegt sein, dass sich das Gerät nicht im Entwicklermodus befinden darf. Jede Geräte-Identität, die bei der Überprüfung ausgegeben wird, ist eng an die Hardware des aktuellen Geräts gebunden. Wenn der Bereich "user" angegeben ist, ist die Identität auch eng an den aktuell angemeldeten Nutzer gebunden.

Diese Funktion ist stark eingeschränkt und schlägt fehl, wenn das aktuelle Gerät oder der aktuelle Nutzer nicht verwaltet wird oder wenn dieser Vorgang nicht explizit für den Aufrufer durch die Geräterichtlinie des Unternehmens aktiviert wurde. Der angeforderte Schlüssel befindet sich nicht im "system"- oder "user"-Token und ist über keine andere API zugänglich.

Parameter

Ausgabe

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit der Challenge-Antwort aufgelöst wird.

challengeMachineKey()

Chrome 50 und höher browser.* seit Chrome 148 Eingestellt seit Chrome 110
browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

Verwenden Sie stattdessen challengeKey.

Fordert einen hardwaregestützten Enterprise-Maschinenschlüssel an und gibt die Antwort als Teil eines Remote-Attestierungsprotokolls aus. Nur unter ChromeOS und in Verbindung mit der Verified Access Web API nützlich, die sowohl Challenges ausgibt als auch Antworten verifiziert. Eine erfolgreiche Bestätigung durch die Verified Access Web API ist ein starkes Signal für Folgendes: * Das aktuelle Gerät ist ein legitimes ChromeOS-Gerät. * Das aktuelle Gerät wird von der Domain verwaltet, die bei der Bestätigung angegeben wurde. * Der aktuell angemeldete Nutzer wird von der Domain verwaltet, die bei der Bestätigung angegeben wurde. * Der aktuelle Gerätestatus entspricht der Geräterichtlinie des Unternehmens. In einer Richtlinie kann beispielsweise festgelegt sein, dass sich das Gerät nicht im Entwicklermodus befinden darf. * Alle Geräte-Identitäten, die bei der Bestätigung ausgegeben werden, sind eng an die Hardware des aktuellen Geräts gebunden. Diese Funktion ist stark eingeschränkt und schlägt fehl, wenn das aktuelle Gerät oder der aktuelle Nutzer nicht verwaltet wird oder wenn dieser Vorgang nicht explizit für den Aufrufer durch die Geräterichtlinie des Unternehmens aktiviert wurde. Der Enterprise Machine Key befindet sich nicht im "system"-Token und ist für keine andere API zugänglich.

Parameter

  • Challenge

    ArrayBuffer

    Eine Challenge, die von der Bestätigter Zugriff Web API ausgegeben wird.

  • registerKey

    Boolesch optional

    Chrome 59 oder höher browser.* seit Chrome 148

    Wenn diese Option festgelegt ist, wird der aktuelle Enterprise-Maschinenschlüssel mit dem Token "system" registriert und die Rolle des Enterprise-Maschinenschlüssels wird aufgegeben. Der Schlüssel kann dann mit einem Zertifikat verknüpft und wie jeder andere Signaturschlüssel verwendet werden. Dieser Schlüssel ist ein 2048-Bit-RSA-Schlüssel. Bei nachfolgenden Aufrufen dieser Funktion wird dann ein neuer Enterprise-Maschinenschlüssel generiert.

Ausgabe

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit der Challenge-Antwort aufgelöst wird.

challengeUserKey()

Chrome 50 und höher browser.* seit Chrome 148 Eingestellt seit Chrome 110
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

Verwenden Sie stattdessen challengeKey.

Fordert einen hardwaregestützten Unternehmensnutzerschlüssel an und gibt die Antwort als Teil eines Remote-Attestation-Protokolls aus. Nur unter ChromeOS und in Verbindung mit der Verified Access Web API nützlich, die sowohl Challenges ausgibt als auch Antworten verifiziert. Eine erfolgreiche Bestätigung durch die Verified Access Web API ist ein starkes Signal für Folgendes: * Das aktuelle Gerät ist ein legitimes ChromeOS-Gerät. * Das aktuelle Gerät wird von der Domain verwaltet, die bei der Bestätigung angegeben wurde. * Der aktuell angemeldete Nutzer wird von der Domain verwaltet, die bei der Bestätigung angegeben wurde. * Der aktuelle Gerätestatus entspricht der Unternehmensnutzerrichtlinie. In einer Richtlinie kann beispielsweise festgelegt sein, dass sich das Gerät nicht im Entwicklermodus befinden darf. * Der durch die Bestätigung ausgegebene öffentliche Schlüssel ist eng an die Hardware des aktuellen Geräts und an den aktuell angemeldeten Nutzer gebunden. Diese Funktion ist stark eingeschränkt und schlägt fehl, wenn das aktuelle Gerät oder der aktuelle Nutzer nicht verwaltet wird oder wenn dieser Vorgang nicht explizit für den Aufrufer durch die Unternehmensnutzerrichtlinie aktiviert wurde. Der Unternehmensnutzerschlüssel befindet sich nicht im "user"-Token und ist für keine andere API zugänglich.

Parameter

  • Challenge

    ArrayBuffer

    Eine Challenge, die von der Bestätigter Zugriff Web API ausgegeben wird.

  • registerKey

    boolean

    Wenn diese Option festgelegt ist, wird der aktuelle Unternehmensnutzerschlüssel mit dem "user"-Token registriert und die Rolle des Unternehmensnutzerschlüssels wird aufgegeben. Der Schlüssel kann dann mit einem Zertifikat verknüpft und wie jeder andere Signaturschlüssel verwendet werden. Dieser Schlüssel ist ein 2048-Bit-RSA-Schlüssel. Bei nachfolgenden Aufrufen dieser Funktion wird dann ein neuer Unternehmensnutzerschlüssel generiert.

Ausgabe

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit der Challenge-Antwort aufgelöst wird.

getCertificates()

browser.enterprise.platformKeys.getCertificates(
  tokenId: string,
): Promise<ArrayBuffer[]>

Gibt die Liste aller Clientzertifikate zurück, die über das angegebene Token verfügbar sind. Kann verwendet werden, um das Vorhandensein und den Ablauf von Clientzertifikaten zu prüfen, die für eine bestimmte Authentifizierung verwendet werden können.

Parameter

  • tokenId

    String

    Die ID eines Tokens, das von getTokens zurückgegeben wird.

Ausgabe

  • Promise<ArrayBuffer[]>

    Chrome 131+ browser.* seit Chrome 148

    Gibt ein Promise zurück, das mit der Liste der verfügbaren Zertifikate aufgelöst wird.

getTokens()

browser.enterprise.platformKeys.getTokens(): Promise<Token[]>

Gibt die verfügbaren Tokens zurück. In der Sitzung eines regulären Nutzers enthält die Liste immer das Token des Nutzers mit id "user". Wenn ein systemweites TPM-Token verfügbar ist, enthält die zurückgegebene Liste auch das systemweite Token mit id "system". Das systemweite Token ist für alle Sitzungen auf diesem Gerät (z.B. einem Chromebook) gleich.

Ausgabe

  • Promise<Token[]>

    Chrome 131+ browser.* seit Chrome 148

    Wird von getTokens mit der Liste der verfügbaren Tokens aufgerufen.

importCertificate()

browser.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

Importiert certificate in das angegebene Token, wenn der zertifizierte Schlüssel bereits in diesem Token gespeichert ist. Nach einer erfolgreichen Zertifizierungsanfrage sollte diese Funktion verwendet werden, um das erhaltene Zertifikat zu speichern und es dem Betriebssystem und dem Browser für die Authentifizierung zur Verfügung zu stellen.

Parameter

  • tokenId

    String

    Die ID eines Tokens, das von getTokens zurückgegeben wird.

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats.

Ausgabe

  • Promise<void>

    Chrome 131+ browser.* seit Chrome 148

    Gibt ein Promise zurück, das aufgelöst wird, wenn dieser Vorgang abgeschlossen ist.

removeCertificate()

browser.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
): Promise<void>

Entfernt certificate aus dem angegebenen Token, falls vorhanden. Sollte verwendet werden, um veraltete Zertifikate zu entfernen, damit sie bei der Authentifizierung nicht berücksichtigt werden und die Zertifikatsauswahl nicht unübersichtlich machen. Sollte verwendet werden, um Speicherplatz im Zertifikatsspeicher freizugeben.

Parameter

  • tokenId

    String

    Die ID eines Tokens, das von getTokens zurückgegeben wird.

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats.

Ausgabe

  • Promise<void>

    Chrome 131+ browser.* seit Chrome 148

    Gibt ein Promise zurück, das aufgelöst wird, wenn dieser Vorgang abgeschlossen ist.