browser.enterprise.platformKeys

Beschrijving

Gebruik de chrome.enterprise.platformKeys API om sleutels te genereren en certificaten voor deze sleutels te installeren. De certificaten worden beheerd door het platform en kunnen worden gebruikt voor TLS-verificatie, netwerktoegang of door andere extensies via chrome.platformKeys.

Rechten

enterprise.platformKeys

Beschikbaarheid

Alleen ChromeOS Beleid vereist

Concepten en gebruik

Het gebruikelijke gebruik van deze API om een clientcertificaat in te schrijven, bestaat uit deze stappen:

  • Haal alle beschikbare tokens op met enterprise.platformKeys.getTokens().

  • Zoek de token met id gelijk aan "user". Gebruik deze token daarna.

  • Genereer een sleutelpaar met de methode generateKey() Token (gedefinieerd in SubtleCrypto). Hiermee wordt de gebruikersnaam teruggezet naar de sleutel.

  • Exporteer de openbare sleutel met de exportKey()-tokenmethode (gedefinieerd in SubtleCrypto).

  • Maak de handtekening van de gegevens van het certificeringsverzoek met de methode sign() Token (gedefinieerd in SubtleCrypto).

  • Vul het certificeringsverzoek in en stuur het naar de certificeringsinstantie.

  • Als je een certificaat krijgt, importeer je het met [enterprise.platformKeys.importCertificate()`[3]

Hier is een voorbeeld van de belangrijkste API-interactie, behalve het maken en sturen van het certificeringsverzoek:

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 of hoger browser.* sinds Chrome 148

Het type sleutel dat je wilt genereren.

Enum

RSA

ECDSA

ChallengeKeyOptions

Chrome 110 of hoger browser.* sinds Chrome 148

Eigenschappen

  • challenge

    ArrayBuffer

    Een challenge zoals uitgegeven door de Verified Access Web API.

  • registerKey

    RegisterKeyOptions optioneel

    Als deze aanwezig is, wordt de gecontroleerde sleutel geregistreerd met de token van de opgegeven scope. De sleutel kan dan aan een certificaat worden gekoppeld en worden gebruikt zoals elke andere ondertekeningssleutel. Volgende aanroepen van deze functie genereren dan een nieuwe Enterprise-sleutel in de opgegeven scope.

  • bereik

    Bereik

    Welke zakelijke sleutel moet worden getest.

RegisterKeyOptions

Chrome 110 of hoger browser.* sinds Chrome 148

Eigenschappen

  • algoritme

    Algoritme

    Welk algoritme de geregistreerde sleutel moet gebruiken.

Scope

Chrome 110 of hoger browser.* sinds Chrome 148

Of de zakelijke gebruikerssleutel of de zakelijke machinesleutel moet worden gebruikt.

Enum

"USER"

MACHINE

Token

Eigenschappen

  • id

    tekenreeks

    Unieke ID voor deze Token.

    Statische ID's zijn "user" en "system", die respectievelijk verwijzen naar de gebruikersspecifieke en de systeembrede hardwaretoken van het platform. Andere tokens (met andere ID's) kunnen worden geretourneerd door enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97+ browser.* sinds Chrome 148

    Implementeert de SubtleCrypto-interface van WebCrypto. De cryptografische bewerkingen, waaronder het genereren van sleutels, worden ondersteund door software. De bescherming van de sleutels, en dus de implementatie van de niet-extraheerbare eigenschap, wordt uitgevoerd in software. De sleutels zijn dus minder beschermd dan hardware-ondersteunde sleutels.

    Alleen niet-extraheerbare sleutels kunnen worden gegenereerd. Het enige ondersteunde sleuteltype is RSASSA-PKCS1-V1_5 met modulusLength tot 2048. Elke sleutel kan maximaal één keer worden gebruikt om gegevens te ondertekenen, tenzij de extensie op de toelatingslijst staat via het KeyPermissions-beleid. In dat geval kan de sleutel onbeperkt worden gebruikt.

    Sleutels die zijn gegenereerd op een specifieke Token, kunnen niet worden gebruikt met andere tokens en ook niet met window.crypto.subtle. Ook kunnen Key-objecten die zijn gemaakt met window.crypto.subtle niet worden gebruikt met deze interface.

  • subtleCrypto

    SubtleCrypto

    Implementeert de SubtleCrypto-interface van WebCrypto. De cryptografische bewerkingen, waaronder het genereren van sleutels, worden hardware-ondersteund.

    Alleen niet-extraheerbare sleutels kunnen worden gegenereerd. De ondersteunde sleuteltypen zijn RSASSA-PKCS1-V1_5 met modulusLength tot 2048 en ECDSA met namedCurve P-256. Elke sleutel kan maximaal één keer worden gebruikt om gegevens te ondertekenen, tenzij de extensie op de toelatingslijst staat van het beleid KeyPermissions. In dat geval kan de sleutel onbeperkt worden gebruikt.

    Sleutels die zijn gegenereerd op een specifieke Token kunnen niet worden gebruikt met andere tokens en kunnen ook niet worden gebruikt met window.crypto.subtle. Key-objecten die zijn gemaakt met window.crypto.subtle, kunnen ook niet worden gebruikt met deze interface.

Methoden

challengeKey()

Chrome 110 of hoger browser.* sinds Chrome 148 
browser.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

Vergelijkbaar met challengeMachineKey en challengeUserKey, maar hiermee kun je het algoritme van een geregistreerde sleutel specificeren. Daagt een hardware-ondersteunde Enterprise Machine Key uit en stuurt de reactie als onderdeel van een protocol voor attest op afstand. Alleen nuttig op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen geeft als reacties verifieert.

Een geslaagde verificatie door de Verified Access Web API is een sterk signaal dat het huidige apparaat een legitiem ChromeOS-apparaat is, dat het huidige apparaat wordt beheerd door het domein dat tijdens de verificatie is opgegeven, dat de huidige ingelogde gebruiker wordt beheerd door het domein dat tijdens de verificatie is opgegeven en dat de huidige apparaatstatus voldoet aan het apparaatbeleid van het bedrijf. In een beleid kan bijvoorbeeld staan dat het apparaat niet in de ontwikkelaarsmodus mag staan. Elke apparaat-ID die door de verificatie wordt verstrekt, is nauw verbonden met de hardware van het huidige apparaat. Als het bereik "user" is opgegeven, is de identiteit ook nauw verbonden met de huidige ingelogde gebruiker.

Deze functie is zeer beperkt en mislukt als het huidige apparaat niet wordt beheerd, de huidige gebruiker niet wordt beheerd of als deze bewerking niet expliciet is aangezet voor de beller door het apparaatbeleid van het bedrijf. De betwiste sleutel bevindt zich niet in de "system"- of "user"-token en is niet toegankelijk via een andere API.

Parameters

Retourzendingen

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt omgezet met de challengereactie.

challengeMachineKey()

Chrome 50+ browser.* sinds Chrome 148 Beëindigd sinds Chrome 110
browser.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

Gebruik in plaats daarvan challengeKey.

Daagt een hardware-ondersteunde Enterprise Machine Key uit en stuurt de reactie als onderdeel van een protocol voor attest op afstand. Alleen nuttig op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen geeft als reacties verifieert. Een geslaagde verificatie door de Web-API voor geverifieerde toegang is een sterk signaal van het volgende: * Het huidige apparaat is een legitiem ChromeOS-apparaat. * Het huidige apparaat wordt beheerd door het domein dat is opgegeven tijdens de verificatie. * De huidige ingelogde gebruiker wordt beheerd door het domein dat is opgegeven tijdens de verificatie. * De huidige apparaatstatus voldoet aan het apparaatbeleid van het bedrijf. In een beleid kan bijvoorbeeld staan dat het apparaat niet in de ontwikkelaarsmodus mag staan. * Elke apparaat-ID die door de verificatie wordt verstrekt, is nauw verbonden met de hardware van het huidige apparaat. Deze functie is zeer beperkt en mislukt als het huidige apparaat niet wordt beheerd, de huidige gebruiker niet wordt beheerd of als deze bewerking niet expliciet is aangezet voor de beller door het apparaatbeleid van het bedrijf. De Enterprise Machine Key bevindt zich niet in de "system"-token en is niet toegankelijk via een andere API.

Parameters

  • challenge

    ArrayBuffer

    Een challenge zoals uitgegeven door de Verified Access Web API.

  • registerKey

    booleaans optioneel

    Chrome 59+ browser.* sinds Chrome 148

    Als je dit beleid instelt, wordt de huidige Enterprise Machine Key geregistreerd met de "system"-token en wordt de rol van Enterprise Machine Key opgegeven. De sleutel kan dan aan een certificaat worden gekoppeld en worden gebruikt zoals elke andere ondertekeningssleutel. Deze sleutel is een 2048-bits RSA-sleutel. Volgende aanroepen van deze functie genereren dan een nieuwe Enterprise Machine Key.

Retourzendingen

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt omgezet met de challengereactie.

challengeUserKey()

Chrome 50+ browser.* sinds Chrome 148 Beëindigd sinds Chrome 110
browser.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

Gebruik in plaats daarvan challengeKey.

Daagt een hardware-ondersteunde zakelijke gebruikerssleutel uit en geeft de reactie door als onderdeel van een protocol voor attest op afstand. Alleen nuttig op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen geeft als reacties verifieert. Een geslaagde verificatie door de Web-API voor geverifieerde toegang is een sterk signaal van het volgende: * Het huidige apparaat is een legitiem ChromeOS-apparaat. * Het huidige apparaat wordt beheerd door het domein dat is opgegeven tijdens de verificatie. * De huidige ingelogde gebruiker wordt beheerd door het domein dat is opgegeven tijdens de verificatie. * De huidige apparaatstatus voldoet aan het beleid voor zakelijke gebruikers. In een beleid kan bijvoorbeeld staan dat het apparaat niet in de ontwikkelaarsmodus mag staan. * De openbare sleutel die door de verificatie wordt verstrekt, is nauw verbonden met de hardware van het huidige apparaat en met de huidige ingelogde gebruiker. Deze functie is zeer beperkt en mislukt als het huidige apparaat niet wordt beheerd, de huidige gebruiker niet wordt beheerd of als deze bewerking niet expliciet is aangezet voor de beller door het beleid voor zakelijke gebruikers. De sleutel van de zakelijke gebruiker bevindt zich niet in de "user"-token en is niet toegankelijk via een andere API.

Parameters

  • challenge

    ArrayBuffer

    Een challenge zoals uitgegeven door de Verified Access Web API.

  • registerKey

    booleaans

    Als je dit beleid instelt, wordt de huidige sleutel voor zakelijke gebruikers geregistreerd met de "user"-token en wordt de rol van sleutel voor zakelijke gebruikers opgegeven. De sleutel kan dan aan een certificaat worden gekoppeld en worden gebruikt zoals elke andere ondertekeningssleutel. Deze sleutel is een 2048-bits RSA-sleutel. Volgende aanroepen van deze functie genereren dan een nieuwe sleutel voor zakelijke gebruikers.

Retourzendingen

  • Promise<ArrayBuffer>

    Chrome 131+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt omgezet met de challengereactie.

getCertificates()

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

Retourneert de lijst met alle clientcertificaten die beschikbaar zijn via de aangegeven token. Kan worden gebruikt om te controleren of er clientcertificaten bestaan die kunnen worden gebruikt voor een bepaalde verificatie en of deze zijn verlopen.

Parameters

  • tokenId

    tekenreeks

    De ID van een token die is geretourneerd door getTokens.

Retourzendingen

  • Promise<ArrayBuffer[]>

    Chrome 131+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt omgezet met de lijst met beschikbare certificaten.

getTokens()

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

Retourneert de beschikbare tokens. In de sessie van een normale gebruiker bevat de lijst altijd de token van de gebruiker met id "user". Als er een systeembrede TPM-token beschikbaar is, bevat de geretourneerde lijst ook de systeembrede token met id "system". De systeembrede token is hetzelfde voor alle sessies op dit apparaat (apparaat in de zin van bijvoorbeeld een Chromebook).

Retourzendingen

  • Promise<Token[]>

    Chrome 131+ browser.* sinds Chrome 148

    Aangeroepen door getTokens met de lijst met beschikbare tokens.

importCertificate()

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

Importeert certificate naar de opgegeven token als de gecertificeerde sleutel al is opgeslagen in deze token. Na een geslaagd certificeringsverzoek moet deze functie worden gebruikt om het verkregen certificaat op te slaan en beschikbaar te maken voor het besturingssysteem en de browser voor verificatie.

Parameters

  • tokenId

    tekenreeks

    De ID van een token die is geretourneerd door getTokens.

  • certificaat

    ArrayBuffer

    De DER-codering van een X.509-certificaat.

Retourzendingen

  • Promise<void>

    Chrome 131+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt opgelost als deze bewerking is afgerond.

removeCertificate()

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

Verwijdert certificate uit de gegeven token als deze aanwezig is. Moet worden gebruikt om verouderde certificaten te verwijderen, zodat ze niet worden meegenomen tijdens de verificatie en de certificaatkeuze niet onoverzichtelijk maken. Moet worden gebruikt om opslagruimte vrij te maken in de certificaatopslag.

Parameters

  • tokenId

    tekenreeks

    De ID van een token die is geretourneerd door getTokens.

  • certificaat

    ArrayBuffer

    De DER-codering van een X.509-certificaat.

Retourzendingen

  • Promise<void>

    Chrome 131+ browser.* sinds Chrome 148

    Retourneert een Promise die wordt opgelost als deze bewerking is afgerond.