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

Autorizzazioni

enterprise.platformKeys

Disponibilità

Solo ChromeOS Richiede criteri

Concetti e utilizzo

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

  • Ottieni 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). Verrà restituito l'handle 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 Token sign() (definito in SubtleCrypto).

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

  • Se viene ricevuto un certificato, importalo utilizzando [enterprise.platformKeys.importCertificate()`[3]

Ecco un esempio che mostra le principali interazioni 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 o versioni successive

Tipo di chiave da generare.

Enum

"RSA"

"ECDSA"

ChallengeKeyOptions

Chrome 110 o versioni successive

Proprietà

  • challenge

    ArrayBuffer

    Una verifica emessa dall'API web Verified Access.

  • registerKey

    RegisterKeyOptions facoltativo

    Se presente, registra la chiave contestata 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

    La chiave Enterprise da verificare.

RegisterKeyOptions

Chrome 110 o versioni successive

Proprietà

  • algoritmo

    Algoritmo

    L'algoritmo che deve essere utilizzato dalla chiave registrata.

Scope

Chrome 110 o versioni successive

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

Enum

"USER"

"MACHINE"

Token

Proprietà

  • id

    stringa

    Identifica in modo univoco questo Token.

    Gli ID statici sono "user" e "system", che fanno riferimento rispettivamente al token hardware specifico dell'utente e a quello 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 di chiavi, sono supportate dal software. La protezione delle chiavi e, di conseguenza, l'implementazione della proprietà non estraibile, viene eseguita in software, pertanto le chiavi sono meno protette rispetto alle chiavi hardware-backed.

    È possibile generare solo chiavi RSASSA-PKCS1-V1_5 non estraibili con modulusLength fino a 2048. Ogni chiave può essere utilizzata per la firma dei dati al massimo una volta.

    Le chiavi generate su un Token specifico non possono essere utilizzate con altri token né con window.crypto.subtle. Analogamente, 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.

    È possibile generare solo chiavi RSASSA-PKCS1-V1_5 non estraibili con modulusLength fino a 2048 ed ECDSA con namedCurve P-256. Ogni chiave può essere utilizzata per la firma dei dati al massimo una volta.

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

Metodi

challengeKey()

Promessa Chrome 110 e versioni successive 
chrome.enterprise.platformKeys.challengeKey(
  options: ChallengeKeyOptions,
  callback?: function,
)

Simile a challengeMachineKey e challengeUserKey, ma consente di specificare l'algoritmo di una chiave registrata. Verifica una chiave macchina Enterprise basata su 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 le sfide e verifica le risposte.

Una verifica riuscita da parte dell'API web Verified Access è un chiaro indicatore che il dispositivo corrente è un dispositivo ChromeOS legittimo, che è gestito dal dominio specificato durante la verifica, che l'utente che ha eseguito l'accesso corrente è gestito dal dominio specificato durante la verifica e che lo stato corrente del dispositivo è conforme ai criteri dei dispositivi aziendali. Ad esempio, un criterio potrebbe 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 legata anche all'utente che ha eseguito l'accesso.

Questa funzione è molto limitata e non andrà a buon fine se il dispositivo corrente non è gestito, se l'utente corrente non è gestito o se questa operazione non è stata attivata esplicitamente per il chiamante dal criterio del dispositivo aziendale. La chiave contestata non si trova nel token "system" o "user" e non è accessibile da nessun'altra API.

Parametri

  • Oggetto contenente i campi definiti in ChallengeKeyOptions.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla verifica.

Resi

  • Promise<ArrayBuffer>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

challengeMachineKey()

Promessa Chrome 50 e versioni successive Ritirato da Chrome 110
chrome.enterprise.platformKeys.challengeMachineKey(
  challenge: ArrayBuffer,
  registerKey?: boolean,
  callback?: function,
)

Utilizza invece challengeKey.

Verifica una chiave macchina Enterprise basata su 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 le sfide e verifica le risposte. Una verifica andata a buon fine da parte dell'API web Verified Access è un indicatore affidabile di quanto segue: * Il dispositivo attuale è un dispositivo ChromeOS legittimo. * Il dispositivo attuale è 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 ai criteri relativi ai dispositivi aziendali. Ad esempio, un criterio potrebbe specificare che il dispositivo non deve essere in modalità sviluppatore. * Qualsiasi identità del dispositivo emessa dalla verifica è strettamente legata all'hardware del dispositivo attuale. Questa funzione è molto limitata e non andrà a buon fine se il dispositivo corrente non è gestito, se l'utente corrente non è gestito o se questa operazione non è stata attivata esplicitamente per il chiamante dal criterio del dispositivo aziendale. La chiave macchina aziendale non si trova nel token "system" e non è accessibile da nessun'altra API.

Parametri

  • challenge

    ArrayBuffer

    Una verifica emessa dall'API web Verified Access.

  • registerKey

    booleano facoltativo

    Chrome 59 e versioni successive

    Se impostato, la chiave macchina Enterprise corrente è registrata con il token "system" e cede il ruolo chiave macchina 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 macchina Enterprise.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla verifica.

Resi

  • Promise<ArrayBuffer>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

challengeUserKey()

Promessa Chrome 50 e versioni successive Ritirato da Chrome 110
chrome.enterprise.platformKeys.challengeUserKey(
  challenge: ArrayBuffer,
  registerKey: boolean,
  callback?: function,
)

Utilizza invece challengeKey.

Verifica una chiave utente Enterprise basata su 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 le sfide e verifica le risposte. Una verifica andata a buon fine da parte dell'API web Verified Access è un indicatore affidabile di quanto segue: * Il dispositivo attuale è un dispositivo ChromeOS legittimo. * Il dispositivo attuale è gestito dal dominio specificato durante la verifica. * L'utente che ha eseguito l'accesso è gestito dal dominio specificato durante la verifica. * Lo stato corrente del dispositivo è conforme ai criteri per gli utenti aziendali. Ad esempio, un criterio potrebbe specificare che il dispositivo non deve essere in modalità sviluppatore. * La chiave pubblica emessa dalla verifica è strettamente legata all'hardware del dispositivo corrente e all'utente che ha eseguito l'accesso. Questa funzione è molto limitata e non andrà a buon fine se il dispositivo corrente non è gestito, se l'utente corrente non è gestito o se questa operazione non è stata attivata esplicitamente per il chiamante dal criterio utente aziendale. La chiave utente Enterprise non si trova nel token "user" e non è accessibile da nessun'altra API.

Parametri

  • challenge

    ArrayBuffer

    Una verifica emessa dall'API web Verified Access.

  • registerKey

    booleano

    Se impostato, la chiave utente Enterprise corrente viene registrata con il token "user" e cede il ruolo 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

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla verifica.

Resi

  • Promise<ArrayBuffer>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getCertificates()

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

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

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (certificates: ArrayBuffer[]) => void

    • certificati

      ArrayBuffer[]

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

Resi

  • Promise<ArrayBuffer[]>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

getTokens()

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

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 inteso ad esempio come Chromebook).

Parametri

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    (tokens: Token[]) => void

    • token

      Token[]

      L'elenco dei token disponibili.

Resi

  • Promise<Token[]>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

importCertificate()

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

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 memorizzare 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

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.

removeCertificate()

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

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 di archiviazione nel magazzino dei certificati.

Parametri

  • tokenId

    stringa

    L'ID di un token restituito da getTokens.

  • certificato

    ArrayBuffer

    La codifica DER di un certificato X.509.

  • callback

    function facoltativa

    Il parametro callback ha il seguente aspetto: 

    () => void

Resi

  • Promise<void>

    Chrome 131 e versioni successive

    Le promesse sono supportate in Manifest V3 e versioni successive, ma i callback vengono forniti per la compatibilità con le versioni precedenti. Non puoi utilizzare entrambe nella stessa chiamata di funzione. La promessa viene risolta con lo stesso tipo passato al callback.