chrome.enterprise.platformKeys

Descrizione

Utilizza l'API chrome.enterprise.platformKeys per generare chiavi e installare certificati per queste chiavi. I certificati verranno gestiti dalla piattaforma e potranno essere utilizzati per l'autenticazione TLS, l'accesso alla rete o da altre estensioni tramite chrome.platformKeys.

Autorizzazioni

enterprise.platformKeys

Disponibilità

Solo ChromeOS Richiede criteri

Utilizzo

L'utilizzo tipico di questa API per registrare un certificato client segue questi passaggi:

  • Recupera tutti i token disponibili utilizzando enterprise.platformKeys.getTokens.

  • Trova il token con id uguale a "user". Utilizza questo token in seguito.

  • Genera una coppia di chiavi utilizzando il metodo generateKey Token (definito in SubtleCrypto). In questo modo, la maniglia tornerà alla chiave.

  • Esporta la chiave pubblica utilizzando il metodo exportKey Token (definito in SubtleCrypto).

  • Crea la firma dei dati della richiesta di certificazione utilizzando il metodo sign Token (definito in SubtleCrypto).

  • Compila la richiesta di certificazione e inviala all'autorità di certificazione.

  • Se viene ricevuto un certificato, importalo utilizzando enterprise.platformKeys.importCertificate

Ecco un esempio che mostra l'interazione principale dell'API, ad eccezione della creazione e dell'invio della richiesta di certificazione:

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

Tipi

Algorithm

Chrome 110+

Tipo di chiave da generare.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110+

Proprietà

  • challenge

    ArrayBuffer

    Una sfida emessa dall'API web Verified Access.

  • registerKey

    RegisterKeyOptions facoltativo

    Se presente, registra la chiave contestata con il token del scope specificato. La chiave può quindi essere associata a un certificato e utilizzata come qualsiasi altra chiave di firma. Le chiamate successive a questa funzione genereranno una nuova chiave aziendale nel scope specificato.

  • ambito

    Ambito

    Quale chiave enterprise contestare.

RegisterKeyOptions

Chrome 110+

Proprietà

  • algoritmo

    Algoritmo

    Quale algoritmo deve utilizzare la chiave registrata.

Scope

Chrome 110+

Indica se utilizzare la chiave utente aziendale o la chiave macchina aziendale.

Enum

"USER"

"MACHINE"

Token

Proprietà

  • id

    stringa

    Identifica in modo univoco questo Token.

    Gli ID statici sono "user" e "system", che si riferiscono rispettivamente al token hardware specifico dell'utente della piattaforma e a quello a livello di sistema. Altri token (con altri identificatori) potrebbero essere restituiti da enterprise.platformKeys.getTokens.

  • softwareBackedSubtleCrypto

    SubtleCrypto

    Chrome 97+

    Implementa l'interfaccia SubtleCrypto di WebCrypto. Le operazioni crittografiche, inclusa la generazione di chiavi, sono supportate dal software. La protezione delle chiavi e quindi l'implementazione della proprietà non estraibile vengono eseguite nel software, quindi le chiavi sono meno protette rispetto a quelle hardware-backed.

    Possono essere generate solo chiavi non estraibili. I tipi di chiavi supportati sono RSASSA-PKCS1-V1_5 e RSA-OAEP (su Chrome versione 135 e successive) con modulusLength fino a 2048. Ogni chiave RSASSA-PKCS1-V1_5 può essere utilizzata per firmare i dati al massimo una volta, a meno che l'estensione non sia inclusa nella lista consentita tramite il criterio KeyPermissions, nel qual caso la chiave può essere utilizzata a tempo indeterminato. Le chiavi RSA-OAEP sono supportate a partire dalla versione 135 di Chrome e possono essere utilizzate dalle estensioni consentite tramite le stesse norme per decriptare altre chiavi.

    Le chiavi generate su un Token specifico non possono essere utilizzate con altri token, né con window.crypto.subtle. Allo stesso modo, gli oggetti Key creati con window.crypto.subtle non possono essere utilizzati con questa interfaccia.

  • subtleCrypto

    SubtleCrypto

    Implementa l'interfaccia SubtleCrypto di WebCrypto. Le operazioni crittografiche, inclusa la generazione di chiavi, sono basate sull'hardware.

    Possono essere generate solo chiavi non estraibili. I tipi di chiavi supportati sono RSASSA-PKCS1-V1_5 e RSA-OAEP (nelle versioni di Chrome 135 e successive) con modulusLength fino a 2048 ed ECDSA con namedCurve P-256. Ogni chiave RSASSA-PKCS1-V1_5 ed ECDSA può essere utilizzata per firmare i dati al massimo una volta, a meno che l'estensione non sia inclusa nella lista consentita tramite il criterio KeyPermissions, nel qual caso la chiave può essere utilizzata a tempo indeterminato. Le chiavi RSA-OAEP sono supportate a partire dalla versione 135 di Chrome e possono essere utilizzate dalle estensioni consentite tramite le stesse norme per decriptare altre chiavi.

    Le chiavi generate su un Token specifico non possono essere utilizzate con altri token, né con window.crypto.subtle. Allo stesso modo, gli oggetti Key creati con window.crypto.subtle non possono essere utilizzati con questa interfaccia.

Metodi

challengeKey()

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

Simile a challengeMachineKey e challengeUserKey, ma consente di specificare l'algoritmo di una chiave registrata. Esegue una richiesta di verifica di una chiave macchina aziendale basata sull'hardware ed emette la risposta nell'ambito di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API web Verified Access, che emette sfide e verifica le risposte.

Una verifica riuscita tramite l'API web Verified Access è un segnale forte che indica che il dispositivo attuale è un dispositivo ChromeOS legittimo, che è gestito dal dominio specificato durante la verifica, che l'utente attualmente connesso è gestito dal dominio specificato durante la verifica e che lo stato attuale del dispositivo è conforme ai criteri aziendali per i dispositivi. Ad esempio, una policy può specificare che il dispositivo non deve essere in modalità sviluppatore. Qualsiasi identità del dispositivo emessa dalla verifica è strettamente legata all'hardware del dispositivo attuale. Se viene specificato l'ambito "user", l'identità è strettamente associata anche all'utente che ha eseguito l'accesso.

Questa funzione è soggetta a molte limitazioni e non andrà a buon fine se il dispositivo attuale non è gestito, l'utente attuale non è gestito o se questa operazione non è stata abilitata esplicitamente per il chiamante dalla policy aziendale per i dispositivi. La chiave contestata non si trova nel token "system" o "user" e non è accessibile da altre API.

Parametri

  • Oggetto contenente i campi definiti in ChallengeKeyOptions.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla sfida.

Resi

  • Promise<ArrayBuffer>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

challengeMachineKey()

Promise Chrome 50+ Ritirato a partire da Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Utilizza challengeKey.

Esegue una richiesta di verifica di una chiave macchina aziendale basata sull'hardware ed emette la risposta nell'ambito di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API web Verified Access, che emette sfide e verifica le risposte. Una verifica riuscita tramite l'API web Accesso verificato è un segnale forte di quanto segue: * Il dispositivo attuale è un dispositivo ChromeOS legittimo. * Il dispositivo attuale è gestito dal dominio specificato durante la verifica. * L'utente attualmente connesso è gestito dal dominio specificato durante la verifica. * Lo stato attuale del dispositivo è conforme ai criteri aziendali relativi ai dispositivi. Ad esempio, una policy può specificare che il dispositivo non deve essere in modalità sviluppatore. * Qualsiasi identità del dispositivo emessa dalla verifica è strettamente vincolata all'hardware del dispositivo attuale. Questa funzione è soggetta a molte limitazioni e non andrà a buon fine se il dispositivo attuale non è gestito, l'utente attuale non è gestito o se questa operazione non è stata abilitata esplicitamente per il chiamante dalla policy aziendale per i dispositivi. La chiave macchina aziendale non si trova nel token "system" e non è accessibile da altre API.

Parametri

  • challenge

    ArrayBuffer

    Una sfida emessa dall'API web Verified Access.

  • registerKey

    booleano facoltativo

    Chrome 59+

    Se impostata, la chiave macchina aziendale corrente viene registrata con il token "system" e rinuncia al ruolo di chiave macchina aziendale. La chiave può quindi essere associata a un certificato e utilizzata come qualsiasi altra chiave di firma. Questa chiave è RSA a 2048 bit. Le chiamate successive a questa funzione genereranno una nuova chiave macchina aziendale.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla sfida.

Resi

  • Promise<ArrayBuffer>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

challengeUserKey()

Promise Chrome 50+ Ritirato a partire da Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Utilizza challengeKey.

Esegue una query su una chiave utente aziendale basata sull'hardware ed emette la risposta nell'ambito di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API web Verified Access, che emette sfide e verifica le risposte. Una verifica riuscita tramite l'API web Accesso verificato è un segnale forte di quanto segue: * Il dispositivo attuale è un dispositivo ChromeOS legittimo. * Il dispositivo attuale è gestito dal dominio specificato durante la verifica. * L'utente attualmente connesso è gestito dal dominio specificato durante la verifica. * Lo stato attuale del dispositivo è conforme alle norme per gli utenti aziendali. Ad esempio, una policy può specificare che il dispositivo non deve essere in modalità sviluppatore. * La chiave pubblica emessa dalla verifica è strettamente legata all'hardware del dispositivo attuale e all'utente attualmente connesso. Questa funzione è soggetta a molte limitazioni e non andrà a buon fine se il dispositivo attuale non è gestito, l'utente attuale non è gestito o se questa operazione non è stata attivata esplicitamente per il chiamante dalla policy utente aziendale. La chiave utente aziendale non si trova nel token "user" e non è accessibile da altre API.

Parametri

  • challenge

    ArrayBuffer

    Una sfida emessa dall'API web Verified Access.

  • registerKey

    booleano

    Se impostata, la chiave utente Enterprise corrente viene registrata con il token "user" e rinuncia al ruolo di chiave utente Enterprise. La chiave può quindi essere associata a un certificato e utilizzata come qualsiasi altra chiave di firma. Questa chiave è RSA a 2048 bit. Le chiamate successive a questa funzione genereranno una nuova chiave utente Enterprise.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla sfida.

Resi

  • Promise<ArrayBuffer>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getCertificates()

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

Restituisce l'elenco di tutti i certificati client disponibili dal token specificato. Può essere utilizzato per verificare l'esistenza e la scadenza dei certificati client utilizzabili per una determinata autenticazione.

Parametri

  • tokenId

    stringa

    L'ID di un token restituito da getTokens.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (certificates: ArrayBuffer[]) => void

    • certificati

      ArrayBuffer[]

      L'elenco dei certificati, ciascuno con codifica DER di un certificato X.509.

Resi

  • Promise<ArrayBuffer[]>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

getTokens()

Promessa 
chrome.enterprise.platformKeys.getTokens(
  callback?: function,
): Promise<Token[]>

Restituisce i token disponibili. Nella sessione di un utente normale, l'elenco conterrà sempre il token dell'utente con id "user". Se è disponibile un token TPM a livello di sistema, l'elenco restituito conterrà anche il token a livello di sistema con id "system". Il token a livello di sistema sarà lo stesso per tutte le sessioni su questo dispositivo (dispositivo nel senso di, ad esempio, un Chromebook).

Parametri

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    (tokens: Token[]) => void

    • token

      Token[]

      L'elenco dei token disponibili.

Resi

  • Promise<Token[]>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

importCertificate()

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

Importa certificate nel token specificato se la chiave certificata è già memorizzata in questo token. Dopo una richiesta di certificazione riuscita, questa funzione deve essere utilizzata per archiviare il certificato ottenuto e renderlo disponibile al sistema operativo e al browser per l'autenticazione.

Parametri

  • tokenId

    stringa

    L'ID di un token restituito da getTokens.

  • certificato

    ArrayBuffer

    Codifica DER di un certificato X.509.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.

removeCertificate()

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

Rimuove certificate dal token specificato, se presente. Deve essere utilizzato per rimuovere i certificati obsoleti in modo che non vengano presi in considerazione durante l'autenticazione e non ingombrino la scelta dei certificati. Deve essere utilizzato per liberare spazio di archiviazione nell'archivio certificati.

Parametri

  • tokenId

    stringa

    L'ID di un token restituito da getTokens.

  • certificato

    ArrayBuffer

    Codifica DER di un certificato X.509.

  • callback

    funzione facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 131+

    Le promesse sono supportate solo per Manifest V3 e versioni successive, le altre piattaforme devono utilizzare i callback.