chrome.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-authenticatie, netwerktoegang of door andere extensies via chrome.platformKeys.

Toestemmingen

enterprise.platformKeys

Beschikbaarheid

Alleen voor ChromeOS. Vereist beleid.

Concepten en gebruik

Het gebruikelijke gebruik van deze API om een ​​clientcertificaat aan te vragen, verloopt volgens deze stappen:

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

  • Zoek het token met id "user" . Gebruik dit token vervolgens.

  • Genereer een sleutelpaar met behulp van de generateKey() `-tokenmethode (gedefinieerd in SubtleCrypto). Deze methode retourneert een handle naar de sleutel.

  • Exporteer de publieke sleutel met behulp van de exportKey() Token-methode (gedefinieerd in SubtleCrypto).

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

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

  • Als een certificaat is ontvangen, importeer het dan met behulp van [ enterprise.platformKeys.importCertificate() `[3]

Hier volgt een voorbeeld dat de belangrijkste API-interactie laat zien, met uitzondering van het opbouwen en verzenden van het certificeringsverzoek:

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);

Soorten

Algorithm

Chrome 110+

Type sleutel dat gegenereerd moet worden.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110+

Eigenschappen

  • uitdaging

    ArrayBuffer

    Een uitdaging zoals die wordt gegenereerd door de Verified Access Web API.

  • registerKey

    RegisterKeyOptions optioneel

    Indien aanwezig, registreert deze functie de uitgedaagde sleutel met het token van het opgegeven scope . De sleutel kan vervolgens aan een certificaat worden gekoppeld en gebruikt worden zoals elke andere ondertekeningssleutel. Bij volgende aanroepen van deze functie wordt dan een nieuwe Enterprise Key gegenereerd binnen het opgegeven scope .

  • domein

    Domein

    Welke Enterprise Key moet worden uitgedaagd?

RegisterKeyOptions

Chrome 110+

Eigenschappen

  • algoritme

    Algoritme

    Welk algoritme moet de geregistreerde sleutel gebruiken?

Scope

Chrome 110+

Of u nu de Enterprise User Key of de Enterprise Machine Key moet gebruiken.

Enum

"GEBRUIKER"

"MACHINE"

Token

Eigenschappen

  • id

    snaar

    Identificeert dit Token op unieke wijze.

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

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97+

    Implementeert de SubtleCrypto- interface van WebCrypto. De cryptografische bewerkingen, inclusief sleutelgeneratie, worden door software ondersteund. De bescherming van de sleutels, en daarmee de implementatie van de niet-extraheerbare eigenschap, gebeurt in software, waardoor de sleutels minder goed beschermd zijn dan sleutels die door hardware worden ondersteund.

    Alleen niet-extraheerbare sleutels kunnen worden gegenereerd. De ondersteunde sleuteltypen zijn RSASSA-PKCS1-V1_5 en RSA-OAEP (vanaf Chrome-versie 135) met modulusLength tot 2048. Elke RSASSA-PKCS1-V1_5-sleutel kan maximaal één keer worden gebruikt voor het ondertekenen van gegevens, tenzij de extensie is toegestaan ​​via het KeyPermissions-beleid . In dat geval kan de sleutel onbeperkt worden gebruikt. RSA-OAEP-sleutels worden ondersteund sinds Chrome-versie 135 en kunnen door extensies die via hetzelfde beleid zijn toegestaan, worden gebruikt om andere sleutels uit te pakken.

    Sleutels die op een specifiek Token zijn gegenereerd, kunnen niet met andere tokens worden gebruikt, noch met window.crypto.subtle . Evenmin kunnen Key die met window.crypto.subtle zijn gemaakt, met deze interface worden gebruikt.

  • subtieleCrypto

    SubtleCrypto

    Implementeert de SubtleCrypto- interface van WebCrypto. De cryptografische bewerkingen, inclusief sleutelgeneratie, worden door hardware ondersteund.

    Alleen niet-extraheerbare sleutels kunnen worden gegenereerd. De ondersteunde sleuteltypen zijn RSASSA-PKCS1-V1_5 en RSA-OAEP (vanaf Chrome-versie 135) met modulusLength tot 2048 en ECDSA met namedCurve P-256. Elke RSASSA-PKCS1-V1_5- en ECDSA-sleutel kan maximaal één keer worden gebruikt voor het ondertekenen van gegevens, tenzij de extensie is toegevoegd aan de lijst met toegestane extensies via het KeyPermissions-beleid . In dat geval kan de sleutel onbeperkt worden gebruikt. RSA-OAEP-sleutels worden ondersteund sinds Chrome-versie 135 en kunnen door extensies die zijn toegevoegd aan dezelfde lijst met toegestane extensies worden gebruikt om andere sleutels uit te pakken.

    Sleutels die op een specifiek Token zijn gegenereerd, kunnen niet met andere tokens worden gebruikt, noch met window.crypto.subtle . Evenmin kunnen Key die met window.crypto.subtle zijn gemaakt, met deze interface worden gebruikt.

Methoden

challengeKey()

Chrome 110+
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
): Promise<ArrayBuffer>

Vergelijkbaar met challengeMachineKey en challengeUserKey , maar maakt het mogelijk om het algoritme van een geregistreerde sleutel te specificeren. Het daagt een hardwarematig ondersteunde Enterprise Machine Key uit en verzendt het antwoord als onderdeel van een extern attestatieprotocol. Alleen bruikbaar op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen verstuurt als antwoorden verifieert.

Een succesvolle 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 aangemelde gebruiker wordt beheerd door het domein dat tijdens de verificatie is opgegeven en dat de huidige apparaatstatus voldoet aan het bedrijfsbeleid voor apparaten. Een beleid kan bijvoorbeeld specificeren dat het apparaat niet in de ontwikkelaarsmodus mag staan. Elke apparaatidentiteit die door de verificatie wordt gegenereerd, is nauw verbonden met de hardware van het huidige apparaat. Als het bereik "user" is gespecificeerd, is de identiteit ook nauw verbonden met de huidige aangemelde gebruiker.

Deze functie is zeer beperkt en zal mislukken als het huidige apparaat niet wordt beheerd, de huidige gebruiker niet wordt beheerd, of als deze bewerking niet expliciet is ingeschakeld voor de aanroeper via het bedrijfsbeleid voor apparaten. De betwiste sleutel bevindt zich niet in het "system" of "user" -token en is niet toegankelijk via een andere API.

Parameters

Retourneert

  • Promise<ArrayBuffer>

    Chrome 131+

    Retourneert een Promise die wordt opgelost met het antwoord op de uitdaging.

challengeMachineKey()

Chrome 50+ Niet meer ondersteund sinds Chrome 110
 
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
): Promise<ArrayBuffer>

Gebruik in plaats daarvan challengeKey .

Deze functie daagt een hardware-ondersteunde Enterprise Machine Key uit en verzendt het antwoord als onderdeel van een extern attestatieprotocol. Alleen bruikbaar op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen verstuurt als antwoorden verifieert. Een succesvolle verificatie door de Verified Access Web API is een sterk signaal dat aan alle volgende voorwaarden is voldaan: * Het huidige apparaat is een legitiem ChromeOS-apparaat. * Het huidige apparaat wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige aangemelde gebruiker wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige apparaatstatus voldoet aan het bedrijfsbeleid voor apparaten. Een beleid kan bijvoorbeeld specificeren dat het apparaat niet in de ontwikkelaarsmodus mag staan. * Elke apparaatidentiteit die door de verificatie wordt gegenereerd, is nauw verbonden met de hardware van het huidige apparaat. Deze functie is zeer beperkt en zal mislukken als het huidige apparaat niet wordt beheerd, de huidige gebruiker niet wordt beheerd of als deze bewerking niet expliciet is ingeschakeld voor de aanroeper door het bedrijfsbeleid voor apparaten. De Enterprise Machine Key bevindt zich niet in het "system" -token en is niet toegankelijk via andere API's.

Parameters

  • uitdaging

    ArrayBuffer

    Een uitdaging zoals die wordt gegenereerd door de Verified Access Web API.

  • registerKey

    boolean optioneel

    Chrome 59+

    Indien ingesteld, wordt de huidige Enterprise Machine Key geregistreerd bij het "system" -token en wordt de Enterprise Machine Key-rol overgedragen. De sleutel kan vervolgens worden gekoppeld aan een certificaat en worden gebruikt zoals elke andere ondertekeningssleutel. Deze sleutel is een 2048-bits RSA-sleutel. Bij volgende aanroepen van deze functie wordt een nieuwe Enterprise Machine Key gegenereerd.

Retourneert

  • Promise<ArrayBuffer>

    Chrome 131+

    Retourneert een Promise die wordt opgelost met het antwoord op de uitdaging.

challengeUserKey()

Chrome 50+ Niet meer ondersteund sinds Chrome 110
 
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
): Promise<ArrayBuffer>

Gebruik in plaats daarvan challengeKey .

Deze functie daagt een hardware-ondersteunde Enterprise User Key uit en verzendt het antwoord als onderdeel van een extern attestatieprotocol. Alleen bruikbaar op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen verstuurt als antwoorden verifieert. Een succesvolle verificatie door de Verified Access Web API is een sterk signaal dat aan alle volgende voorwaarden is voldaan: * Het huidige apparaat is een legitiem ChromeOS-apparaat. * Het huidige apparaat wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige aangemelde gebruiker wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige apparaatstatus voldoet aan het bedrijfsbeleid voor gebruikers. Een beleid kan bijvoorbeeld specificeren dat het apparaat niet in de ontwikkelaarsmodus mag staan. * De openbare sleutel die door de verificatie wordt verzonden, is nauw verbonden met de hardware van het huidige apparaat en met de huidige aangemelde gebruiker. Deze functie is zeer beperkt en zal mislukken als het huidige apparaat niet wordt beheerd, de huidige gebruiker niet wordt beheerd of als deze bewerking niet expliciet is ingeschakeld voor de aanroeper door het bedrijfsbeleid voor gebruikers. De Enterprise User Key bevindt zich niet in het "user" -token en is niet toegankelijk via andere API's.

Parameters

  • uitdaging

    ArrayBuffer

    Een uitdaging zoals die wordt gegenereerd door de Verified Access Web API.

  • registerKey

    booleaans

    Indien ingesteld, wordt de huidige Enterprise User Key geregistreerd bij het "user" -token en wordt de Enterprise User Key-rol overgedragen. De sleutel kan vervolgens worden gekoppeld aan een certificaat en worden gebruikt zoals elke andere ondertekeningssleutel. Deze sleutel is een 2048-bits RSA-sleutel. Bij volgende aanroepen van deze functie wordt een nieuwe Enterprise User Key gegenereerd.

Retourneert

  • Promise<ArrayBuffer>

    Chrome 131+

    Retourneert een Promise die wordt opgelost met het antwoord op de uitdaging.

getCertificates()

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

Geeft een lijst weer van alle clientcertificaten die beschikbaar zijn op basis van het opgegeven token. Kan worden gebruikt om te controleren of clientcertificaten die voor een bepaalde authenticatie gebruikt kunnen worden, bestaan ​​en verlopen zijn.

Parameters

  • tokenId

    snaar

    De ID van een token dat wordt geretourneerd door getTokens .

Retourneert

  • Promise<ArrayBuffer[]>

    Chrome 131+

    Retourneert een Promise die wordt opgelost met de lijst van de beschikbare certificaten.

getTokens()

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

Geeft de beschikbare tokens terug. In een reguliere gebruikerssessie bevat de lijst altijd het token van de gebruiker met id "user" . Als er een systeembreed TPM-token beschikbaar is, bevat de geretourneerde lijst ook het systeembrede token met id "system" . Het systeembrede token is hetzelfde voor alle sessies op dit apparaat (apparaat in de zin van bijvoorbeeld een Chromebook).

Retourneert

  • Promise< Token []>

    Chrome 131+

    Wordt aangeroepen door getTokens met de lijst van beschikbare tokens.

importCertificate()

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

Importeert certificate in het opgegeven token als de gecertificeerde sleutel al in dit token is opgeslagen. Na een succesvol certificeringsverzoek moet deze functie worden gebruikt om het verkregen certificaat op te slaan en beschikbaar te stellen aan het besturingssysteem en de browser voor authenticatie.

Parameters

  • tokenId

    snaar

    De ID van een token dat wordt geretourneerd door getTokens .

  • certificaat

    ArrayBuffer

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

Retourneert

  • Promise<void>

    Chrome 131+

    Retourneert een Promise die wordt opgelost wanneer deze bewerking is voltooid.

removeCertificate()

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

Verwijdert certificate van het opgegeven token, indien aanwezig. Deze functie moet worden gebruikt om verouderde certificaten te verwijderen, zodat ze niet meer worden meegenomen in de authenticatie en de certificaatkeuze niet onnodig complex maken. Ook handig om opslagruimte vrij te maken in het certificaatarchief.

Parameters

  • tokenId

    snaar

    De ID van een token dat wordt geretourneerd door getTokens .

  • certificaat

    ArrayBuffer

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

Retourneert

  • Promise<void>

    Chrome 131+

    Retourneert een Promise die wordt opgelost wanneer deze bewerking is voltooid.