Questa pagina fornisce dettagli per assistere gli implementatori di Keymaster HAL. Copre ogni tag nell'HAL, in quale versione di Keymaster è disponibile quel tag e se il tag è ripetibile. Ad eccezione di quanto indicato nelle descrizioni dei tag, tutti i tag seguenti vengono utilizzati durante la generazione della chiave per specificare le caratteristiche della chiave.
Per Keymaster 4, i tag sono definiti in platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , come 3.0/types.hal per Keymaster 3 e 4.0/types.hal per Keymaster 4. Per Keymaster 2 e versioni precedenti, i tag sono definiti in platform/hardware/libhardware/include/hardware/keymaster_defs.h .
Per le funzioni, vedere la pagina Funzioni Keymaster .
Tag::ACTIVE_DATETIME
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la data e l'ora in cui la chiave diventa attiva. Prima di questo momento, qualsiasi tentativo di utilizzare la chiave non riesce con ErrorCode::KEY_NOT_YET_VALID .
Il valore è un intero a 64 bit che rappresenta i millisecondi dal 1 gennaio 1970.
Tag::ALGORITMO
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica l'algoritmo crittografico con cui viene utilizzata la chiave.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class Algorithm : uint32_t {
RSA = 1,
EC = 3,
AES = 32,
HMAC = 128,
};
Keymaster 2 e precedenti
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Tag::TUTTE LE APPLICAZIONI
Versione : 1, 2, 3, 4
Ripetibile ? No
Riservato per uso futuro.
Tag::ALLOW_WHILE_ON_BODY
Versione : 2, 3, 4
Ripetibile ? No
Questo tag è applicabile solo ai dispositivi Android Wear con sensori sul corpo. A questo punto, non ci si aspetta che nessun TEE sia in grado di fornire un accesso sicuro a un sensore sul corpo, o che i sensori sul corpo siano molto sicuri, quindi questa dovrebbe essere una funzionalità puramente software.
Tag::ALL_USERS
Versione : 3, 4
Ripetibile ? No
Riservato per uso futuro.
Tag::DATI_APPLICAZIONE
Versione : 1, 2, 3, 4
Ripetibile ? No
Quando viene fornito a generateKey o importKey , questo tag specifica i dati necessari durante tutti gli usi della chiave. In particolare, le chiamate a exportKey e getKeyCharacteristics devono fornire lo stesso valore al parametro clientId e le chiamate per iniziare devono fornire questo tag e gli stessi dati associati come parte del set inParams . Se non vengono forniti i dati corretti, la funzione restituisce ErrorCode::INVALID_KEY_BLOB .
Il contenuto di questo tag è vincolato alla chiave crittograficamente , il che significa che non deve essere possibile per un avversario che ha accesso a tutti i segreti del mondo sicuro ma non ha accesso al contenuto del tag decrittografare la chiave senza forzare il tag contenuto, che le applicazioni possono impedire specificando un contenuto con entropia sufficientemente elevato.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Etichetta::ID_APPLICAZIONE
Versione : 1, 2, 3, 4
Ripetibile ? No
Quando viene fornito a generateKey o importKey , questo tag specifica i dati necessari durante tutti gli usi della chiave. In particolare, le chiamate a exportKey e getKeyCharacteristics devono fornire lo stesso valore nel parametro clientId e le chiamate per iniziare devono fornire questo tag e gli stessi dati associati come parte del set inParams . Se non vengono forniti i dati corretti, la funzione restituisce ErrorCode::INVALID_KEY_BLOB .
Il contenuto di questo tag è vincolato alla chiave crittograficamente , il che significa che un avversario che può accedere a tutti i segreti del mondo sicuro, ma non ha accesso al contenuto del tag, non può decrittografare la chiave (senza forzare il contenuto del tag ).
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::DATI_ASSOCIATI
Versione : 1, 2, 3, 4
Ripetibile ? No
Fornisce "dati associati" per la crittografia o la decrittografia AES-GCM. Questo tag viene fornito per aggiornare e specifica i dati che non sono crittografati/decrittografati, ma vengono utilizzati nel calcolo del tag GCM.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_APPLICATION_ID
Versione : 3, 4
Ripetibile ? No
Utilizzato per identificare l'insieme di possibili applicazioni di cui si è avviata un'attestazione chiave.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_CHALLENGE
Versione : 3, 4
Ripetibile ? No
Utilizzato per fornire una sfida nell'attestazione.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_BRAND
Versione : 3, 4
Ripetibile ? No
Fornisce il marchio del dispositivo, come restituito da Build.BRAND in Android. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_DEVICE
Versione : 3, 4
Ripetibile ? No
Fornisce il nome del dispositivo del dispositivo, come restituito da Build.DEVICE in Android. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_IMEI
Versione : 3, 4
Ripetibile ? sì
Fornisce gli IMEI per tutte le radio sul dispositivo. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_MANUFACTURER
Versione : 3, 4
Ripetibile ? No
Fornisce il nome del produttore del dispositivo, come restituito da Build.MANUFACTURER in Android. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_MEID
Versione : 3, 4
Ripetibile ? sì
Fornisce i MEID per tutte le radio sul dispositivo. Questo campo verrà impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_MODEL
Versione : 3, 4
Ripetibile ? No
Fornisce il nome del modello del dispositivo, come restituito da Build.MODEL in Android. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_PRODUCT
Versione : 3, 4
Ripetibile ? No
Fornisce il nome del prodotto del dispositivo, come restituito da Build.PRODUCT in Android. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::ATTESTATION_ID_SERIAL
Versione : 3, 4
Ripetibile ? No
Fornisce il numero di serie del dispositivo. Questo campo viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o è stato precedentemente chiamato destroyAttestationIds() e il dispositivo non può più attestare i suoi ID), qualsiasi richiesta di attestazione della chiave che include questo tag non riesce con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Etichetta::AUTH_TIMEOUT
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica il tempo in secondi per il quale la chiave è autorizzata all'uso, dopo l'autenticazione. Se Tag::USER_SECURE_ID è presente e questo tag non lo è, allora la chiave necessita di autenticazione per ogni utilizzo (vedi inizio per i dettagli del flusso di autenticazione per operazione).
Il valore è un numero intero a 32 bit che specifica il tempo in secondi dopo un'autenticazione riuscita dell'utente specificato da Tag::USER_SECURE_ID con il metodo di autenticazione specificato da Tag::USER_AUTH_TYPE in cui la chiave può essere utilizzata.
Etichetta::AUTH_TOKEN
Versione : 1, 2, 3, 4
Ripetibile ? No
Fornisce un token di autenticazione per iniziare , aggiornare o terminare , per provare l'autenticazione dell'utente per un'operazione con la chiave che la richiede (la chiave ha Tag::USER_SECURE_ID ).
Il valore è un BLOB che contiene una struttura hw_auth_token_t .
Tag::BLOB_USAGE_REQUIREMENTS
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica le condizioni ambientali di sistema necessarie per l'utilizzo della chiave generata.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class KeyBlobUsageRequirements : uint32_t {
STANDALONE = 0,
REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 e precedenti
typedef enum {
KM_BLOB_STANDALONE = 0,
KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;
Questo tag può essere specificato durante la generazione della chiave per richiedere che la chiave sia utilizzabile nella condizione specificata. Deve essere restituito con le caratteristiche chiave da generateKey e getKeyCharacteristics . Se il chiamante specifica Tag::BLOB_USAGE_REQUIREMENTS con valore KeyBlobUsageRequirements::STANDALONE , il trustlet restituisce un BLOB di chiavi che può essere utilizzato senza il supporto del file system. Questo è fondamentale per i dispositivi con dischi crittografati, in cui il file system potrebbe non essere disponibile fino a quando non viene utilizzata una chiave Keymaster per decrittografare il disco.
Etichetta::MODALITÀ_BLOCCO
Versione : 1, 2, 3, 4
Ripetibile ? sì
Specifica le modalità di cifratura a blocchi con cui è possibile utilizzare la chiave. Questo tag è rilevante solo per le chiavi AES.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class BlockMode : uint32_t {
ECB = 1,
CBC = 2,
CTR = 3,
GCM = 32,
};
Keymaster 2 e precedenti
typedef enum {
KM_MODE_ECB = 1,
KM_MODE_CBC = 2,
KM_MODE_CTR = 3,
KM_MODE_GCM = 32,
} keymaster_block_mode_t;
Questo tag è ripetibile e per le operazioni con i tasti AES specificare una modalità nell'argomento additionalParams di begin . Se la modalità specificata non è nelle modalità associate alla chiave, l'operazione non riesce con ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Tag::BOOT_PATCHLEVEL
Versione : 4
Tag::BOOT_PATCHLEVEL specifica il livello di patch di sicurezza dell'immagine di avvio (kernel) con cui è possibile utilizzare la chiave. Questo tag non viene mai inviato al keymaster TA, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dal TA. Qualsiasi tentativo di utilizzare una chiave con un valore Tag::BOOT_PATCHLEVEL diverso dal patchlevel di sistema attualmente in esecuzione fa sì che begin() , getKeyCharacteristics() o exportKey() restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedere upgradeKey() per i dettagli.
Il valore del tag è un numero intero nella forma AAAAMMGG, dove AAAA è l'anno a quattro cifre dell'ultimo aggiornamento, MM è il mese a due cifre e GG è il giorno a due cifre dell'ultimo aggiornamento. Ad esempio, per una chiave generata su un dispositivo Android aggiornato l'ultima volta il 5 giugno 2018, il valore sarebbe 20180605. Se il giorno non è noto, è possibile sostituire 00.
Durante ogni avvio, il bootloader deve fornire il livello di patch dell'immagine di avvio all'ambiente protetto (il meccanismo è definito dall'implementazione).
Deve essere applicato tramite hardware.
Tag::BOOTLOADER_SOLO
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica che solo il bootloader può utilizzare la chiave.
Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).
Qualsiasi tentativo di utilizzare una chiave con Tag::BOOTLOADER_ONLY dal sistema Android non riesce con ErrorCode::INVALID_KEY_BLOB .
Etichetta::CHIAMANTE_NONCE
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica che il chiamante può fornire un nonce per le operazioni che non lo richiedono.
Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).
Questo tag viene utilizzato solo per le chiavi AES ed è rilevante solo per le modalità di blocco CBC, CTR e GCM. Se il tag non è presente, le implementazioni dovrebbero rifiutare qualsiasi operazione che prevede che Tag::NONCE inizi con ErrorCode::CALLER_NONCE_PROHIBITED .
Tag::CREATION_DATETIME
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la data e l'ora di creazione della chiave, in millisecondi dal 1 gennaio 1970. Questo tag è facoltativo e solo informativo.
Tag::DIGEST
Versione : 1, 2, 3, 4
Ripetibile ? sì
Specifica gli algoritmi digest che possono essere utilizzati con la chiave per eseguire operazioni di firma e verifica. Questo tag è rilevante per le chiavi RSA, ECDSA e HMAC.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class Digest : uint32_t {
NONE = 0,
MD5 = 1,
SHA1 = 2,
SHA_2_224 = 3,
SHA_2_256 = 4,
SHA_2_384 = 5,
SHA_2_512 = 6,
};
Keymaster 2 e precedenti
typedef enum {
KM_DIGEST_NONE = 0,
KM_DIGEST_MD5 = 1,
KM_DIGEST_SHA1 = 2,
KM_DIGEST_SHA_2_224 = 3,
KM_DIGEST_SHA_2_256 = 4,
KM_DIGEST_SHA_2_384 = 5,
KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;
Questo tag è ripetibile. Per le operazioni di firma e verifica, specificare un digest nell'argomento additionalParams di begin . Se il digest specificato non è nei digest associati alla chiave, l'operazione non riesce con ErrorCode::INCOMPATIBLE_DIGEST .
Etichetta::CURVA_EC
Versione : 2, 3, 4
Ripetibile ? No
In Keymaster 1, la curva utilizzata per le chiavi EC è stata ricavata dalla dimensione della chiave specificata. Per migliorare la flessibilità in futuro, Keymaster 2 ha introdotto un modo esplicito per specificare le curve. Le richieste di generazione di chiavi EC possono avere Tag::EC_CURVE , Tag::KEY_SIZE o entrambi.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Keymaster 2 e precedenti
enum class EcCurve : uint32_t {
P_224 = 0,
P_256 = 1,
P_384 = 2,
P_521 = 3,
};
Se una richiesta di generazione contiene solo Tag::KEY_SIZE , torna alla logica Keymaster 1, scegliendo la curva NIST appropriata.
Se la richiesta contiene solo Tag::EC_CURVE , utilizzare la curva specificata. Per Keymaster 3 e versioni successive, le curve sono definite in EcCurve . Per Keymaster 2 e precedenti, le curve sono definite in keymaster_ec_curve_t .
Se la richiesta contiene entrambi, utilizzare la curva specificata da Tag::EC_CURVE e verificare che la dimensione della chiave specificata sia appropriata per quella curva. In caso contrario, restituire ErrorCode::INVALID_ARGUMENT .
Tag::INCLUDE_UNIQUE_ID
Versione : 2, 3, 4
Ripetibile ? No
Questo tag viene specificato durante la generazione della chiave per indicare che un certificato di attestazione per la chiave generata deve contenere un ID dispositivo univoco nell'ambito dell'applicazione e limitato nel tempo, come specificato da Tag::UNIQUE_ID .
Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).
Etichetta::KEY_SIZE
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la dimensione, in bit, della chiave, misurata in modo normale per l'algoritmo della chiave. Ad esempio, per le chiavi RSA, Tag::KEY_SIZE specifica la dimensione del modulo pubblico. Per le chiavi AES specifica la lunghezza del materiale della chiave segreta.
Etichetta::LUNGHEZZA_MAC
Versione : 1, 2, 3, 4
Ripetibile ? No
Fornisce la lunghezza richiesta di un tag di autenticazione MAC o GCM, in bit.
Il valore è la lunghezza MAC in bit. È un multiplo di 8 e almeno grande quanto il valore di Tag::MIN_MAC_LENGTH associato alla chiave.
Tag::MAX_USES_PER_BOOT
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica il numero massimo di volte in cui una chiave può essere utilizzata tra i riavvii del sistema. Questo è un altro meccanismo per limitare il tasso di utilizzo delle chiavi.
Il valore è un numero intero a 32 bit che rappresenta gli utilizzi per avvio.
Quando una chiave con questo tag viene utilizzata in un'operazione, un contatore associato alla chiave deve essere incrementato durante la chiamata iniziale . Dopo che il contatore di chiavi ha superato questo valore, tutti i tentativi successivi di utilizzare la chiave hanno esito negativo con ErrorCode::MAX_OPS_EXCEEDED , fino al riavvio del dispositivo. Ciò implica che un trustlet mantiene una tabella dei contatori di utilizzo per le chiavi con questo tag. Poiché la memoria di Keymaster è spesso limitata, questa tabella può avere una dimensione massima fissa e Keymaster può non riuscire a operazioni che tentano di utilizzare chiavi con questo tag quando la tabella è piena. Il tavolo deve ospitare almeno 16 chiavi. Se un'operazione non riesce perché la tabella è piena, Keymaster restituisce ErrorCode::TOO_MANY_OPERATIONS .
Tag::MIN_MAC_LENGTH
Versione : 1, 2, 3, 4
Ripetibile ? No
Questo tag specifica la lunghezza minima di MAC che può essere richiesta o verificata con questa chiave per le chiavi HMAC e le chiavi AES che supportano la modalità GCM.
Questo valore è la lunghezza minima del MAC, in bit. È un multiplo di 8. Per le chiavi HMAC, il valore è almeno 64. Per le chiavi GCM, il valore è almeno 96 e non più di 128.
Tag::MIN_SECONDS_BETWEEN_OPS
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la quantità di tempo minima che trascorre tra le operazioni consentite utilizzando una chiave. Questo può essere utilizzato per limitare gli usi delle chiavi in contesti in cui l'uso illimitato può consentire attacchi di forza bruta.
Il valore è un numero intero a 32 bit che rappresenta i secondi tra le operazioni consentite.
Quando una chiave con questo tag viene utilizzata in un'operazione, avviare un timer durante l' arrivo o interrompere la chiamata. Qualsiasi chiamata all'inizio ricevuta prima del timer indica che l'intervallo specificato da Tag::MIN_SECONDS_BETWEEN_OPS ha esito negativo con ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Ciò implica che un trustlet mantiene una tabella dei contatori di utilizzo per le chiavi con questo tag. Poiché la memoria di Keymaster è spesso limitata, questa tabella può avere una dimensione massima fissa e Keymaster può non riuscire a operazioni che tentano di utilizzare chiavi con questo tag quando la tabella è piena. La tabella deve contenere almeno 32 chiavi in uso e riutilizzare in modo aggressivo gli slot della tabella quando scadono gli intervalli di utilizzo minimo delle chiavi. Se un'operazione non riesce perché la tabella è piena, Keymaster restituisce ErrorCode::TOO_MANY_OPERATIONS .
Tag::NO_AUTH_REQUIRED
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica che non è richiesta alcuna autenticazione per utilizzare questa chiave. Questo tag si esclude a vicenda con Tag::USER_SECURE_ID .
Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).
Etichetta::NONCE
Versione : 1, 2, 3, 4
Ripetibile ? No
Fornisce o restituisce un nonce o un vettore di inizializzazione (IV) per la crittografia o la decrittografia AES GCM, CBC o CTR. Questo tag viene fornito per iniziare durante le operazioni di crittografia e decrittografia. Viene fornito solo per iniziare se la chiave ha Tag::CALLER_NONCE . Se non fornito, un nonce o IV appropriato verrà generato casualmente da Keymaster e restituito dall'inizio.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria. Le lunghezze consentite dipendono dalla modalità: le nonce GCM hanno una lunghezza di 12 byte; Gli IV CBC e CTR sono lunghi 16 byte.
Etichetta::ORIGINE
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica dove è stata creata la chiave, se nota. Questo tag potrebbe non essere specificato durante la generazione o l'importazione della chiave e deve essere aggiunto alle caratteristiche della chiave dal trustlet.
Maestro delle chiavi 3 I possibili valori sono definiti in android::hardware::keymaster::v3_0::KeyOrigin :
enum class KeyOrigin : uint32_t {
GENERATED = 0,
DERIVED = 1,
IMPORTED = 2,
UNKNOWN = 3,
};
Keymaster 2 e precedenti I possibili valori sono definiti in keymaster_origin_t :
typedef enum {
KM_ORIGIN_GENERATED = 0,
KM_ORIGIN_IMPORTED = 2,
KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t
Il significato completo del valore dipende non solo dal valore, ma anche dal fatto che si trovi nell'elenco delle caratteristiche applicate dall'hardware o dal software.
GENERATED indica che Keymaster ha generato la chiave. Se nell'elenco dell'applicazione hardware, la chiave è stata generata in hardware protetto ed è permanentemente vincolata all'hardware. Se nell'elenco delle applicazioni software, la chiave è stata generata in SoftKeymaster e non è vincolata all'hardware.
DERIVED indica che la chiave è stata derivata all'interno di Keymaster. Probabilmente esiste fuori dispositivo.
IMPORTED indica che la chiave è stata generata al di fuori di Keymaster e importata in Keymaster. Se nell'elenco dell'hardware applicato, è permanentemente vincolato all'hardware, sebbene possano esistere copie al di fuori dell'hardware protetto. Se nell'elenco delle applicazioni software, la chiave è stata importata in SoftKeymaster e non è vincolata all'hardware.
UNKNOWN dovrebbe apparire solo nell'elenco dell'hardware. Indica che la chiave è legata all'hardware, ma non è noto se la chiave sia stata originariamente generata in hardware protetto o sia stata importata. Ciò si verifica solo quando l'hardware keymaster0 viene utilizzato per emulare i servizi keymaster1.
Tag::ORIGINATION_EXPIRE_DATETIME
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la data e l'ora in cui la chiave scade ai fini della firma e della crittografia. Trascorso questo tempo, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::SIGN o KeyPurpose::ENCRYPT fornito per iniziare non riesce con ErrorCode::KEY_EXPIRED .
Il valore è un intero a 64 bit che rappresenta i millisecondi dal 1 gennaio 1970.
Tag::OS_PATCHLEVEL
Versione : 2, 3, 4
Ripetibile ? No
Questo tag non viene mai inviato al keymaster TA, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dal TA.
Il valore del tag è un numero intero nel formato AAAAMM, dove AAAA è l'anno a quattro cifre dell'ultimo aggiornamento e MM è il mese a due cifre dell'ultimo aggiornamento. Ad esempio, per una chiave generata su un dispositivo Android aggiornato l'ultima volta a dicembre 2015, il valore sarebbe 201512.
I tasti che hanno un livello di patch diverso dal livello di patch corrente non sono utilizzabili. Un tentativo di utilizzare tale chiave fa sì che begin , getKeyCharacteristics o exportKey restituisca ErrorCode::KEY_REQUIRES_UPGRADE . Vedere Associazione alla versione per maggiori dettagli.
Tag::VERSIONE_OS
Versione : 2, 3, 4
Ripetibile ? No
Questo tag non viene mai inviato al keymaster TA, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dal TA.
Il valore del tag è un numero intero nella forma MMmmss, dove MM è il numero di versione principale, mm è il numero di versione secondaria e ss è il numero di versione secondaria. Ad esempio, per una chiave generata su Android versione 4.0.3, il valore sarebbe 040003.
Tag::IMBOTTITURA
Versione : 1, 2, 3, 4
Ripetibile ? sì
Specifica le modalità di riempimento che possono essere utilizzate con la chiave. Questo tag è rilevante per le chiavi RSA e AES.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class PaddingMode : uint32_t {
NONE = 1,
RSA_OAEP = 2,
RSA_PSS = 3,
RSA_PKCS1_1_5_ENCRYPT = 4,
RSA_PKCS1_1_5_SIGN = 5,
PKCS7 = 64,
};
Keymaster 2 e precedenti
typedef enum {
KM_PAD_NONE = 1,
KM_PAD_RSA_OAEP = 2,
KM_PAD_RSA_PSS = 3,
KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
KM_PAD_PKCS7 = 64,
} keymaster_padding_t;
PaddingMode::RSA_OAEP e PaddingMode::RSA_PKCS1_1_5_ENCRYPT vengono utilizzati solo per le chiavi di crittografia/decrittografia RSA e specificano rispettivamente il riempimento RSA PKCS#1v2 OAEP e il riempimento randomizzato RSA PKCS#1 v1.5. PaddingMode::RSA_PSS e PaddingMode::RSA_PKCS1_1_5_SIGN vengono utilizzati solo per le chiavi di firma/verifica RSA e specificano rispettivamente il padding PSS RSA PKCS#1v2 e il padding deterministico RSA PKCS#1 v1.5.
PaddingMode::NONE può essere utilizzato con chiavi RSA o AES. Per le chiavi AES, se PaddingMode::NONE viene utilizzato con ECB o CBC in modalità blocco e i dati da crittografare o decrittografare non sono un multiplo della dimensione del blocco AES in lunghezza, la chiamata al completamento ha esito negativo con ErrorCode::INVALID_INPUT_LENGTH .
PaddingMode::PKCS7 può essere utilizzato solo con chiavi AES e solo con modalità ECB e CBC.
Questo tag è ripetibile. Per iniziare è necessario specificare una modalità di riempimento nella chiamata. Se la modalità specificata non è autorizzata per la chiave, l'operazione non riesce con ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Etichetta::SCOPO
Versione : 1, 2, 3, 4
Ripetibile ? sì
Specifica l'insieme di scopi per i quali è possibile utilizzare la chiave.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3
enum class KeyPurpose : uint32_t {
ENCRYPT = 0,
DECRYPT = 1,
SIGN = 2,
VERIFY = 3,
DERIVE_KEY = 4, // since 3.0
WRAP_KEY = 5, // since 3.0
};
Keymaster 2 e precedenti
typedef enum {
KM_PURPOSE_ENCRYPT = 0,
KM_PURPOSE_DECRYPT = 1,
KM_PURPOSE_SIGN = 2,
KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;
Questo tag è ripetibile; le chiavi possono essere generate con più valori, sebbene un'operazione abbia un unico scopo. Quando la funzione di inizio viene chiamata per avviare un'operazione, viene specificato lo scopo dell'operazione. Se lo scopo specificato per l'operazione non è autorizzato dalla chiave, l'operazione non riesce con ErrorCode::INCOMPATIBLE_PURPOSE .
Tag::RESET_SINCE_ID_ROTATION
Versione : 3, 4
Ripetibile ? No
Specifica se il dispositivo è stato ripristinato in fabbrica dall'ultima rotazione dell'ID univoco. Utilizzato per l'attestazione chiave.
Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).
Tag::ROLLBACK_RESISTANT
Versione : 1, 2, 3, 4
Ripetibile ? No
Indica che la chiave è resistente al rollback, il che significa che quando viene eliminata da deleteKey o deleteAllKeys , è garantito che la chiave sia eliminata in modo permanente e inutilizzabile. È possibile che le chiavi senza questo tag possano essere eliminate e quindi ripristinate dal backup.
Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).
Tag::ROOT_OF_TRUST
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la radice di fiducia , la chiave utilizzata dall'avvio verificato per convalidare il sistema operativo avviato (se presente). Questo tag non viene mai fornito o restituito da Keymaster nelle caratteristiche chiave.
Tag::RSA_PUBLIC_EXPONENT
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica il valore dell'esponente pubblico per una coppia di chiavi RSA. Questo tag è rilevante solo per le chiavi RSA e necessario per tutte le chiavi RSA.
Il valore è un intero senza segno a 64 bit che soddisfa i requisiti di un esponente pubblico RSA. Questo valore deve essere un numero primo. I trustlet supportano il valore 2^16+1 e possono supportare altri valori ragionevoli, in particolare il valore 3. Se non viene specificato alcun esponente o se l'esponente specificato non è supportato, la generazione della chiave non riesce con ErrorCode::INVALID_ARGUMENT .
Etichetta::ID_UNICO
Versione : 3, 4
Ripetibile ? No
Utilizzato per fornire un ID univoco nell'attestazione.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag::USAGE_EXPIRE_DATETIME
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la data e l'ora di scadenza della chiave per scopi di verifica e decrittografia. Trascorso questo tempo, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::VERIFY o KeyPurpose::DECRYPT fornito per iniziare non riesce con ErrorCode::KEY_EXPIRED .
Il valore è un intero a 64 bit che rappresenta i millisecondi dal 1 gennaio 1970.
Etichetta::USER_AUTH_TYPE
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica i tipi di autenticatori utente che possono essere utilizzati per autorizzare questa chiave. Quando a Keymaster viene richiesto di eseguire un'operazione con una chiave con questo tag, riceve un token di authenticator_type e il campo tipo_autenticatore del token deve corrispondere al valore nel tag. Ad esempio, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0 , dove ntoh è una funzione che converte gli interi ordinati in rete in interi ordinati dall'host e auth_type_tag_value è il valore di questo tag.
Il valore è una maschera di bit intera a 32 bit di valori dall'enumerazione:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
Keymaster 2 e precedenti
typedef enum {
HW_AUTH_NONE = 0,
HW_AUTH_PASSWORD = 1 << 0,
HW_AUTH_FINGERPRINT = 1 << 1,
// Additional entries should be powers of 2.
HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;
Etichetta::USER_SECURE_ID
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica che una chiave può essere utilizzata solo in uno stato di autenticazione utente sicuro particolare. Questo tag si esclude a vicenda con Tag::NO_AUTH_REQUIRED .
Il valore è un numero intero a 64 bit che specifica il valore dello stato della politica di autenticazione che deve essere presente in un token di autenticazione (a condizione che inizi con Tag::AUTH_TOKEN ) per autorizzare l'uso della chiave. Qualsiasi chiamata che inizia con una chiave con questo tag che non fornisce un token di autenticazione o fornisce un token di autenticazione senza un valore di stato della politica corrispondente, non riesce.
Questo tag è ripetibile. Se uno qualsiasi dei valori forniti corrisponde a qualsiasi valore dello stato della politica nel token di autenticazione, la chiave è autorizzata per l'uso. In caso contrario, l'operazione non riesce con ErrorCode::KEY_USER_NOT_AUTHENTICATED .
Tag::VENDOR_PATCHLEVEL
Versione : 4
Questo tag specifica il livello di patch di sicurezza dell'immagine del fornitore con cui è possibile utilizzare la chiave. Questo tag non viene mai inviato al keymaster TA, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dal TA. Qualsiasi tentativo di utilizzare una chiave con un valore Tag::VENDOR_PATCHLEVEL diverso dal patchlevel di sistema attualmente in esecuzione deve causare begin() , getKeyCharacteristics() o exportKey() per restituire ErrorCode::KEY_REQUIRES_UPGRADE . Vedere upgradeKey() per i dettagli.
Il valore del tag è un numero intero nella forma AAAAMMGG, dove AAAA è l'anno a quattro cifre dell'ultimo aggiornamento, MM è il mese a due cifre e GG è il giorno a due cifre dell'ultimo aggiornamento. Ad esempio, per una chiave generata su un dispositivo Android aggiornato l'ultima volta il 5 giugno 2018, il valore sarebbe 20180605.
L'HAL di IKeymasterDevice deve leggere l'attuale livello di patch del fornitore dalla proprietà di sistema ro.vendor.build.security_patch e consegnarlo all'ambiente sicuro quando l'HAL viene caricato per la prima volta (il meccanismo è definito dall'implementazione). L'ambiente protetto non deve accettare un altro livello di patch fino al successivo avvio.
Deve essere applicato tramite hardware.