Descrizione
Usa 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à
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 successivamente.Genera una coppia di chiavi utilizzando il metodo
generateKey
Token (definito in SubtleCrypto). L'handle verrà restituito 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).Completa la richiesta di certificazione e inviala all'autorità di certificazione.
Se un certificato viene ricevuto, importalo utilizzando enterprise.platformKeys.importCertificate
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
Tipo di chiave da generare.
Enum
ChallengeKeyOptions
Proprietà
-
challenge
ArrayBuffer
Una verifica presentata dall'API Verified Access Web.
-
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 valorescope
specificato. -
ambito
Quale chiave aziendale sfidare.
RegisterKeyOptions
Proprietà
-
algoritmo
L'algoritmo che deve essere utilizzato dalla chiave registrata.
Scope
Indica se utilizzare la chiave utente Enterprise o la chiave macchina Enterprise.
Enum
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 daenterprise.platformKeys.getTokens
. -
softwareBackedSubtleCrypto
SubtleCrypto
Chrome 97 e versioni successiveImplementa 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é conwindow.crypto.subtle
. Analogamente, gli oggettiKey
creati conwindow.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 connamedCurve
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é conwindow.crypto.subtle
. Analogamente, gli oggettiKey
creati conwindow.crypto.subtle
non possono essere utilizzati con questa interfaccia.
Metodi
challengeKey()
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 Verified Access Web, che emette le verifiche e verifica le risposte.
Una verifica con esito positivo da parte dell'API Verified Access Web è un segnale chiaro che il dispositivo attuale è 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 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
-
opzioni
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>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
challengeMachineKey()
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 emette le verifiche 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 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 si trova nel token "system"
e non è accessibile da nessun'altra API.
Parametri
-
challenge
ArrayBuffer
Una verifica presentata dall'API Verified Access Web.
-
registerKey
booleano facoltativo
Chrome 59 e versioni successiveSe 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 aziendale. -
callback
function facoltativa
Il parametro
callback
ha il seguente aspetto:(response: ArrayBuffer) => void
-
risposta
ArrayBuffer
La risposta alla verifica.
-
Resi
-
Promise<ArrayBuffer>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
challengeUserKey()
chrome.enterprise.platformKeys.challengeUserKey(
challenge: ArrayBuffer,
registerKey: boolean,
callback?: function,
)
Utilizza 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 emette le verifiche e verifica le risposte. Una verifica con esito positivo da parte dell'API web Verified Access è un indicatore significativo di tutte le seguenti condizioni: * Il dispositivo attuale è 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 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 attuale e all'utente che ha attualmente 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 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
booleano
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 facoltativa
Il parametro
callback
ha il seguente aspetto:(response: ArrayBuffer) => void
-
risposta
ArrayBuffer
La risposta alla verifica.
-
Resi
-
Promise<ArrayBuffer>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
getCertificates()
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
funzione 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[]>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
getTokens()
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
Resi
-
Prometti<Token[]>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
importCertificate()
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
-
Promesso<void>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.
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 ingombrino la scelta del certificato. 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
function facoltativa
Il parametro
callback
ha il seguente aspetto:() => void
Resi
-
Promesso<void>
In attesaLe promesse sono supportate solo per Manifest V3 e versioni successive, mentre le altre piattaforme devono utilizzare i callback.