chrome.enterprise.platformKeys

refresh date: 2026-09-25 robots: noindex

Importante: questa API funziona solo su ChromeOS.

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 un'altra estensione tramite chrome.platformKeys.

Autorizzazioni

enterprise.platformKeys

Disponibilità

Solo ChromeOS Richiede una policy

Nota: questa API è destinata solo alle estensioni preinstallate da una policy.

Utilizzo

L'utilizzo tipico di questa API per registrare un certificato client prevede i seguenti passaggi:

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

• Trova il token con id uguale a "user". Utilizza questo token in un secondo momento.

• Genera una coppia di chiavi utilizzando il metodo Token generateKey (definito in SubtleCrypto). Verrà restituito l'handle della chiave.

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

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

• Completa 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 con l'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 e versioni successive

Tipo di chiave da generare.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 e versioni successive

Proprietà

• challenge

  ArrayBuffer

  Una verifica emessa dall'API web Accesso verificato.

• registerKey

  RegisterKeyOptions facoltativo

  Se presente, registra la chiave di verifica con il token di 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 Enterprise nel scope specificato.

• ambito

  Ambito

  Quale chiave Enterprise verificare.

RegisterKeyOptions

Chrome 110 e versioni successive

Proprietà

• algoritmo

  Algoritmo

  L'algoritmo che deve essere utilizzato dalla chiave registrata.

Scope

Chrome 110 e versioni successive

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. Eventuali altri token (con altri identificatori) potrebbero essere restituiti da enterprise.platformKeys.getTokens.

• softwareBackedSubtleCrypto

  SubtleCrypto

  Chrome 97 e versioni successive

  Implementa l'interfaccia SubtleCrypto di WebCrypto. Le operazioni di crittografia, inclusa la generazione delle chiavi, sono supportate dal software. La protezione delle chiavi, e quindi l'implementazione della proprietà non estraibile, viene eseguita nel software, pertanto le chiavi sono meno protette rispetto alle chiavi con integrazione hardware.

  È possibile generare solo chiavi non estraibili. L'unico tipo di chiave supportato è RSASSA-PKCS1-V1_5 con modulusLength fino a 2048. Ogni chiave può essere utilizzata per la firma dei dati al massimo una volta, a meno che l'estensione non sia inclusa nella lista consentita tramite la policy KeyPermissions, nel qual caso la chiave può essere utilizzata a tempo indeterminato.

  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 delle chiavi, sono basate sulla crittografia hardware.

  È possibile generare solo chiavi non estraibili. I tipi di chiavi supportati sono RSASSA-PKCS1-V1_5 con modulusLength fino a 2048 ed ECDSA con namedCurve P-256. Ogni chiave può essere utilizzata per firmare i dati al massimo una volta, a meno che l'estensione non sia inclusa nella lista consentita dalla policy KeyPermissions, nel qual caso la chiave può essere utilizzata a tempo indeterminato.

  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. Verifica una chiave Enterprise Machine Key con crittografia hardware ed emette la risposta nell'ambito di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API web Accesso verificato, che genera le richieste e verifica le risposte.

Una verifica riuscita da parte dell'API web Accesso verificato è un forte indicatore del fatto che il dispositivo corrente è un dispositivo ChromeOS legittimo, che il dispositivo corrente è 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 alla policy per i dispositivi aziendali. Ad esempio, una policy potrebbe specificare che il dispositivo non deve essere in modalità sviluppatore. Qualsiasi identità del dispositivo emessa dalla verifica è strettamente associata all'hardware del dispositivo corrente. Se viene specificato l'ambito "user", l'identità è anche strettamente associata all'utente che ha eseguito l'accesso.

Questa funzione è altamente limitata e non andrà a buon fine se il dispositivo corrente non è gestito, l'utente corrente non è gestito o se questa operazione non è stata abilitata esplicitamente per il chiamante dalla policy per i dispositivi aziendali. La chiave di verifica non si trova nel token "system" o "user" e non è accessibile da altre API.

Parametri

• opzioni

  ChallengeKeyOptions

  Oggetto contenente i campi definiti in ChallengeKeyOptions.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  (response: ArrayBuffer) => void

  • risposta

    ArrayBuffer

    La risposta alla verifica.

Resi

• Promise<ArrayBuffer>

  Chrome 131+

  Restituisce una Promise che si risolve con la risposta alla verifica.

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

challengeMachineKey()

Promise Chrome 50 e versioni successive Ritirato da Chrome 110

chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Utilizza invece challengeKey.

Verifica una chiave Enterprise Machine Key con crittografia hardware ed emette la risposta nell'ambito di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API web Accesso verificato, che genera le richieste e verifica le risposte. Una verifica riuscita da parte dell'API web Accesso verificato è un forte indicatore di quanto segue: * Il dispositivo corrente è un dispositivo ChromeOS legittimo. * Il dispositivo corrente è gestito dal dominio specificato durante la verifica. * L'utente che ha eseguito l'accesso è gestito dal dominio specificato durante la verifica. * Lo stato attuale del dispositivo è conforme alla policy per i dispositivi aziendali. Ad esempio, una policy potrebbe specificare che il dispositivo non deve essere in modalità sviluppatore. * Qualsiasi identità del dispositivo emessa dalla verifica è strettamente associata all'hardware del dispositivo corrente. Questa funzione è altamente limitata e non andrà a buon fine se il dispositivo corrente non è gestito, l'utente corrente non è gestito o se questa operazione non è stata abilitata esplicitamente per il chiamante dalla policy per i dispositivi aziendali. La chiave Enterprise Machine non si trova nel token "system" e non è accessibile da altre API.

Parametri

• challenge

  ArrayBuffer

  Una verifica emessa dall'API web Accesso verificato.

• registerKey

  boolean facoltativo

  Chrome 59 e versioni successive

  Se impostata, la chiave Enterprise Machine Key corrente viene registrata con il token "system" e rinuncia al ruolo Enterprise Machine Key. 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 Enterprise Machine Key.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  (response: ArrayBuffer) => void

  • risposta

    ArrayBuffer

    La risposta alla verifica.

Resi

• Promise<ArrayBuffer>

  Chrome 131+

  Restituisce una Promise che si risolve con la risposta alla verifica.

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

challengeUserKey()

Promise Chrome 50 e versioni successive Ritirato da Chrome 110

chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
): Promise<ArrayBuffer>

Utilizza invece challengeKey.

Verifica una chiave utente aziendale con crittografia hardware ed emette la risposta nell'ambito di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API web Accesso verificato, che genera le richieste e verifica le risposte. Una verifica riuscita da parte dell'API web Accesso verificato è un forte indicatore di quanto segue: * Il dispositivo corrente è un dispositivo ChromeOS legittimo. * Il dispositivo corrente è gestito dal dominio specificato durante la verifica. * L'utente che ha eseguito l'accesso è gestito dal dominio specificato durante la verifica. * Lo stato attuale del dispositivo è conforme alle policy degli utenti aziendali. Ad esempio, una policy potrebbe specificare che il dispositivo non deve essere in modalità sviluppatore. * La chiave pubblica emessa dalla verifica è strettamente associata all'hardware del dispositivo corrente e all'utente che ha eseguito l'accesso. Questa funzione è altamente limitata e non andrà a buon fine se il dispositivo corrente non è gestito, l'utente corrente non è gestito o se questa operazione non è stata attivata esplicitamente per il chiamante dalla policy utente aziendale. La chiave utente aziendale non risiede nel token "user" e non è accessibile da altre API.

Parametri

• challenge

  ArrayBuffer

  Una verifica emessa dall'API web Accesso verificato.

• registerKey

  booleano

  Se impostata, la chiave utente aziendale corrente viene registrata con il token "user" e rinuncia al ruolo di chiave utente 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 utente aziendale.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  (response: ArrayBuffer) => void

  • risposta

    ArrayBuffer

    La risposta alla verifica.

Resi

• Promise<ArrayBuffer>

  Chrome 131+

  Restituisce una Promise che si risolve con la risposta alla verifica.

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

getCertificates()

Promise

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 elemento facoltativo

  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+

  Restituisce una promessa che si risolve con l'elenco dei certificati disponibili.

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

getTokens()

Promise

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à uguale per tutte le sessioni su questo dispositivo (dispositivo nel senso, ad esempio, di un Chromebook).

Parametri

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  (tokens: Token[]) => void

  • token

    Token[]

    L'elenco dei token disponibili.

Resi

• Promise<Token[]>

  Chrome 131+

  Richiamato da getTokens con l'elenco dei token disponibili.

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

importCertificate()

Promise

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 andata a buon fine, 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

  La codifica DER di un certificato X.509.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 131+

  Restituisce una promessa che viene risolta al termine di questa operazione.

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

removeCertificate()

Promise

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 del certificato. Deve essere utilizzato per liberare spazio nell'archivio certificati.

Parametri

• tokenId

  stringa

  L'ID di un token restituito da getTokens.

• certificato

  ArrayBuffer

  La codifica DER di un certificato X.509.

• callback

  funzione elemento facoltativo

  Il parametro callback ha il seguente aspetto:

  () => void

Resi

• Promise<void>

  Chrome 131+

  Restituisce una promessa che viene risolta al termine di questa operazione.

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