chrome.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

So registrieren Sie ein Clientzertifikat mit dieser API:

  • 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 später.

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

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

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

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

  • Wenn ein Zertifikat empfangen wird, importiere 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) {
  chrome.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) {
  chrome.enterprise.platformKeys.importCertificate(userToken.id, certificate);
}

getUserToken(generateAndSign);

Typen

Algorithm

Chrome 110 oder höher

Zu generierende Schlüsselart.

Enum

ChallengeKeyOptions

Chrome 110 und höher

Attribute

  • Challenge

    ArrayBuffer

    Eine Herausforderung, die von der Verified Access Web API gesendet wird.

  • registerKey

    RegisterKeyOptions optional

    Falls vorhanden, wird der abgefragte 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

    Ebene

    Welcher Enterprise Key infrage kommt.

RegisterKeyOptions

Chrome 110 und höher

Attribute

  • Algorithmus

    Algorithmus

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

Scope

Chrome 110 oder höher

Ob der Enterprise-Nutzerschlüssel oder der Enterprise-Rechnerschlüssel verwendet werden soll.

Enum

„USER“

Token

Attribute

  • id

    String

    Identifiziert dieses Token eindeutig.

    Statische IDs sind "user" und "system", die sich auf das nutzerspezifische und das systemweite Hardwaretoken der Plattform beziehen. Alle anderen Tokens (mit anderen Kennungen) können von enterprise.platformKeys.getTokens zurückgegeben werden.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 und höher

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

    Nur nicht extrahierbare RSASSA-PKCS1-V1_5-Schlüssel mit einer modulusLength bis 2.048 können generiert werden. Jeder Schlüssel kann nur einmal zum Signieren von Daten verwendet werden.

    Schlüssel, die auf einer bestimmten Token generiert wurden, können nicht mit anderen Tokens oder mit window.crypto.subtle verwendet werden. Mit window.crypto.subtle erstellte Key-Objekte können ebenfalls nicht mit dieser Benutzeroberfläche verwendet werden.

  • subtleCrypto

    SubtleCrypto

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

    Nur nicht extrahierbare RSASSA-PKCS1-V1_5-Schlüssel mit modulusLength bis 2048 und ECDSA mit namedCurve P-256 können generiert werden. Jeder Schlüssel kann zum Signieren von Daten höchstens einmal verwendet werden.

    Schlüssel, die auf einer bestimmten Token generiert wurden, können nicht mit anderen Tokens oder mit window.crypto.subtle verwendet werden. Mit window.crypto.subtle erstellte Key-Objekte können ebenfalls nicht mit dieser Benutzeroberfläche verwendet werden.

Methoden

challengeKey()

Versprechen Chrome 110 oder höher 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

Ä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 Identitätsbestätigungen als auch Antworten überprüft.

Eine erfolgreiche Überprüfung durch die Verified Access Web API ist ein starkes Signal dafür, dass es sich bei dem aktuellen Gerät um ein legitimes ChromeOS-Gerät handelt, dass es von der bei der Überprüfung angegebenen Domain verwaltet wird, dass der aktuell angemeldete Nutzer von der bei der Überprüfung angegebenen Domain verwaltet wird und dass der aktuelle Gerätestatus den Geräterichtlinien des Unternehmens entspricht. Beispielsweise kann in einer Richtlinie festgelegt sein, dass sich das Gerät nicht im Entwicklermodus befinden darf. Jede Geräteidentitä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 außerdem eng an den aktuell angemeldeten Nutzer gebunden.

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

Parameter

  • Objekt mit den in ChallengeKeyOptions definierten Feldern.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (response: ArrayBuffer) => void

    • Antwort

      ArrayBuffer

      Die Reaktion auf die Challenge.

Gibt Folgendes zurück:

  • Promise<ArrayBuffer>

    Ausstehend

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

challengeMachineKey()

Promise Chrome 50 und höher Ab Chrome 110 nicht mehr unterstützt
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

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 Identitätsbestätigungen als auch Antworten überprüft. Eine erfolgreiche Bestätigung durch die Verified Access Web API ist in folgenden Situationen ein starkes Signal: * 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 für Unternehmen. Beispielsweise kann in einer Richtlinie festgelegt sein, dass sich das Gerät nicht im Entwicklermodus befinden darf. * Jede Geräteidentität, die bei der Überprüfung ausgegeben wird, ist eng an die Hardware des aktuellen Geräts gebunden. Diese Funktion ist stark eingeschränkt und schlägt fehl, wenn das aktuelle Gerät nicht verwaltet wird, der aktuelle Nutzer nicht verwaltet wird oder wenn dieser Vorgang nicht explizit durch die Unternehmensrichtlinien für den Aufrufer aktiviert wurde. Der Enterprise-Maschinenschlüssel befindet sich nicht im "system"-Token und ist für keine andere API zugänglich.

Parameter

  • Challenge

    ArrayBuffer

    Eine Herausforderung, die von der Verified Access Web API gesendet wird.

  • registerKey

    boolescher Wert optional

    Chrome 59 und höher

    Wenn diese Option festgelegt ist, wird der aktuelle Enterprise-Maschinenschlüssel mit dem "system"-Token registriert und die Rolle „Enterprise-Maschinenschlüssel“ 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.

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (response: ArrayBuffer) => void

    • Antwort

      ArrayBuffer

      Die Reaktion auf die Challenge.

Gibt Folgendes zurück:

  • Promise<ArrayBuffer>

    Ausstehend

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

challengeUserKey()

Versprechen Chrome 50 oder höher Eingestellt seit Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

Verwenden Sie stattdessen challengeKey.

Fordert einen hardwaregestützten Enterprise-Nutzerschlü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 Herausforderungen stellt als auch Antworten überprüft. Eine erfolgreiche Bestätigung durch die Verified Access Web API ist in folgenden Situationen ein starkes Signal: * 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 den Richtlinien für Unternehmensnutzer. Eine Richtlinie kann beispielsweise angeben, dass sich das Gerät nicht im Entwicklermodus befinden darf. * Der öffentliche Schlüssel, der bei der Bestätigung ausgegeben wird, 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 nicht verwaltet wird, der aktuelle Nutzer nicht verwaltet wird oder wenn dieser Vorgang nicht explizit durch eine Unternehmensnutzerrichtlinie für den Aufrufer aktiviert wurde. Der Enterprise-Nutzerschlüssel befindet sich nicht im "user"-Token und ist für keine andere API zugänglich.

Parameter

  • Challenge

    ArrayBuffer

    Eine Herausforderung, die von der Verified Access Web API gesendet wird.

  • registerKey

    boolean

    Wenn festgelegt, wird der aktuelle Enterprise-Nutzerschlüssel mit dem "user"-Token registriert und die Rolle „Enterprise-Nutzerschlüssel“ wird entzogen. 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-Nutzerschlüssel generiert.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (response: ArrayBuffer) => void

    • Antwort

      ArrayBuffer

      Die Reaktion auf die Challenge.

Gibt Folgendes zurück:

  • Promise<ArrayBuffer>

    Ausstehend

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

getCertificates()

Promise 
chrome.enterprise.platformKeys.getCertificates(
  tokenId: string,
  callback?: function,
)

Gibt die Liste aller Clientzertifikate zurück, die für 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.

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    (certificates: ArrayBuffer[]) => void

    • Zertifikate

      ArrayBuffer[]

      Die Liste der Zertifikate mit jeweils DER-Codierung eines X.509-Zertifikats

Gibt Folgendes zurück:

  • Promise<ArrayBuffer[]>

    Ausstehend

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

getTokens()

Versprechen 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
)

Gibt die verfügbaren Tokens zurück. In einer regulären Nutzersitzung 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 (Gerät im Sinne von z.B. Chromebook) gleich.

Parameter

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    (tokens: Token[]) => void

    • Tokens

      Token[]

      Die Liste der verfügbaren Tokens.

Gibt Folgendes zurück:

  • Promise<Token[]>

    Ausstehend

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

importCertificate()

Versprechen 
chrome.enterprise.platformKeys.importCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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 für das Betriebssystem und den Browser zur Authentifizierung verfügbar zu machen.

Parameter

  • tokenId

    String

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

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats

  • callback

    function optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Ausstehend

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

removeCertificate()

Versprechen 
chrome.enterprise.platformKeys.removeCertificate(
  tokenId: string,
  certificate: ArrayBuffer,
  callback?: function,
)

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 überladen. Sollte verwendet werden, um Speicherplatz im Zertifikatspeicher freizugeben.

Parameter

  • tokenId

    String

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

  • Zertifikat

    ArrayBuffer

    Die DER-Codierung eines X.509-Zertifikats

  • callback

    Funktion optional

    Der Parameter callback sieht so aus: 

    () => void

Gibt Folgendes zurück:

  • Promise<void>

    Ausstehend

    Versprechen werden in Manifest V3 und höher unterstützt, aber Callbacks werden aus Gründen der Abwärtskompatibilität bereitgestellt. Sie können beide nicht für denselben Funktionsaufruf verwenden. Die Promise wird mit demselben Typ aufgelöst, der an das Callback übergeben wird.