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 precedenti, i tag sono definiti in platform/hardware/libhardware/include/hardware/keymaster_defs.h .
Per le funzioni, vedere la pagina Funzioni Keymaster .
Etichetta::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 fallisce 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 precedenti
typedef enum {
KM_ALGORITHM_RSA = 1,
KM_ALGORITHM_EC = 3,
KM_ALGORITHM_AES = 32,
KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;
Etichetta::TUTTE_APPLICAZIONI
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 per i dispositivi Android Wear con sensori incorporati. A questo punto, non ci si aspetta che un 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 caratteristica puramente applicata dal software.
Etichetta::ALL_USERS
Versione : 3, 4
Ripetibile ? NO
Riservato per uso futuro.
Etichetta::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 a begin 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 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 con un'entropia sufficientemente elevata.
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 a begin 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 protetto, ma non ha accesso al contenuto del tag, non può decrittografare la chiave (senza forzare brutamente il contenuto del tag ).
Il valore è un blob, una matrice di byte di lunghezza arbitraria.
Etichetta::DATI_ASSOCIATI
Versione : 1, 2, 3, 4
Ripetibile ? NO
Fornisce "dati associati" per la crittografia o decrittografia AES-GCM. Questo tag viene fornito per aggiornare e specifica i dati che non sono crittografati/decrittografati, ma vengono utilizzati per calcolare il tag GCM.
Il valore è un blob, una matrice di byte di lunghezza arbitraria.
Etichetta::ATTESTATION_APPLICATION_ID
Versione : 3, 4
Ripetibile ? NO
Utilizzato per identificare l'insieme di possibili applicazioni di cui una ha avviato 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.
Etichetta::ATTESTATION_ID_BRAND
Versione : 3, 4
Ripetibile ? NO
Fornisce il nome della marca del dispositivo, come restituito da Build.BRAND in Android. Questo campo è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un blob, una matrice di byte di lunghezza arbitraria.
Etichetta::ATTESTATION_ID_DEVICE
Versione : 3, 4
Ripetibile ? NO
Fornisce il nome del dispositivo del dispositivo, come restituito da Build.DEVICE in Android. Questo campo è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un blob, una matrice di byte di lunghezza arbitraria.
Etichetta::ATTESTATION_ID_IMEI
Versione : 3, 4
Ripetibile ? SÌ
Fornisce gli IMEI per tutte le radio sul dispositivo. Questo campo è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un blob, una matrice di byte di lunghezza arbitraria.
Etichetta::ATTESTATION_ID_MANUFACTURER
Versione : 3, 4
Ripetibile ? NO
Fornisce il nome del produttore del dispositivo, come restituito da Build.MANUFACTURER in Android. Questo campo è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo con ErrorCode::CANNOT_ATTEST_IDS .
Il valore è un blob, una matrice di byte di lunghezza arbitraria.
Etichetta::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 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 ha esito negativo 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 è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo 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 è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo 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 è impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.
Se il dispositivo non supporta l'attestazione dell'ID (o 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 ha esito negativo 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 cui la chiave è autorizzata all'uso, dopo l'autenticazione. Se Tag::USER_SECURE_ID è presente e questo tag non lo è, allora la chiave richiede l'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 finire , per dimostrare l'autenticazione dell'utente per un'operazione della 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 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::BLOCK_MODE
Versione : 1, 2, 3, 4
Ripetibile ? SÌ
Specifica le modalità di cifratura a blocchi con cui la chiave può essere utilizzata. 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 chiave AES specificare una modalità nell'argomento additionalParams di begin . Se la modalità specificata non è nelle modalità associate alla chiave, l'operazione ha esito negativo 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 la chiave può essere utilizzata. 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ì begin() , getKeyCharacteristics() o exportKey() restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedere upgradeKey() per i dettagli.
Il valore del tag è un numero intero nel formato YYYYMMDD, dove YYYY è l'anno a quattro cifre dell'ultimo aggiornamento, MM è il mese a due cifre e DD è 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 dall'hardware.
Tag::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 fallisce 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 fornisca Tag::NONCE per iniziare con ErrorCode::CALLER_NONCE_PROHIBITED .
Etichetta::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.
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 si trova nei digest associati alla chiave, l'operazione ha esito negativo con ErrorCode::INCOMPATIBLE_DIGEST .
Etichetta::EC_CURVE
Versione : 2, 3, 4
Ripetibile ? NO
In Keymaster 1, la curva utilizzata per le chiavi EC è stata indovinata 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 della chiave 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 , ricorrere alla logica Keymaster 1, scegliendo la curva NIST appropriata.
Se la richiesta contiene solo Tag::EC_CURVE , utilizza 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, utilizza la curva specificata da Tag::EC_CURVE e verifica che la dimensione della chiave specificata sia appropriata per quella curva. In caso contrario, restituire ErrorCode::INVALID_ARGUMENT .
Etichetta::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 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).
Tag::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 grande almeno quanto il valore di Tag::MIN_MAC_LENGTH associato alla chiave.
Etichetta::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 l'utilizzo delle chiavi.
Il valore è un numero intero a 32 bit che rappresenta gli usi per avvio.
Quando una chiave con questo tag viene utilizzata in un'operazione, un contatore associato alla chiave deve essere incrementato durante la chiamata di inizio . 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 conservi 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 le chiavi con questo tag quando la tabella è piena. Il tavolo deve ospitare 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 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 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 più di 128.
Etichetta::MIN_SECONDS_BETWEEN_OPS
Versione : 1, 2, 3, 4
Ripetibile ? NO
Specifica la quantità minima di tempo che trascorre tra le operazioni consentite utilizzando una chiave. Questo può essere utilizzato per limitare l'uso 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 un tasto con questo tag viene utilizzato in un'operazione, avvia un timer durante la chiamata di fine o interruzione . Qualsiasi chiamata all'inizio ricevuta prima che il timer indichi che l'intervallo specificato da Tag::MIN_SECONDS_BETWEEN_OPS è trascorso ha esito negativo con ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Ciò implica che un trustlet conservi 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 le 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).
Tag::NON NESSUNO
Versione : 1, 2, 3, 4
Ripetibile ? NO
Fornisce o restituisce un nonce o vettore di inizializzazione (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 casualmente da Keymaster e restituito dall'inizio.
Il valore è un blob, una matrice di byte di lunghezza arbitraria. Le lunghezze consentite dipendono dalla modalità: i nonce GCM hanno una lunghezza di 12 byte; CBC e CTR IV hanno una lunghezza di 16 byte.
Etichetta::ORIGINE
Versione : 1, 2, 3, 4
Ripetibile ? NO
Specifica dove è stata creata la chiave, se nota. Questo tag non può 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 presente nell'elenco dei dispositivi applicati 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 è legata all'hardware.
DERIVED indica che la chiave è stata derivata all'interno di Keymaster. Probabilmente esiste fuori dal dispositivo.
IMPORTED indica che la chiave è stata generata al di fuori di Keymaster e importata in Keymaster. Se nell'elenco dei dispositivi applicati dall'hardware, è associato permanentemente 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 è legata all'hardware.
UNKNOWN dovrebbe apparire solo nell'elenco dei sistemi applicati dall'hardware. Indica che la chiave è legata all'hardware, ma non è noto se la chiave sia stata originariamente generata in hardware sicuro o sia stata importata. Ciò si verifica solo quando l'hardware keymaster0 viene utilizzato per emulare i servizi keymaster1.
Etichetta::ORIGINATION_EXPIRE_DATETIME
Versione : 1, 2, 3, 4
Ripetibile ? NO
Specifica la data e l'ora in cui la chiave scade per scopi di firma e crittografia. Trascorso questo tempo, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::SIGN o KeyPurpose::ENCRYPT fornito per iniziare ha esito negativo 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 keymaster TA, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dal TA.
Il valore del tag è un numero intero nel formato YYYYMM, dove YYYY è 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 tale chiave fa sì che begin , getKeyCharacteristics o exportKey restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedere Collegamento della versione per ulteriori dettagli.
Etichetta::OS_VERSION
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 della versione principale, mm è il numero della versione secondaria e ss è il numero della 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 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 a finish 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. È necessario specificare una modalità di riempimento nella chiamata per iniziare . Se la modalità specificata non è autorizzata per la chiave, l'operazione ha esito negativo con ErrorCode::INCOMPATIBLE_BLOCK_MODE .
Etichetta::SCOPO
Versione : 1, 2, 3, 4
Ripetibile ? SÌ
Specifica l'insieme 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 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 begin 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 ha esito negativo con ErrorCode::INCOMPATIBLE_PURPOSE .
Tag::RESET_SINCE_ID_ROTATION
Versione : 3, 4
Ripetibile ? NO
Specifica se il dispositivo è stato ripristinato alle impostazioni di fabbrica dall'ultima rotazione dell'ID univoco. Utilizzato per l'attestazione della 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 sarà definitivamente eliminata 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 root of trust , 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 della 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 ed è necessario per tutte le chiavi RSA.
Il valore è un numero 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.
Etichetta::USAGE_EXPIRE_DATETIME
Versione : 1, 2, 3, 4
Ripetibile ? NO
Specifica la data e l'ora in cui la chiave scade per scopi di verifica e decrittografia. Trascorso questo tempo, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::VERIFY o KeyPurpose::DECRYPT fornito per iniziare fallisce 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 a Keymaster viene richiesto 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 i numeri interi ordinati dalla rete in numeri 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 un particolare stato di autenticazione utente protetto. 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 del criterio 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 per iniziare 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, ha esito negativo.
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. Altrimenti l'operazione fallisce 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 può essere utilizzata 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 far sì che begin() , getKeyCharacteristics() o exportKey() restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedere upgradeKey() per i dettagli.
Il valore del tag è un numero intero nel formato YYYYMMDD, dove YYYY è l'anno a quattro cifre dell'ultimo aggiornamento, MM è il mese a due cifre e DD è 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 IKeymasterDevice deve leggere il livello di patch del fornitore corrente 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 a dopo il successivo avvio.
Deve essere applicato dall'hardware.