chrome.enterprise.platformKeys

Beschreibung

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

Berechtigungen

enterprise.platformKeys

Verfügbarkeit

Konzepte und Nutzung

Die typische Verwendung dieser API zum Registrieren eines Clientzertifikats sieht so aus:

  • 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 Tokenmethode generateKey() (in SubtleCrypto definiert). Dadurch wird der Handle zum Schlüssel zurückgegeben.

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

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

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

  • Wenn du ein Zertifikat erhalten hast, importiere es mit [enterprise.platformKeys.importCertificate()`[3]]

Das folgende Beispiel zeigt die grundlegende API-Interaktion mit Ausnahme des Erstellens und Sendens der Zertifizierungsanforderung:

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

Typ des zu generierenden Schlüssels.

Enum

ChallengeKeyOptions

Chrome 110 oder höher

Attribute

  • Challenge

    ArrayBuffer

    Eine von der Verified Access Web API ausgegebene Identitätsbestätigung.

  • registerKey

    RegisterKeyOptions optional

    Falls vorhanden, wird der angeforderte Schlüssel mit dem angegebenen scope-Token registriert. Der Schlüssel kann dann mit einem Zertifikat verknüpft und wie jeder andere Signaturschlüssel verwendet werden. Die nachfolgenden Aufrufe dieser Funktion generieren dann einen neuen Enterprise-Schlüssel im angegebenen scope.

  • Bereich

    Scope (Bereich)

    Welcher Enterprise-Schlüssel ist für Sie geeignet?

RegisterKeyOptions

Chrome 110 oder höher

Attribute

  • Algorithmus

    Algorithmus

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

Scope

Chrome 110 oder höher

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

Enum

"MACHINE"

Token

Attribute

  • id

    String

    Kennzeichnet diese Token eindeutig.

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97 oder höher

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

    Es können nur nicht-extrahierbare RSASSA-PKCS1-V1_5-Schlüssel mit modulusLength bis 2048 generiert werden. Jeder Schlüssel kann höchstens einmal zum Signieren von Daten verwendet werden.

    Für ein bestimmtes Token generierte Schlüssel können weder mit anderen Tokens noch mit window.crypto.subtle verwendet werden. Ebenso können mit window.crypto.subtle erstellte Key-Objekte nicht auf dieser Oberfläche 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 RSASSA-PKCS1-V1_5-Schlüssel mit modulusLength bis 2048 und ECDSA mit namedCurve P-256 generiert werden. Jeder Schlüssel kann höchstens einmal zum Signieren von Daten verwendet werden.

    Für ein bestimmtes Token generierte Schlüssel können weder mit anderen Tokens noch mit window.crypto.subtle verwendet werden. Ebenso können mit window.crypto.subtle erstellte Key-Objekte nicht auf dieser Oberfläche verwendet werden.

Methoden

challengeKey()

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 hardwarebasierten Enterprise-Maschinenschlüssel heraus und gibt die Antwort als Teil eines Remote Attestationsprotokolls aus. Dies ist nur unter Chrome OS und in Verbindung mit der Verified Access Web API nützlich, die sowohl fordert als auch Antworten überprüft.

Eine erfolgreiche Bestätigung über die Verified Access Web API ist ein starkes Signal dafür, dass das aktuelle Gerät ein legitimes Chrome OS-Gerät ist, dass das aktuelle Gerät von der bei der Überprüfung angegebenen Domain verwaltet wird, der aktuell angemeldete Nutzer von der während der Bestätigung angegebenen Domain verwaltet wird und der aktuelle Gerätestatus den Geräterichtlinien des Unternehmens entspricht. Eine Richtlinie kann beispielsweise festlegen, dass sich das Gerät nicht im Entwicklermodus befinden darf. Die Geräteidentität, die bei der Überprüfung ausgegeben wird, ist eng an die Hardware des aktuellen Geräts gebunden. Wenn der "user"-Bereich angegeben ist, ist die Identität außerdem eng an den aktuell angemeldeten Nutzer gebunden.

Diese Funktion ist streng eingeschränkt und funktioniert nicht, wenn das aktuelle Gerät nicht verwaltet wird, der aktuelle Nutzer nicht verwaltet wird oder dieser Vorgang nicht explizit durch die Geräterichtlinien des Unternehmens für den Aufrufer aktiviert wurde. Der unsichere Schlüssel befindet sich nicht im "system"- oder "user"-Token und ist mit keiner anderen API zugänglich.

Parameters

  • Objekt mit den in ChallengeKeyOptions definierten Feldern.

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (response: ArrayBuffer)=>void

    • Antwort

      ArrayBuffer

      Die Herausforderungsantwort.

challengeMachineKey()

Chrome 50 oder höher Seit Chrome 110 eingestellt
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback: function,
)

Verwenden Sie stattdessen challengeKey.

Fordert einen hardwarebasierten Enterprise-Maschinenschlüssel heraus und gibt die Antwort als Teil eines Remote Attestationsprotokolls aus. Dies ist nur unter Chrome OS und in Verbindung mit der Verified Access Web API nützlich, die sowohl fordert als auch Antworten überprüft. Eine erfolgreiche Bestätigung mit der Verified Access Web API ist ein starkes Signal für Folgendes: * Das aktuelle Gerät ist ein legitimes Chrome OS-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 Überprüfung angegeben wurde. * Der aktuelle Gerätestatus entspricht den Geräterichtlinien für Unternehmen. Eine Richtlinie kann beispielsweise festlegen, dass sich das Gerät nicht im Entwicklermodus befinden darf. * Die bei der Überprüfung ausgegebene Geräteidentität ist eng an die Hardware des aktuellen Geräts gebunden. Diese Funktion ist streng eingeschränkt und funktioniert nicht, wenn das aktuelle Gerät nicht verwaltet wird, der aktuelle Nutzer nicht verwaltet wird oder dieser Vorgang nicht explizit durch die Geräterichtlinien des Unternehmens für den Aufrufer aktiviert wurde. Der Enterprise-Maschinenschlüssel befindet sich nicht im "system"-Token und ist mit keiner anderen API zugänglich.

Parameters

  • Challenge

    ArrayBuffer

    Eine von der Verified Access Web API ausgegebene Identitätsbestätigung.

  • registerKey

    Boolescher Wert optional

    Chrome 59 und höher

    Wenn festgelegt, wird der aktuelle Enterprise-Maschinenschlüssel mit dem "system"-Token registriert und die Rolle des Enterprise-Maschinenschlüssels wird aufgehoben. 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. Die nachfolgenden Aufrufe dieser Funktion generieren dann einen neuen Enterprise-Maschinenschlüssel.

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (response: ArrayBuffer)=>void

    • Antwort

      ArrayBuffer

      Die Herausforderungsantwort.

challengeUserKey()

Chrome 50 oder höher Seit Chrome 110 eingestellt
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback: function,
)

Verwenden Sie stattdessen challengeKey.

Fordert einen hardwaregestützten Enterprise-Nutzerschlüssel heraus und gibt die Antwort als Teil eines Remote Attestationsprotokolls aus. Dies ist nur unter Chrome OS und in Verbindung mit der Verified Access Web API nützlich, die sowohl fordert als auch Antworten überprüft. Eine erfolgreiche Bestätigung mit der Verified Access Web API ist ein starkes Signal für Folgendes: * Das aktuelle Gerät ist ein legitimes Chrome OS-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 Überprüfung angegeben wurde. * Der aktuelle Gerätestatus entspricht den Richtlinien für Unternehmensnutzer. Eine Richtlinie kann beispielsweise festlegen, dass sich das Gerät nicht im Entwicklermodus befinden darf. * Der bei der 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 streng eingeschränkt und funktioniert nicht, wenn das aktuelle Gerät nicht verwaltet wird, der aktuelle Nutzer nicht verwaltet wird oder 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 mit keiner anderen API zugänglich.

Parameters

  • Challenge

    ArrayBuffer

    Eine von der Verified Access Web API ausgegebene Identitätsbestätigung.

  • registerKey

    boolean

    Wenn festgelegt, wird der aktuelle Enterprise-Nutzerschlüssel mit dem "user"-Token registriert und die Rolle des Enterprise-Nutzerschlü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. Die nachfolgenden Aufrufe dieser Funktion generieren dann einen neuen Enterprise-User-Schlüssel.

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (response: ArrayBuffer)=>void

    • Antwort

      ArrayBuffer

      Die Herausforderungsantwort.

getCertificates()

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 zu prüfen, ob Clientzertifikate vorhanden sind oder ablaufen, die für eine bestimmte Authentifizierung verwendet werden können.

Parameters

  • tokenId

    String

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

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (certificates: ArrayBuffer[])=>void

    • Zertifikate

      Array-Zwischenspeicher[]

      Die Liste der Zertifikate, jedes in DER-Codierung eines X.509-Zertifikats.

getTokens()

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

Gibt die verfügbaren Tokens zurück. Bei einer normalen 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 gleich (z.B. ein Chromebook).

Parameters

  • callback

    Funktion

    Der Parameter callback sieht so aus: 

    (tokens: Token[])=>void

    • Tokens

      Token[]

      Die Liste der verfügbaren Tokens.

importCertificate()

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

Parameters

  • 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

removeCertificate()

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

Parameters

  • 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