Tag di autorizzazione Keymaster

Questa pagina fornisce dettagli per assistere gli utenti che implementano gli HAL Keymaster. Copre ogni tag nell'HAL, la versione di Keymaster in cui è disponibile il tag e se il tag è ripetibile. Ad eccezione di quanto indicato nelle descrizioni dei tag, tutti i tag riportati di seguito vengono utilizzati durante la generazione della chiave per specificare caratteristiche.

Per Keymaster 4, i tag sono definiti in platform/hardware/interfaces/keymaster/keymaster-version/types.hal, ad esempio 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, vedi Pagina Keymaster Functions.

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 un eventuale tentativo di utilizzare la chiave non va a buon fine 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;

Tag::ALL_APPLICATIONS

Versione: 1, 2, 3, 4

Ripetibile? No

Riservato per uso futuro.

Tag::ALLOW_WHILE_ON_BODY

Versione: 2, 3, 4

Ripetibile? No

Questo tag è valido solo per i dispositivi Android Wear dotati di sensori sul corpo. A questo punto, non è previsto che qualsiasi TEE possa fornire accesso sicuro a un sensore indossato o che i sensori indossati siano molto sicuri, pertanto si prevede che si tratti di una funzionalità applicata esclusivamente tramite software.

Tag::ALL_USERS

Versione: 3, 4

Ripetibile? No

Riservato per un uso futuro.

Tag::APPLICATION_DATA

Versione: 1, 2, 3, 4

Ripetibile? No

Quando fornito a GeneraChiave 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 nell'ambito dell'insieme inParams. Se non vengono forniti i dati corretti, la funzione restituisce ErrorCode::INVALID_KEY_BLOB.

I contenuti di questo tag sono associati alla chiave crittograficamente, il che significa che non deve essere possibile per un avversario che ha accesso a tutti proteggere i segreti del mondo, ma non ha accesso ai contenuti del tag per decriptare senza forzare i contenuti del tag, cosa che le app possono impedire che specifichi contenuti con un'entropia sufficientemente elevata.

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

Tag::APPLICATION_ID

Versione: 1, 2, 3, 4

Ripetibile? No

Se 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 nell'ambito dell'insieme inParams. Se non vengono forniti i dati corretti, la funzione restituisce ErrorCode::INVALID_KEY_BLOB.

I contenuti di questo tag sono legati alla chiave in modo criptato, il che significa che un avversario che può accedere a tutti i segreti di sicurezza mondiali, ma non ha accesso ai contenuti del tag, non può decriptare la chiave (senza utilizzare la forza bruta sui contenuti del tag).

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

Tag::ASSOCIATED_DATA

Versione: 1, 2, 3, 4

Ripetibile? No

Fornisce "dati associati" per la crittografia o la decrittografia AES-GCM. Questo tag è forniti per aggiornare specifica i dati che non sono criptati/decriptati, ma che sono utilizzati in informatica il tag GCM.

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

Tag::ATTESTATION_APPLICATION_ID

Versione: 3, 4

Ripetibile? No

Utilizzato per identificare l'insieme di possibili app di cui ha avviato un'attestazione della chiave.

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

Tag::ATTESTATION_CHALLENGE

Versione: 3, 4

Ripetibile? No

Utilizzato per fornire verifica nell'attestazione.

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

Tag::ATTESTATION_ID_BRAND

Versione: 3, 4

Ripetibile? No

Fornisce il nome del brand del dispositivo, restituito da Build.BRAND in Android. Questo campo viene impostato solo quando viene richiesta l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o Hai già chiamato destroyAttestationIds() e il dispositivo può non attesti più i suoi ID), qualsiasi richiesta di attestazione della chiave che includa questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_DEVICE

Versione: 3, 4

Ripetibile? No

Fornisce il nome del dispositivo, come restituito da Build.DEVICE su Android. Questo campo viene impostato solo quando viene richiesta l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o Hai già chiamato destroyAttestationIds() e il dispositivo può non attesti più i suoi ID), qualsiasi richiesta di attestazione della chiave che includa questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_IMEI

Versione: 3, 4

Ripetibile? Sì

Fornisce gli IMEI per tutti i segnali radio sul dispositivo. Questo campo è impostato solo quando richiedi l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o se destroyAttestationIds() è stato chiamato in precedenza e il dispositivo non può più autenticare i propri ID), qualsiasi richiesta di attestazione della chiave che include questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_MANUFACTURER

Versione: 3, 4

Ripetibile? No

Fornisce il nome del produttore del dispositivo, così come viene restituito Build.MANUFACTURER su Android. Questo campo viene impostato solo se richiedere l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o Hai già chiamato destroyAttestationIds() e il dispositivo può non attesti più i suoi ID), qualsiasi richiesta di attestazione della chiave che includa questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_MEID

Versione: 3, 4

Ripetibile? Sì

Fornisce gli MEID di tutte le radio sul dispositivo. Questo campo è impostato solo quando richiedi l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o se destroyAttestationIds() è stato chiamato in precedenza e il dispositivo non può più autenticare i propri ID), qualsiasi richiesta di attestazione della chiave che include questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_MODEL

Versione: 3, 4

Ripetibile? No

Fornisce il nome del modello del dispositivo, come restituito da Build.MODEL su Android. Questo campo viene impostato solo quando viene richiesta l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o Hai già chiamato destroyAttestationIds() e il dispositivo può non attesti più i suoi ID), qualsiasi richiesta di attestazione della chiave che includa questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::ATTESTATION_ID_PRODUCT

Versione: 3, 4

Ripetibile? No

Fornisce il nome del prodotto del dispositivo, 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 Hai già chiamato destroyAttestationIds() e il dispositivo può non attesti più i suoi ID), qualsiasi richiesta di attestazione della chiave che includa questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

Il valore è un blob, un array 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 se richiedere l'attestazione degli identificatori del dispositivo.

Se il dispositivo non supporta l'attestazione dell'ID (o Hai già chiamato destroyAttestationIds() e il dispositivo può non attesti più i suoi ID), qualsiasi richiesta di attestazione della chiave che includa questo tag non va a buon fine con ErrorCode::CANNOT_ATTEST_IDS.

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

Tag::AUTH_TIMEOUT

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica il tempo in secondi in cui la chiave può essere utilizzata, dopo il quale autenticazione. Se Tag::USER_SECURE_ID è presente e questo tag non è presente, la chiave deve essere autenticata per ogni utilizzo (vedi begin 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 che consente di in uso.

Tag::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 con la chiave che lo richiede (la chiave ha Tag::USER_SECURE_ID).

Il valore è un blob che contiene una struttura hw_auth_token_t.

Tag::BLOB_USAGE_REQUIREMENTS

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica le condizioni 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 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 la chiave caratteristiche da generateKey e getKeyCharacteristics. Se l'utente chiamante specifica Tag::BLOB_USAGE_REQUIREMENTS con valore KeyBlobUsageRequirements::STANDALONE, il trustlet restituisce un blob della chiave che può essere utilizzato senza il supporto del file system. Questo è fondamentale per i dispositivi con dischi criptati, in cui il file system potrebbe non essere disponibile finché non viene utilizzata una chiave Keymaster per decriptare il disco.

Tag::BLOCK_MODE

Versione: 1, 2, 3, 4

Ripetibile? Sì

Specifica le modalità di crittografia a blocchi con cui è possibile utilizzare la chiave. Questo tag è pertinente solo per le chiavi AES.

I valori possibili sono definiti dalla seguente enumerazione:

Keymaster 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 e precedenti 
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Questo tag è ripetibile e per le operazioni con i tasti AES specifica una modalità in l'argomento additionalParams di begin. Se la modalità specificata non è nelle modalità associate alla chiave, il valore operazione non riuscita con ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::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 keymaster TA, ma viene aggiunto all'elenco delle autorizzazioni applicate dall'hardware dall'AT. Qualsiasi tentativo di utilizza una chiave con un valore Tag::BOOT_PATCHLEVEL diverso da a livello di patch di sistema attualmente in esecuzione causa begin(), getKeyCharacteristics() o exportKey() per il reso ErrorCode::KEY_REQUIRES_UPGRADE. Per maggiori dettagli, visita la pagina upgradeKey().

Il valore del tag è un numero intero nel formato AAAAMMGG, dove AAAA è il valore anno a quattro cifre dell'ultimo aggiornamento, MM indica il mese di due cifre e GG indica il mese il giorno a due cifre dell'ultimo aggiornamento. Ad esempio, per una chiave generata su un dispositivo Android aggiornata l'ultima volta il 5 giugno 2018, il valore sarà 20180605. Se il giorno non è noto, è possibile sostituirlo con 00.

Durante ogni avvio, il bootloader deve fornire il livello di patch dell'immagine di avvio nell'ambiente sicuro (il meccanismo è definito dall'implementazione).

Deve essere applicata 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 veri (se il tag è presente) e false (se il tag non è presente).

Qualsiasi tentativo di utilizzare una chiave con Tag::BOOTLOADER_ONLY dall' Il sistema Android non funziona con ErrorCode::INVALID_KEY_BLOB.

Tag::CALLER_NONCE

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica che il chiamante può fornire un nonce per le operazioni che richiedono un nonce.

Questo tag è booleano, quindi i valori possibili sono veri (se il tag è presente) e false (se il tag non è presente).

Questo tag viene utilizzato solo per le chiavi AES ed è pertinente solo per le modalità di blocco CBC, CTR e GCM. Se il tag non è presente, le implementazioni devono rifiutare qualsiasi operazione che fornisca Tag::NONCE per iniziare con ErrorCode::CALLER_NONCE_PROHIBITED.

Tag::CREATION_DATETIME

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica la data e l'ora di creazione della chiave, in millisecondi a partire dal giorno 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 le operazioni di firma e verifica. Questo tag è pertinente per RSA, ECDSA e Chiavi 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, specifica un digest nell'argomento additionalParams di begin. Se il digest specificato non è presente nei digest associati alla chiave, l'operazione non riesce con ErrorCode::INCOMPATIBLE_DIGEST.

Tag::EC_CURVE

Versione: 2, 3, 4

Ripetibile? No

In Keymaster 1, la curva utilizzata per le chiavi EC veniva dedotta dalla dimensione della chiave specificata. Per migliorare la flessibilità in futuro, Keymaster 2 ha introdotto un'esplicita per specificare le curve. Le richieste di generazione di chiavi EC possono avereTag::EC_CURVE, Tag::KEY_SIZE o entrambe.

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, riassegna la logica di 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 contiene entrambe, 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.

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 basato sull'app e limitato nel tempo, come specificato da Tag::UNIQUE_ID.

Questo tag è booleano, quindi i valori possibili sono veri (se il tag è presente) e false (se il tag non è presente).

Tag::KEY_SIZE

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica le dimensioni, in bit, della chiave, misurate 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.

Tag::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 del MAC in bit. È un multiplo di 8 e grande almeno quanto il valore di Tag::MIN_MAC_LENGTH associati alla chiave.

Tag::MAX_USES_PER_BOOT

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica il numero massimo di volte in cui una chiave può essere utilizzata tra sistema si riavvia. Questo è un altro meccanismo per limitare la frequenza di utilizzo delle chiavi.

Il valore è un numero intero a 32 bit che rappresenta gli utilizzi per avvio.

Quando in un'operazione viene utilizzata una chiave con questo tag, viene utilizzato un contatore associato alla chiave. deve essere incrementato durante begin della chiamata. Dopo la chiave contatore ha superato questo valore, tutti i tentativi successivi di utilizzare la chiave non sono andati a buon fine con ErrorCode::MAX_OPS_EXCEEDED, fino al riavvio del dispositivo. 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ò non riuscire a eseguire le operazioni che tentano di utilizzare le chiavi con questo tag quando la tabella è piena. La tabella deve contenere almeno 16 chiavi. Se un'operazione non va a buon fine perché la tabella è piena, Keymaster restituisce ErrorCode::TOO_MANY_OPERATIONS.

Tag::MIN_MAC_LENGTH

Versione: 1, 2, 3, 4

Ripetibile? No

Questo tag specifica la lunghezza minima di MAC che è possibile richiedere o verificata con questa chiave per le chiavi HMAC e AES che supportano la modalità GCM.

Questo valore è la lunghezza minima dell'MAC, in bit. È un multiplo di 8. Per Chiavi HMAC, il valore è almeno 64. Per le chiavi GCM il valore è almeno 96 e non più di 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica il tempo minimo che intercorre tra le operazioni consentite utilizzando una chiave. Può essere usato per limitare la frequenza di utilizzo delle chiavi in contesti laddove un uso illimitato potrebbe consentire attacchi di forza bruta.

Il valore è un numero intero a 32 bit che rappresenta i secondi tra le operazioni consentite.

Quando in un'operazione viene utilizzata una chiave con questo tag, avvia un timer durante il finish o interrompi la chiamata. Qualsiasi chiamata a begin ricevuta prima che il timer indichi che è trascorso l'intervallo specificato da Tag::MIN_SECONDS_BETWEEN_OPS non va a buon fine con ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Questo il fatto che un trustlet conservi una tabella dei contatori dell'utilizzo per le chiavi con questo tag. Poiché la memoria di Keymaster è spesso limitata, questa tabella può avere una dimensione massima fissa e Keymaster può non riuscire a eseguire le operazioni che tentano di utilizzare le chiavi con questo tag quando la tabella è piena. La tabella deve ospitarne almeno 32 in uso e riutilizzare in modo aggressivo gli slot delle tabelle quando scadono gli intervalli di utilizzo minimo della chiave. Se un'operazione non va a buon fine perché la tabella è piena, Keymaster restituisce ErrorCode::TOO_MANY_OPERATIONS.

Tag::NO_AUTH_REQUIRED

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica che non è richiesta alcuna autenticazione per utilizzare questa chiave. Questo tag è mutuamente esclusivo di 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::NONCE

Versione: 1, 2, 3, 4

Ripetibile? No

Fornisce o restituisce un nonce o un vettore di inizializzazione (IV) per la crittografia o la decrittografia AES GCM, CBC o CTR. Questo tag viene fornito per iniziare durante le operazioni di crittografia e decrittografia. Viene fornito solo per iniziare se la chiave ha Tag::CALLER_NONCE. Se non viene specificato, un nonce o IV appropriato viene generato casualmente 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; le IV CBC e CTR hanno una lunghezza di 16 byte.

Tag::ORIGIN

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.

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 precedenti

I valori possibili 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 non dipende solo dal valore, ma anche dal fatto che si trova nell'elenco delle caratteristiche applicate dall'hardware o dal software.

GENERATED indica che la chiave è stata generata da Keymaster. Se è presente nell'elenco con l'applicazione forzata dell'hardware, la chiave è stata generata in hardware sicuro ed è permanentemente associata all'hardware. Se si trova nell'elenco applicato tramite 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 al di fuori di Keymaster e importata in Keymaster. Se è presente nell'elenco con applicazione forzata tramite hardware, è vincolato in modo permanente all'hardware, anche se potrebbero esistere copie al di fuori dell'hardware sicuro. Se nella dell'applicazione forzata del software, la chiave è stata importata in SoftKeymaster e associato all'hardware.

UNKNOWN dovrebbe apparire solo nell'elenco delle applicazioni forzate dall'hardware. Indica che la chiave è associata all'hardware, ma non è noto se è stata generata originariamente in hardware sicuro o è stata importata. Questo si verifica solo quando l'hardware keymaster0 utilizzato per emulare i servizi keymaster1.

Tag::ORIGINATION_EXPIRE_DATETIME

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica la data e l'ora di scadenza della chiave per la firma e la crittografia. Dopodiché, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::SIGN oppure scopo chiave::ENCRYPT fornito a begin non riesce con ErrorCode::KEY_EXPIRED.

Il valore è un numero intero a 64 bit che rappresenta i millisecondi, 1° gennaio 1970.

Tag::OS_PATCHLEVEL

Versione: 2, 3, 4

Ripetibile? No

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

Il valore del tag è un numero intero del tipo AAAAMM, dove AAAA è l'anno in quattro cifre dell'ultimo aggiornamento e MM è il mese in due cifre dell'ultimo aggiornamento. Ad esempio, per l'ultimo aggiornamento di una chiave generata su un dispositivo Android, dicembre 2015, il valore sarà 201512.

Le chiavi con un livello di patch diverso da quello attuale non sono utilizzabili. Un tentativo di utilizzare queste cause chiave begin, getKeyCharacteristics, o exportKey per restituire ErrorCode::KEY_REQUIRES_UPGRADE. Consulta Associazione delle versioni per scoprire di più i dettagli.

Tag::OS_VERSION

Versione: 2, 3, 4

Ripetibile? No

Questo tag non viene mai inviato al TA Keymaster, ma viene aggiunto dall'amministratore dell'elenco di autorizzazione applicato dall'hardware.

Il valore del tag è un numero intero del tipo 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 sarà 040003.

Tag::PADDING

Versione: 1, 2, 3, 4

Ripetibile? Sì

Specifica le modalità di riempimento che possono essere utilizzate con la chiave. Questo tag è pertinente 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 Spazio utilizzato: PaddingMode::RSA_PKCS1_1_5_ENCRYPT solo per le chiavi di crittografia/decrittografia RSA e specifica OAEP PKCS#1v2 RSA per la spaziatura interna e per la spaziatura interna randomizzata RSA PKCS#1 v1.5. PaddingMode::RSA_PSS e PaddingMode::RSA_PKCS1_1_5_SIGN vengono utilizzati solo per le chiavi di firma/verifica RSA e specificano rispettivamente il padding PSS RSA PKCS#1 v2 e il padding deterministico RSA PKCS#1 v1.5.

PaddingMode::NONE può essere utilizzato con chiavi RSA o AES. Per le chiavi AES, se viene utilizzato PaddingMode::NONE con la modalità blocco ECB o CBC e la lunghezza dei dati da criptare o decriptare non è un multiplo della dimensione del blocco AES, la chiamata a finish non va a buon fine 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 spaziatura interna nella chiamata a inizia. Se la modalità specificata non è autorizzata per la chiave, l'operazione non va a buon fine con ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::SCOPO

Versione: 1, 2, 3, 4

Ripetibile? Sì

Specifica l'insieme di scopi per cui può essere utilizzata la chiave.

I valori possibili sono definiti dalla seguente enumerazione:

Keymaster 3 
enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};
Keymaster 2 e precedenti 
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Questo tag è ripetibile; le chiavi possono essere generate con più valori, anche se un'operazione ha un unico scopo. Quando viene chiamata la funzione begin per avviare un'operazione, viene specificato lo scopo dell'operazione. Se lo scopo specificato per l'operazione non è autorizzato dalla chiave, l'operazione non va a buon fine con ErrorCode::INCOMPATIBLE_PURPOSE.

Tag::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 delle chiavi.

Questo tag è booleano, quindi i valori possibili sono veri (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, ovvero quando viene eliminata tramite deleteKey oppure deleteAllKeys, se la chiave è eliminata definitivamente e inutilizzabile. È possibile che le chiavi senza questo tag vengano eliminate e poi ripristinate dal backup.

Questo tag è booleano, quindi i valori possibili sono true (se il tag è presente) e false (se il tag non è presente).

Tag::ROOT_OF_TRUST

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica la root di attendibilità, la chiave utilizzata dall'avvio verificato per convalidare il sistema operativo avviato (se presente). Questo tag non viene mai fornito da Keymaster nelle caratteristiche chiave.

Tag::RSA_PUBLIC_EXPONENT

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica il valore dell'esponente pubblico per una coppia di chiavi RSA. Questo tag è pertinente solo alle chiavi RSA e necessario per tutte le chiavi RSA.

Il valore è un numero intero non firmato a 64 bit che soddisfa i requisiti di un esponente pubblico RSA. Questo valore deve essere un numero primo. I trustlet supportano il valore 2^16+1 e possono supportare altri valori ragionevoli, in particolare il valore 3. Se non viene specificato alcun esponente o se l'esponente specificato non è supportato, la generazione della chiave non riesce e ErrorCode::INVALID_ARGUMENT.

Tag::UNIQUE_ID

Versione: 3, 4

Ripetibile? No

Utilizzato per fornire un ID univoco nell'attestazione.

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

Tag::USAGE_EXPIRE_DATETIME

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica la data e l'ora di scadenza della chiave per la verifica e la decrittografia. Dopo questo periodo di tempo, qualsiasi tentativo di utilizzare una chiave con KeyPurpose::VERIFY o KeyPurpose::DECRYPT fornito a begin non va a buon fine con ErrorCode::KEY_EXPIRED.

Il valore è un numero intero a 64 bit che rappresenta i millisecondi dal 1° gennaio 1970.

Tag::USER_AUTH_TYPE

Versione: 1, 2, 3, 4

Ripetibile? No

Specifica i tipi di autenticazione degli utenti che possono essere utilizzati per autorizzare questa chiave. Quando a Keymaster viene richiesto di eseguire un'operazione con una chiave con questo riceve un token di autenticazione e il token Il campo authenticator_type deve corrispondere al valore nel tag. Ad esempio, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0, dove ntoh è una funzione che converte gli interi ordinati in rete in interi ordinati in base all'host e auth_type_tag_value è il valore di questo tag.

Il valore è una maschera di bit di numeri interi 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;

Tag::USER_SECURE_ID

Versione: 1, 2, 3, 4

Ripetibile? Sì

Specifica che una chiave può essere utilizzata solo per un determinato utente sicuro lo stato dell'autenticazione. 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 il Tag::AUTH_TOKEN) per autorizzare l'utilizzo della chiave. Qualsiasi chiama begin con una chiave con questo tag che non fornisce di autenticazione o fornisce un token il token di autenticazione senza un valore dello stato del criterio corrispondente non va a buon fine.

Questo tag è ripetibile. Se uno dei valori forniti corrisponde a un criterio nel token di autenticazione, la chiave è autorizzata all'uso. In caso contrario, l'operazione non andrà a buon fine con ErrorCode::KEY_USER_NOT_AUTHENTICATED.

Tag::VENDOR_PATCHLEVEL

Versione: 4

Questo tag specifica il livello della patch di sicurezza dell'immagine del fornitore con cui la chiave può essere utilizzata. Questo tag non viene mai inviato al TA Keymaster, ma viene aggiunto dall'amministratore dell'elenco di autorizzazione applicato dall'hardware. Qualsiasi tentativo di utilizzare una chiave con un Il valore di Tag::VENDOR_PATCHLEVEL è diverso da quello attualmente in esecuzione livello patch di sistema deve causare begin(), getKeyCharacteristics() o exportKey() per il reso ErrorCode::KEY_REQUIRES_UPGRADE. Vedi upgradeKey() per maggiori dettagli.

Il valore del tag è un numero intero nel formato AAAAMMGG, dove AAAA è il valore anno a quattro cifre dell'ultimo aggiornamento, MM indica il mese di due cifre e GG indica il mese il giorno a due cifre dell'ultimo aggiornamento. Ad esempio, per una chiave generata su un dispositivo Android aggiornata l'ultima volta il 5 giugno 2018, il valore sarà 20180605.

L'HAL IKeymasterDevice deve leggere il patchlevel del fornitore corrente dalla proprietà ro.vendor.build.security_patch del sistema e inviarlo all'ambiente sicuro al primo caricamento dell'HAL (il meccanismo è definito dall'implementazione). L'ambiente sicuro non deve accettare un altro livello di patch fino a dopo l'avvio successivo.

Deve essere basata sull'hardware.