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 op een andere manier via chrome.platformKeys.

Machtigingen

enterprise.platformKeys

Beschikbaarheid

Alleen ChromeOS Vereist beleid

Concepten en gebruik

Typisch gebruik van deze API om een ​​clientcertificaat in te schrijven volgt deze stappen:

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

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

  • Genereer een sleutelpaar met behulp van de generateKey() Token-methode (gedefinieerd in SubtleCrypto). Hierdoor keert de handgreep terug naar de sleutel.

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

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

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

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

Hier is een voorbeeld dat de belangrijkste API-interactie laat zien, behalve het samenstellen 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

Chroom 110+

Type sleutel dat moet worden gegenereerd.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chroom 110+

Eigenschappen

  • uitdaging

    ArrayBuffer

    Een uitdaging zoals uitgestraald door de Verified Access Web API.

  • registersleutel

    RegisterKeyOptions optioneel

    Registreert, indien aanwezig, de uitgedaagde sleutel met het token van het opgegeven scope . De sleutel kan vervolgens worden gekoppeld aan een certificaat en worden gebruikt zoals elke andere ondertekeningssleutel. Volgende aanroepen van deze functie genereren vervolgens een nieuwe Enterprise Key in het opgegeven scope .

  • domein

    Domein

    Welke Enterprise Key moet worden uitgedaagd.

RegisterKeyOptions

Chroom 110+

Eigenschappen

  • algoritme

    Algoritme

    Welk algoritme de geregistreerde sleutel moet gebruiken.

Scope

Chroom 110+

Of u de Enterprise User Key of de Enterprise Machine Key wilt gebruiken.

Enum

"GEBRUIKER"

"MACHINE"

Token

Eigenschappen

  • Identiteitskaart

    snaar

    Identificeert dit Token op unieke wijze.

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

  • softwareOndersteundSubtleCrypto

    Subtiele Crypto

    Chroom 97+

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

    Er kunnen alleen niet-extraheerbare RSASSA-PKCS1-V1_5-sleutels met modulusLength tot 2048 worden gegenereerd. Elke sleutel kan maximaal één keer worden gebruikt voor het ondertekenen van gegevens.

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

  • subtieleCrypto

    Subtiele Crypto

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

    Er kunnen alleen niet-extraheerbare RSASSA-PKCS1-V1_5-sleutels met modulusLength tot 2048 en ECDSA met namedCurve P-256 worden gegenereerd. Elke sleutel kan maximaal één keer worden gebruikt voor het ondertekenen van gegevens.

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

Methoden

challengeKey()

BeloofChrome 110+
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

Vergelijkbaar met challengeMachineKey en challengeUserKey , maar maakt het mogelijk om het algoritme van een geregistreerde sleutel op te geven. Daagt een door hardware ondersteunde Enterprise Machine Key uit en verzendt het antwoord als onderdeel van een attestprotocol op afstand. Alleen nuttig op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen uitvaardigt 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 is opgegeven tijdens de verificatie, dat de huidige ingelogde gebruiker wordt beheerd door het domein dat is opgegeven tijdens de verificatie. en de huidige apparaatstatus voldoet aan het apparaatbeleid van het bedrijf. Een beleid kan bijvoorbeeld specificeren dat het apparaat niet in de ontwikkelaarsmodus mag staan. Elke apparaatidentiteit die door de verificatie wordt uitgezonden, 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 aangemelde 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 ingeschakeld voor de beller door het apparaatbeleid van de onderneming. De betwiste sleutel bevindt zich niet in het token "system" of "user" en is niet toegankelijk voor een andere API.

Parameters

  • Object dat de velden bevat die zijn gedefinieerd in ChallengeKeyOptions .

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (response: ArrayBuffer) => void

    • antwoord

      ArrayBuffer

      De uitdagingsreactie.

Retouren

  • Belofte<ArrayBuffer>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

challengeMachineKey()

PromiseChrome 50+ Verouderd sinds Chrome 110
 
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

Gebruik in plaats daarvan challengeKey .

Daagt een door hardware ondersteunde Enterprise Machine Key uit en verzendt het antwoord als onderdeel van een attestprotocol op afstand. Alleen nuttig op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen uitvaardigt als antwoorden verifieert. Een succesvolle verificatie door de Verified Access Web API is een sterk signaal van al het volgende: * Het huidige apparaat is een legitiem ChromeOS-apparaat. * Het huidige apparaat wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige ingelogde gebruiker wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige apparaatstatus voldoet aan het apparaatbeleid van het bedrijf. Een beleid kan bijvoorbeeld specificeren dat het apparaat niet in de ontwikkelaarsmodus mag staan. *Elke apparaatidentiteit die door de verificatie wordt vrijgegeven, 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 ingeschakeld voor de beller door het apparaatbeleid van de onderneming. De Enterprise Machine Key bevindt zich niet in het "system" -token en is niet toegankelijk voor andere API's.

Parameters

  • uitdaging

    ArrayBuffer

    Een uitdaging zoals uitgestraald door de Verified Access Web API.

  • registersleutel

    Booleaans optioneel

    Chroom 59+

    Indien ingesteld, wordt de huidige Enterprise Machine Key geregistreerd met het "system" -token en wordt de rol van Enterprise Machine Key opgegeven. De sleutel kan vervolgens worden gekoppeld aan een certificaat en worden gebruikt zoals elke andere ondertekeningssleutel. Deze sleutel is 2048-bit RSA. Volgende aanroepen van deze functie genereren vervolgens een nieuwe Enterprise Machine Key.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (response: ArrayBuffer) => void

    • antwoord

      ArrayBuffer

      De uitdagingsreactie.

Retouren

  • Belofte<ArrayBuffer>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

challengeUserKey()

PromiseChrome 50+ Verouderd sinds Chrome 110
 
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

Gebruik in plaats daarvan challengeKey .

Daagt een door hardware ondersteunde Enterprise User Key uit en verzendt het antwoord als onderdeel van een attestprotocol op afstand. Alleen nuttig op ChromeOS en in combinatie met de Verified Access Web API, die zowel uitdagingen uitvaardigt als antwoorden verifieert. Een succesvolle verificatie door de Verified Access Web API is een sterk signaal van al het volgende: * Het huidige apparaat is een legitiem ChromeOS-apparaat. * Het huidige apparaat wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige ingelogde gebruiker wordt beheerd door het domein dat tijdens de verificatie is opgegeven. * De huidige apparaatstatus voldoet aan het zakelijke gebruikersbeleid. Een beleid kan bijvoorbeeld specificeren dat het apparaat niet in de ontwikkelaarsmodus mag staan. * De openbare sleutel die door de verificatie wordt uitgezonden, 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 ingeschakeld voor de beller door het zakelijke gebruikersbeleid. De Enterprise User Key bevindt zich niet in het "user" -token en is niet toegankelijk voor andere API's.

Parameters

  • uitdaging

    ArrayBuffer

    Een uitdaging zoals uitgestraald door de Verified Access Web API.

  • registersleutel

    Booleaans

    Indien ingesteld, wordt de huidige Enterprise User Key geregistreerd met het "user" -token en wordt de rol van de Enterprise User Key opgegeven. De sleutel kan vervolgens worden gekoppeld aan een certificaat en worden gebruikt zoals elke andere ondertekeningssleutel. Deze sleutel is 2048-bit RSA. Volgende aanroepen van deze functie genereren vervolgens een nieuwe Enterprise User Key.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (response: ArrayBuffer) => void

    • antwoord

      ArrayBuffer

      De uitdagingsreactie.

Retouren

  • Belofte<ArrayBuffer>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getCertificates()

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

Retourneert de lijst met alle clientcertificaten die beschikbaar zijn voor het opgegeven token. Kan worden gebruikt om te controleren op het bestaan ​​en het verlopen van clientcertificaten die bruikbaar zijn voor een bepaalde authenticatie.

Parameters

  • tokenId

    snaar

    De id van een token dat wordt geretourneerd door getTokens .

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (certificates: ArrayBuffer[]) => void

    • certificaten

      ArrayBuffer[]

      De lijst met certificaten, elk in DER-codering van een X.509-certificaat.

Retouren

  • Belofte<ArrayBuffer[]>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

getTokens()

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

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

Parameters

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    (tokens: Token[]) => void

    • tokens

      Token []

      De lijst met beschikbare tokens.

Retouren

  • Beloof < Token []>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

importCertificate()

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

Importeert certificate naar 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 maken voor 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.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.

removeCertificate()

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

Verwijdert certificate van het opgegeven token, indien aanwezig. Moet worden gebruikt om verouderde certificaten te verwijderen, zodat er tijdens de authenticatie geen rekening mee wordt gehouden en de certificaatkeuze niet onoverzichtelijk wordt. Moet worden gebruikt 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.

  • terugbellen

    functie optioneel

    De callback parameter ziet er als volgt uit: 

    () => void

Retouren

  • Beloof <nietig>

    Chroom 131+

    Beloften worden ondersteund in Manifest V3 en hoger, maar er zijn callbacks beschikbaar voor achterwaartse compatibiliteit. U kunt niet beide gebruiken bij dezelfde functieaanroep. De belofte wordt opgelost met hetzelfde type dat wordt doorgegeven aan de callback.