Questa pagina fornisce dettagli per assistere gli implementatori di Keymaster HAL. Copre ogni tag nell'HAL, in quale versione di Keymaster quel tag è disponibile e se il tag è ripetibile. Ad eccezione di quanto indicato nelle descrizioni dei tag, tutti i tag di seguito 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 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 questa volta, qualsiasi tentativo di utilizzare la chiave non riesce con ErrorCode::KEY_NOT_YET_VALID .
Il valore è un numero 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 versioni precedenti
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Etichetta :: ALL_APPLICATIONS
Versione : 1, 2, 3, 4
Ripetibile ? No
Riservato per uso futuro.
Etichetta :: 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 alcun 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 funzione puramente applicata dal software.
Etichetta :: ALL_USERS
Versione : 3, 4
Ripetibile ? No
Riservato per uso futuro.
Etichetta :: APPLICATION_DATA
Versione : 1, 2, 3, 4
Ripetibile ? No
Quando 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 per decrittografare la chiave senza forzare il tag contenuto, che le applicazioni possono impedire specificando un contenuto sufficientemente elevato di entropia.
Il valore è un BLOB, una matrice di byte di lunghezza arbitraria.
Tag :: APPLICATION_ID
Versione : 1, 2, 3, 4
Ripetibile ? No
Quando 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 è associato alla chiave in modo crittografico , 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 :: ASSOCIATED_DATA
Versione : 1, 2, 3, 4
Ripetibile ? No
Fornisce "dati associati" per crittografia o decrittografia AES-GCM. Questo tag viene fornito per aggiornare e specifica i dati che non sono crittografati / decrittografati, ma vengono utilizzati nell'elaborazione 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.
Etichetta :: 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 nome del 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 se in precedenza era stato 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 se in precedenza era stato 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 se in precedenza era stato 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 se in precedenza era stato 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 se in precedenza era stato 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 :: 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 se in precedenza era stato 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 :: 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 se in precedenza era stato chiamato destroyAttestationIds() e il dispositivo non può più attestare i propri 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 se in precedenza era stato 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 :: AUTH_TIMEOUT
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica il tempo in secondi per il quale la chiave è autorizzata per l'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 dimostrare l'autenticazione dell'utente per un'operazione chiave che lo richiede (la chiave ha Tag :: USER_SECURE_ID ).
Il valore è un blob che contiene una struttura hw_auth_token_t .
Etichetta :: BLOB_USAGE_REQUIREMENTS
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica le condizioni dell'ambiente di sistema necessarie per utilizzare la 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 versioni 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 di generateKey e getKeyCharacteristics . Se il chiamante specifica Tag::BLOB_USAGE_REQUIREMENTS con il valore KeyBlobUsageRequirements::STANDALONE il trustlet restituisce un blob di chiavi che può essere utilizzato senza il supporto del file system. Ciò è 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 :: BLOCK_MODE
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 versioni 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 .
Etichetta :: 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 TA keymaster, ma viene aggiunto all'elenco di autorizzazioni applicate dall'hardware dal TA. Qualsiasi tentativo di utilizzare una chiave con un valore Tag::BOOT_PATCHLEVEL diverso dal livello di patch 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 hardware.
Etichetta :: BOOTLOADER_ONLY
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 :: CALLER_NONCE
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica che il chiamante può fornire un nonce per le operazioni che richiedono il nonce.
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 in cui è stata creata la chiave, in millisecondi dal 1 gennaio 1970. Questo tag è facoltativo e solo informativo.
Etichetta :: 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 versioni 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 :: EC_CURVE
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à andando avanti, 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 versioni 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 , ripiegare sulla logica Keymaster 1, scegliendo la curva NIST appropriata.
Se la richiesta contiene solo Tag::EC_CURVE , utilizza la curva specificata. Per Keymaster 3 e EcCurve successive, le curve sono definite in EcCurve . Per Keymaster 2 e keymaster_ec_curve_t precedenti, le curve sono definite in keymaster_ec_curve_t .
Se la richiesta contiene entrambi, utilizza la curva specificata da Tag::EC_CURVE e verifica che la dimensione della chiave specificata sia appropriata per quella curva. In caso contrario, restituisci 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 univoco del dispositivo con 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 nel 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 :: MAC_LENGTH
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 pari al 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 che una chiave può essere utilizzata tra i riavvii del sistema. Questo è un altro meccanismo per limitare l'utilizzo delle chiavi.
Il valore è un numero intero a 32 bit che rappresenta gli utilizzi per l'avvio.
Quando una chiave con questo tag viene utilizzato in un'operazione, un contatore a chiave associata deve essere incrementato durante il cominciare chiamata. Dopo che il contatore della chiave ha superato questo valore, tutti i successivi tentativi di utilizzare la chiave hanno esito negativo con ErrorCode::MAX_OPS_EXCEEDED , fino al riavvio del dispositivo. Ciò implica che un trustlet mantenga 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ò fallire le operazioni che tentano di utilizzare chiavi con questo tag quando la tabella è piena. Il tavolo deve contenere almeno 16 chiavi. Se un'operazione fallisce perché la tabella è piena, Keymaster restituisce ErrorCode::TOO_MANY_OPERATIONS .
Etichetta :: MIN_MAC_LENGTH
Versione : 1, 2, 3, 4
Ripetibile ? No
Questo tag specifica la lunghezza minima del MAC che può essere richiesta o verificata con questa chiave per chiavi HMAC e chiavi AES che supportano la modalità GCM.
Questo valore è la lunghezza MAC minima, in bit. È un multiplo di 8. Per le chiavi HMAC, il valore è almeno 64. Per le chiavi GCM, il valore è almeno 96 e non superiore a 128.
Etichetta :: 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 la frequenza degli 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 la fine o interrompere la chiamata. Qualsiasi chiamata di inizio ricevuta prima del timer indica che l'intervallo specificato da Tag::MIN_SECONDS_BETWEEN_OPS è scaduto non riesce con ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Ciò implica che un trustlet mantenga 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ò fallire le 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 fallisce perché la tabella è piena, Keymaster restituisce ErrorCode::TOO_MANY_OPERATIONS .
Etichetta :: 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 Initialization Vector (IV) per la crittografia o 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 in modo casuale 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; CBC e CTR IV hanno una lunghezza di 16 byte.
Etichetta :: ORIGIN
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.
Keymaster 3 I valori possibili 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 versioni 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 si trova nell'elenco applicato dall'hardware, la chiave è stata generata in un hardware protetto ed è associata in modo permanente all'hardware. Se nell'elenco applicato dal software, la chiave è stata generata in SoftKeymaster e non è vincolata all'hardware.
DERIVED indica che la chiave è stata derivata all'interno di Keymaster. È probabile che esista fuori dal dispositivo.
IMPORTED indica che la chiave è stata generata all'esterno di Keymaster e importata in Keymaster. Se si trova nell'elenco applicato dall'hardware, è permanentemente associato 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 applicato dall'hardware. Indica che la chiave è collegata all'hardware, ma non è noto se la chiave sia stata originariamente generata in un 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. Dopo 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 numero intero a 64 bit che rappresenta i millisecondi dal 1 gennaio 1970.
Etichetta :: OS_PATCHLEVEL
Versione : 2, 3, 4
Ripetibile ? No
Questo tag non viene mai inviato al TA keymaster, ma viene aggiunto all'elenco di autorizzazioni applicate dall'hardware dal TA.
Il valore del tag è un numero intero nella forma 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.
Le chiavi che hanno un livello di patch diverso dal livello di patch corrente non sono utilizzabili. Un tentativo di utilizzare una chiave di questo tipo fa sì che begin , getKeyCharacteristics o exportKey restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedere Associazione della versione per ulteriori dettagli.
Etichetta :: OS_VERSION
Versione : 2, 3, 4
Ripetibile ? No
Questo tag non viene mai inviato al TA keymaster, ma viene aggiunto all'elenco di 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 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 versioni 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 casuale 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 riempimento RSA PKCS # 1v2 PSS e il riempimento 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 la modalità blocco ECB o CBC e i dati da crittografare o decrittografare non sono un multiplo della dimensione del blocco AES in lunghezza, la chiamata al completamento fallisce 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 la serie di scopi per i quali la chiave può essere utilizzata.
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 versioni 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 .
Etichetta :: RESET_SINCE_ID_ROTATION
Versione : 3, 4
Ripetibile ? No
Specifica se il dispositivo è stato ripristinato ai dati di 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).
Etichetta :: 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 sarà 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).
Etichetta :: ROOT_OF_TRUST
Versione : 1, 2, 3, 4
Ripetibile ? No
Specifica la radice di attendibilità , 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.
Etichetta :: 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 fallisce con ErrorCode::INVALID_ARGUMENT .
Tag :: UNIQUE_ID
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 in cui scade la chiave a scopo di verifica e decrittografia. Dopo 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 numero 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 viene richiesto a Keymaster di eseguire un'operazione con una chiave con questo tag, riceve un token di autenticazione e il campo authenticator_type 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 dalla 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 dei valori dell'enumerazione:
Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
NONE = 0u, // 0
PASSWORD = 1 << 0,
FINGERPRINT = 1 << 1,
ANY = UINT32_MAX,
};
Keymaster 2 e versioni 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 (fornito per iniziare con Tag :: AUTH_TOKEN ) per autorizzare l'uso della chiave. Qualsiasi chiamata che inizi 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 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 .
Etichetta :: 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 TA keymaster, ma viene aggiunto all'elenco di autorizzazioni applicate dall'hardware dal TA. Qualsiasi tentativo di utilizzare una chiave con un valore Tag::VENDOR_PATCHLEVEL diverso dal livello di patch di sistema attualmente in esecuzione deve far 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.
L'HAL di IKeymasterDevice deve leggere il livello di patch del fornitore corrente dalla proprietà di sistema ro.vendor.build.security_patch e consegnarlo all'ambiente protetto 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 hardware.