Tag di autorizzazione del keymaster

Questa pagina fornisce dettagli per assistere gli implementatori degli HAL Keymaster. 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 .

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.

Etichetta::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::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 ai dispositivi Android Wear con sensori sul corpo. A questo punto, non si prevede che alcun TEE sarà in grado di fornire un accesso sicuro a un sensore indossato sul corpo o che i sensori indossati sul corpo siano molto sicuri, quindi si prevede che questa sia una funzionalità puramente software.

Etichetta::TUTTI_UTENTI

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 utilizzi 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 è legato crittograficamente alla chiave, 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 brutalmente il tag contenuto, che le applicazioni possono impedire specificando un contenuto con entropia sufficientemente elevata.

Il valore è un blob, un array di byte di lunghezza arbitraria.

Etichetta::APPLICATION_ID

Versione : 1, 2, 3, 4

Ripetibile ? NO

Quando fornito a generateKey o importKey , questo tag specifica i dati necessari durante tutti gli utilizzi 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 è legato crittograficamente alla chiave, 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 brutalmente il contenuto del tag ).

Il valore è un blob, un array 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 nel calcolo del tag GCM.

Il valore è un blob, un array di byte di lunghezza arbitraria.

Etichetta::ATTESTATION_APPLICATION_ID

Versione : 3, 4

Ripetibile ? NO

Utilizzato per identificare l'insieme delle possibili applicazioni di cui si è avviata una chiave di attestazione.

Il valore è un blob, un array di byte di lunghezza arbitraria.

Etichetta::ATTESTATION_CHALLENGE

Versione : 3, 4

Ripetibile ? NO

Utilizzato per fornire una sfida nell'attestazione.

Il valore è un blob, un array di byte di lunghezza arbitraria.

Etichetta::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 è stato chiamato in precedenza 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, un array di byte di lunghezza arbitraria.

Etichetta::ATTESTATION_ID_DEVICE

Versione : 3, 4

Ripetibile ? NO

Fornisce il nome 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 chiamato in precedenza 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, un array 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 viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o è stato chiamato in precedenza 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, un array 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 viene impostato solo quando si richiede l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o è stato chiamato in precedenza 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, un array 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 è stato chiamato in precedenza 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, un array 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 è stato chiamato in precedenza 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, un array 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 è stato chiamato in precedenza 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, un array di byte di lunghezza arbitraria.

Etichetta::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 chiamato in precedenza 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, un array 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 per l'uso, dopo l'autenticazione. Se Tag::USER_SECURE_ID è presente e questo tag no, 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 l'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 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 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 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 crittografia a blocchi con cui può essere utilizzata 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 chiave AES specificare una modalità 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 della patch di sicurezza dell'immagine di avvio (kernel) con cui può essere utilizzata la chiave. Questo tag non viene mai inviato al TA keymaster, 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 del sistema attualmente in esecuzione fa sì begin() , getKeyCharacteristics() o exportKey() restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedi upgradeKey() per i dettagli.

Il valore del tag è un numero intero nel formato 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.

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 fallisce 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 non 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, a partire 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 additionalParams di Begin . Se il digest specificato non è presente nei digest associati alla chiave, l'operazione fallisce 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à 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 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 , 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 versioni precedenti, le curve sono definite in keymaster_ec_curve_t .

Se la richiesta li 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, restituisce 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 applicativo 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::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 ed è 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 la velocità 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 di inizio . Dopo che il contatore della chiave ha superato questo valore, tutti i tentativi successivi di utilizzare la chiave falliscono con ErrorCode::MAX_OPS_EXCEEDED , finché il dispositivo non viene riavviato. Ciò implica che un trustlet mantenga una tabella di 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 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 superiore a 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 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, avvia un timer durante la chiamata di fine o interruzione . Qualsiasi chiamata all'inizio ricevuta prima del timer indica che l'intervallo specificato da Tag::MIN_SECONDS_BETWEEN_OPS è trascorso fallisce con ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Ciò implica che un trustlet mantenga una tabella di 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 un 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 per iniziare solo se la chiave ha Tag::CALLER_NONCE . Se non fornito, un nonce o un IV appropriato verrà generato casualmente da Keymaster e restituito dall'inizio.

Il valore è un blob, un array di byte di lunghezza arbitraria. Le lunghezze consentite dipendono dalla modalità: i nonce GCM hanno una lunghezza di 12 byte; I 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 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 nell'elenco applicato dall'hardware, la chiave è stata generata in un hardware sicuro ed è permanentemente associata 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. Probabilmente esiste fuori dal dispositivo.

IMPORTED indica che la chiave è stata generata all'esterno di Keymaster e importata in Keymaster. Se presente nell'elenco applicato dall'hardware, è 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 applicato dall'hardware. Indica che la chiave è legata all'hardware, ma non è noto se la chiave sia stata originariamente generata in un hardware protetto o importata. Ciò si verifica solo quando viene utilizzato l'hardware keymaster0 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 fornita per iniziare fallisce 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 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.

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 . Per ulteriori dettagli, vedere Associazione della versione .

Etichetta::VERSIONE_OS

Versione : 2, 3, 4

Ripetibile ? NO

Questo tag non viene mai inviato al TA keymaster, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dal TA.

Il valore del tag è un numero intero nel formato 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 nella versione Android 4.0.3, il valore sarebbe 040003.

Etichetta::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 PSS RSA PKCS#1v2 e il riempimento deterministico RSA PKCS#1 v1.5.

PaddingMode::NONE può essere utilizzato con le 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 multipli della dimensione del blocco AES in lunghezza, la chiamata a Finish ha esito negativo con ErrorCode::INVALID_INPUT_LENGTH .

PaddingMode::PKCS7 può essere utilizzato solo con chiavi AES e solo con le modalità ECB e CBC.

Questo tag è ripetibile. È necessario specificare una modalità di riempimento nella chiamata a Begin . 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 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 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 fallisce con ErrorCode::INCOMPATIBLE_PURPOSE .

Etichetta::RESET_SINCE_ID_ROTAZIONE

Versione : 3, 4

Ripetibile ? NO

Specifica se sono stati ripristinati i dati di fabbrica del dispositivo 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_RESISTENTE

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 , la chiave sarà sicuramente eliminata in modo permanente e inutilizzabile. È possibile che le chiavi senza questo tag vengano 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 ed è 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 .

Etichetta::ID_UNIQUE

Versione : 3, 4

Ripetibile ? NO

Utilizzato per fornire un ID univoco nell'attestazione.

Il valore è un blob, un array 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 a scopo di verifica e decrittografia. Trascorso questo tempo, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::VERIFY o KeyPurpose::DECRYPT fornita 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 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 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 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 un particolare stato di autenticazione utente sicuro. 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 inizia con una chiave con questo tag che non fornisce un token di autenticazione o fornisce un token di autenticazione senza un valore dello stato della policy 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 TA keymaster, 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 del sistema attualmente in esecuzione deve far sì che begin() , getKeyCharacteristics() o exportKey() restituiscano ErrorCode::KEY_REQUIRES_UPGRADE . Vedi upgradeKey() per i dettagli.

Il valore del tag è un numero intero nel formato 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 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 sicuro non deve accettare un altro livello di patch fino a dopo il successivo avvio.

Deve essere applicato tramite hardware.