chrome.enterprise.platformKeys

Descrizione

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

Autorizzazioni

enterprise.platformKeys

Disponibilità

Solo ChromeOS Richiede criterio

Concetti e 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 successivamente.

  • Genera una coppia di chiavi utilizzando il metodo Token generateKey() (definito in SubtleCrypto). L'handle verrà restituito alla 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 hai ricevuto un certificato, importalo utilizzando [enterprise.platformKeys.importCertificate()`[3]

Ecco un esempio che mostra l'interazione principale con l'API, tranne la creazione e l'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 presentata dall'API Verified Access Web.

  • registerKey

    RegisterKeyOptions facoltativo

    Se presente, registra la chiave oggetto 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 valore scope specificato.

  • ambito

    Ambito

    Quale chiave aziendale sfidare.

RegisterKeyOptions

Chrome 110 e versioni successive

Proprietà

  • algoritmo

    Algoritmo

    L'algoritmo che deve essere utilizzato dalla chiave registrata.

Scope

Chrome 110 e versioni successive

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

Enum

"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 per l'utente e a livello di sistema della piattaforma. 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 crittografiche, inclusa la generazione di chiavi, sono supportate dal software. La protezione delle chiavi, e quindi l'implementazione della proprietà non estraibile, avviene nel software, quindi le chiavi sono meno protette rispetto alle chiavi basate su hardware.

    È possibile generare solo chiavi RSASSA-PKCS1-V1_5 non estraibili con modulusLength fino a 2048. Ogni chiave può essere utilizzata per firmare i 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 delle 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 firmare i 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()

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 di macchina aziendale supportata da hardware ed emette la risposta come parte di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API Verified Access Web, che verifica e verifica le risposte.

Una verifica con esito positivo da parte dell'API Verified Access Web è un segnale chiaro che il dispositivo corrente è un dispositivo ChromeOS legittimo, che il dispositivo attuale è gestito dal dominio specificato durante la verifica, che l'utente che ha attualmente eseguito l'accesso è gestito dal dominio specificato durante la verifica e 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. Se l'ambito "user" viene specificato, l'identità è anche strettamente associata all'utente che ha attualmente eseguito l'accesso.

Questa funzione è altamente limitata e non riuscirà se il dispositivo attuale non è gestito, l'utente corrente non è gestito o se l'operazione non è stata attivata esplicitamente per il chiamante in base ai criteri relativi ai dispositivi aziendali. La chiave sottoposta a richiesta di verifica non risiede nel token "system" o "user" e non è accessibile a nessun'altra API.

Parametri

  • opzioni del modello.

    ChallengeKeyOptions

    Oggetto contenente i campi definiti in ChallengeKeyOptions.

  • callback

    funzione

    Il parametro callback ha un aspetto simile al seguente: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla sfida.

challengeMachineKey()

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

Usa invece challengeKey.

Verifica una chiave di macchina aziendale supportata da hardware ed emette la risposta come parte di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API Verified Access Web, che verifica e verifica le risposte. Una verifica con esito positivo da parte dell'API web Verified Access è un segnale chiaro di tutti i seguenti aspetti: * Il dispositivo attuale è un dispositivo ChromeOS legittimo. * Il dispositivo corrente è gestito dal dominio specificato durante la verifica. * L'utente che ha attualmente 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 è altamente limitata e non riuscirà se il dispositivo attuale non è gestito, l'utente corrente non è gestito o se l'operazione non è stata attivata esplicitamente per il chiamante in base ai criteri relativi ai dispositivi aziendali. La chiave macchina aziendale non risiede nel token "system" e non è accessibile a nessun'altra API.

Parametri

  • challenge

    ArrayBuffer

    Una verifica presentata dall'API Verified Access Web.

  • registerKey

    booleano facoltativo

    Chrome 59 e versioni successive

    Se impostato, l'attuale chiave macchina aziendale viene registrata con il token "system" e rinuncia al ruolo 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

    Il parametro callback ha un aspetto simile al seguente: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla sfida.

challengeUserKey()

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

Usa invece challengeKey.

Verifica una chiave utente aziendale supportata da hardware ed emette la risposta come parte di un protocollo di attestazione remota. Utile solo su ChromeOS e in combinazione con l'API Verified Access Web, che verifica e verifica le risposte. Una verifica con esito positivo da parte dell'API web Verified Access è un segnale chiaro di tutti i seguenti aspetti: * Il dispositivo attuale è un dispositivo ChromeOS legittimo. * Il dispositivo corrente è gestito dal dominio specificato durante la verifica. * L'utente che ha attualmente eseguito l'accesso è gestito dal dominio specificato durante la verifica. * L'attuale stato del dispositivo è conforme ai criteri relativi agli 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 attuale e all'utente che ha attualmente eseguito l'accesso. Questa funzione è altamente limitata e non riuscirà se il dispositivo attuale non è gestito, l'utente corrente non è gestito o se l'operazione non è stata attivata esplicitamente per il chiamante in base ai criteri relativi agli utenti aziendali. La chiave utente aziendale non risiede nel token "user" e non è accessibile a nessun'altra API.

Parametri

  • challenge

    ArrayBuffer

    Una verifica presentata dall'API Verified Access Web.

  • registerKey

    boolean

    Se impostato, l'attuale chiave utente aziendale viene registrata con il token "user" e rinuncia al ruolo 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

    Il parametro callback ha un aspetto simile al seguente: 

    (response: ArrayBuffer) => void

    • risposta

      ArrayBuffer

      La risposta alla sfida.

getCertificates()

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

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

Parametri

  • tokenId

    stringa

    L'ID di un token restituito da getTokens.

  • callback

    funzione

    Il parametro callback ha un aspetto simile al seguente: 

    (certificates: ArrayBuffer[]) => void

    • certificates

      ArrayBuffer[]

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

getTokens()

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

Restituisce i token disponibili. In una 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 che si tratta di un Chromebook).

Parametri

  • callback

    funzione

    Il parametro callback ha un aspetto simile al seguente: 

    (tokens: Token[]) => void

    • token

      Token[]

      L'elenco dei token disponibili.

importCertificate()

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

Importa certificate nel token specificato se la chiave certificata è già archiviata in questo token. Se la 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 facoltativa

    Il parametro callback ha un aspetto simile al seguente: 

    () => void

removeCertificate()

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 intasino la scelta dei certificati. Da utilizzare per liberare spazio di archiviazione 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 facoltativa

    Il parametro callback ha un aspetto simile al seguente: 

    () => void