Questa pagina fornisce dettagli per assistere gli utenti che implementano gli HAL Keymaster. Copre ogni tag nell'HAL, la versione Keymaster disponibile per quel 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
,
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, 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 3enum class Algorithm : uint32_t { RSA = 1, EC = 3, AES = 32, HMAC = 128, };
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 un 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. Alle ore non è previsto che un TEE sia in grado di fornire un accesso sicuro a un sensore sul corpo o che i sensori sul corpo sono molto sicuri, quindi dovrebbe essere una funzionalità interamente basata sul 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. Nella
in particolare le chiamate
exportKey e
getKeyCharacteristics
devono fornire lo stesso valore al parametro clientId
e richiama
iniziare a fornire
questo tag e gli stessi dati associati nell'ambito inParams
per iniziare. 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 segreti del mondo, ma non ha accesso ai contenuti del tag per decriptare senza forzare il contenuto del tag, cosa che le applicazioni 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
Quando fornito a
GeneraChiave
o importKey,
Questo tag specifica i dati necessari durante tutti gli utilizzi della chiave. Nella
in particolare le chiamate
exportKey e
getKeyCharacteristics
devono fornire lo stesso valore nel parametro clientId
e
le chiamate a iniziare devono
fornire questo tag e gli stessi dati associati nell'ambito
inParams
impostato. 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 è un avversario che può accedere a tutti i segreti del mondo sicuri, ma non ha accesso ai contenuti del tag e non può decriptare (senza forzare il contenuto 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 applicazioni 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
Indica il nome del brand del dispositivo, come restituito da Build.BRAND
su Android. Questo campo viene impostato solo quando si richiede l'attestazione del
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 si richiede l'attestazione del
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
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_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 i MEID per tutti i segnali radio sul dispositivo. Questo campo verrà impostato solo quando richiedi 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_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 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_PRODUCT
Versione: 3, 4
Ripetibile? No
Fornisce il nome del prodotto del dispositivo, come restituito da
Build.PRODUCT
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_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 ma questo tag no, la chiave richiede l'autenticazione per ogni sull'utilizzo (vedi inizio 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 autenticazione su begin, aggiorna o finire, per dimostrare l'autenticazione dell'utente per un'operazione chiave che 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'elemento pubblicitario chiave da utilizzare.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3enum class KeyBlobUsageRequirements : uint32_t { STANDALONE = 0, REQUIRES_FILE_SYSTEM = 1, };
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
getKeyFeatureistics.
Se il chiamante specifica Tag::BLOB_USAGE_REQUIREMENTS
con
valore KeyBlobUsageRequirements::STANDALONE
, il trustlet restituisce un blob chiave
utilizzabili senza il supporto del file system. Questo aspetto è fondamentale per i dispositivi
con dischi criptati, dove il file system potrebbe non essere disponibile finché
dopo l'utilizzo di 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 può essere utilizzata la chiave. Questo tag è pertinente solo per le chiavi AES.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3enum class BlockMode : uint32_t { ECB = 1, CBC = 2, CTR = 3, GCM = 32, };
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
. 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 Ultimo aggiornamento del dispositivo Android: 5 giugno 2018, il valore sarebbe 20180605. Se il giorno non è noto, può essere sostituito 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 basata sull'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 non richiedono la rimozione.
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 CBC, CTR e GCM
modalità di blocco. Se il tag non è presente, le implementazioni devono rifiutare qualsiasi
che fornisce Tag::NONCE a
inizio
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 3enum 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, };
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 è nei digest associati alla chiave,
operazione non riuscita con ErrorCode::INCOMPATIBLE_DIGEST
.
Tag::EC_CURVE
Versione: 2, 3, 4
Ripetibile? No
In Keymaster 1, la curva utilizzata per le chiavi EC è stata ipotizzata dalla chiave specificata
dimensioni. Per migliorare la flessibilità in futuro, Keymaster 2 ha introdotto un'esplicita
per specificare le curve. Le richieste di generazione di chiavi EC potrebbero avere
Tag::EC_CURVE
, Tag::KEY_SIZE
o entrambi.
I valori possibili sono definiti dalla seguente enumerazione:
Keymaster 3enum class EcCurve : uint32_t { P_224 = 0, P_256 = 1, P_384 = 2, P_521 = 3, };
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
,
utilizza la logica Keymaster 1, scegliendo la curva NIST appropriata.
Se la richiesta contiene solo Tag::EC_CURVE
, utilizza il metodo
specificata. Per Keymaster 3 e versioni successive, le curve sono definite
EcCurve
. Per Keymaster 2 e versioni precedenti, le curve sono definite
a 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
appropriato per quella curva. In caso contrario, restituisci
ErrorCode::INVALID_ARGUMENT
.
Tag::INCLUDE_UNIQUE_ID
Versione: 2, 3, 4
Ripetibile? No
Questo tag viene specificato durante la generazione della chiave per indicare che un'attestazione per la chiave generata deve contenere una dimensione e l'ambito ID univoco del dispositivo 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 la dimensione, in bit, della chiave, misurandola nel modo normale per
dell'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 in bit di un tag di autenticazione MAC o GCM.
Il valore è la lunghezza dell'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 il 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 hanno esito positivo
con ErrorCode::MAX_OPS_EXCEEDED
, fino al riavvio del dispositivo.
Ciò implica che un trustlet mantiene una tabella dei contatori dell'utilizzo per le chiavi con questo
del tag. Poiché la memoria Keymaster è spesso limitata, questa tabella può avere un valore
dimensione massima e Keymaster può non riuscire a eseguire operazioni che tentano di utilizzare 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 può trascorrere tra i valori consentiti operazioni usando una chiave. Può essere usato per limitare la frequenza di utilizzo delle chiavi in contesti laddove un uso illimitato può favorire attacchi di forza bruta.
Il valore è un numero intero a 32 bit che rappresenta i secondi tra i valori consentiti operazioni.
Avvia un timer quando viene utilizzata una chiave con questo tag in un'operazione
durante il finish o
interrompi la chiamata. Qualsiasi
chiamata a begin, ovvero
ricevute prima del timer indica che l'intervallo specificato
Errore di Tag::MIN_SECONDS_BETWEEN_OPS
trascorso 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 Keymaster è spesso limitata, questa tabella può avere un valore massimo fisso
dimensioni e Keymaster possono non riuscire 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 l'autenticazione per utilizzare questa chiave. Questo tag è che si escludono a vicenda con Tag::USER_SECURE_ID.
Questo tag è booleano, quindi i valori possibili sono veri (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 AES GCM, CBC, o la crittografia o la decrittografia del CTR. Questo tag è fornito a inizio durante le operazioni di crittografia e decriptazione. Viene fornito solo inizio se la chiave ha Tag::CALLER_NONCE. Se non viene specificato, un nonce o IV appropriato verrà generato casualmente Keymaster e restituito dall'inizio.
Il valore è un blob, un array di byte di lunghezza arbitraria. Lunghezze consentite dipendono dalla modalità: i nonce GCM hanno una lunghezza di 12 byte; Gli IV di CBC e CTR sono 16 byte.
Tag::ORIGIN
Versione: 1, 2, 3, 4
Ripetibile? No
Specifica dove è stata creata la chiave, se noto. Questo tag potrebbe non essere specificato durante la generazione o l'importazione delle chiavi e deve essere aggiunto alle caratteristiche chiave dal trustlet.
Keymaster 3I valori possibili sono definiti in
android::hardware::keymaster::v3_0::KeyOrigin
:
enum class KeyOrigin : uint32_t { GENERATED = 0, DERIVED = 1, IMPORTED = 2, UNKNOWN = 3, };
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 dipende non solo dal valore, ma anche dal fatto che si trova nell'elenco delle caratteristiche applicate dall'hardware o dal software.
GENERATED
indica che Keymaster ha generato la chiave.
Se invece è presente nell'elenco
La chiave è stata generata in hardware sicuro ed è associata definitivamente all'hardware. Se
nell'elenco delle applicazioni applicate dal software, la chiave è stata generata in SoftKeymaster ed è
non è associato all'hardware.
DERIVED
indica che la chiave è stata derivata all'interno di Keymaster.
È probabile che esista fuori dal dispositivo.
IMPORTED
indica che la chiave è stata generata all'esterno
di Keymaster e importati in
Keymaster. Se nell'elenco delle applicazioni forzate, è associato in modo permanente all'hardware,
anche se potrebbero esistere copie al di fuori dell'hardware protetto. Se nella
dell'applicazione forzata del software, la chiave è stata importata in SoftKeymaster e non è
associato all'hardware.
UNKNOWN
dovrebbe apparire solo nell'elenco delle applicazioni forzate dall'hardware.
Indica che la chiave è
associato all'hardware, ma non è noto se la chiave sia stata originariamente generata in
hardware protetto o che è stato importato. 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
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 nel formato AAAAMM, dove AAAA è il l'anno a quattro cifre dell'ultimo aggiornamento e MM indica il mese a due cifre dell'ultimo aggiornamento, 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 keymaster TA, ma viene aggiunto al l'elenco delle autorizzazioni hardware applicate dall'AT.
Il valore del tag è un numero intero nel formato MMmmss, dove MM è il maggiore numero di versione, mm è il numero di versione secondario e ss è la versione secondaria numero. 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 spaziatura interna 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 3enum 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, };
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 gli RSA
le chiavi di firma/verifica e specificare il PSS RSA PKCS#1v2
la spaziatura interna e la spaziatura interna deterministica RSA PKCS#1 v1.5, rispettivamente.
PaddingMode::NONE
può essere utilizzato con RSA o
Chiavi AES. Per le chiavi AES, se viene utilizzato PaddingMode::NONE
con la modalità di blocco ECB o CBC e i dati da criptare o decriptare
non è un multiplo della lunghezza del blocco AES, la chiamata alla fine
non riesce 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 3enum class KeyPurpose : uint32_t { ENCRYPT = 0, DECRYPT = 1, SIGN = 2, VERIFY = 3, DERIVE_KEY = 4, // since 3.0 WRAP_KEY = 5, // since 3.0 };
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
la funzione begin è denominata
per avviare un'operazione, ne viene specificato lo scopo.
Se lo scopo specificato nell'operazione non è autorizzato dal
, l'operazione non va a buon fine con ErrorCode::INCOMPATIBLE_PURPOSE
.
Tag::RESET_SINCE_ID_ROTATION
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 della chiave.
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 le chiavi senza questo tag potrebbero essere eliminate e poi ripristinate dal backup.
Questo tag è booleano, quindi i valori possibili sono veri (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 senza segno a 64 bit che soddisfa i requisiti di un
esponente pubblico RSA. Questo valore deve essere un numero primo. I trustlet supportano
valore 2^16 1 e può 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
scopi di decrittografia. Dopodiché, qualsiasi tentativo di utilizzare una chiave con
scopo chiave: VERIFICA o
scopo principale: DECRYPT 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::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 i numeri interi ordinati in 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 contenente i valori dell'enumerazione:
Keymaster 3enum class HardwareAuthenticatorType : uint32_t { NONE = 0u, // 0 PASSWORD = 1 << 0, FINGERPRINT = 1 << 1, ANY = UINT32_MAX, };
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? No
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 lo stato del criterio di autenticazione che deve essere presente in un token di autenticazione (fornito inizia con 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 va a buon fine
ErrorCode::KEY_USER_NOT_AUTHENTICATED
.
Tag::VENDOR_PATCHLEVEL
Versione: 4
Questo tag specifica il livello patch di sicurezza dell'immagine del fornitore con cui la chiave
possono essere utilizzati. Questo tag non viene mai inviato al keymaster TA, ma viene aggiunto al
l'elenco delle autorizzazioni hardware
applicate dall'AT. 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 Ultimo aggiornamento del dispositivo Android: 5 giugno 2018, il valore sarebbe 20180605.
L'HAL IKeymasterDevice deve leggere dal sistema l'attuale livello di patch del fornitore
proprietà ro.vendor.build.security_patch
e la invii alla
in un 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.