Riferimento alla struttura keymaster2_device

Interrompe un'operazione di crittografia iniziata con begin() , liberando tutte le risorse interne e invalidando operation_handle .

Definizione nella riga 415 del file keymaster2.h .

Aggiunge entropia al generatore di numeri casuali utilizzato da Keymaster. L'entropia aggiunta tramite questo metodo non è garantita come unica fonte di entropia utilizzata e la funzione di miscelazione deve essere sicura, nel senso che se l'RNG viene inizializzato (da qualsiasi fonte) con dati che l'attaccante non può prevedere (o controllare), l'output dell'RNG è indistinguibile da quello casuale. Pertanto, se l'entropia di qualsiasi sorgente è buona, l'output sarà buono.

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	di dati	Dati casuali da includere.
[in]	data_length	Lunghezza di data .

Definizione nella riga 74 del file keymaster2.h .

Genera una catena di certificati X.509 firmata che attesta la presenza di key_to_attest in Keymaster (DA FARE(swillden): descrivi i contenuti del certificato in modo più dettagliato). Il certificato conterrà un'estensione con OID 1.3.6.1.4.1.11129.2.1.17 e il valore definito in <TODO:swillden – insert link here> che contiene la descrizione della chiave.

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	key_to_attest	La chiave keymaster per la quale verrà generato il certificato di attestazione.
[in]	attest_params	Parametri che definiscono la modalità di esecuzione dell'attestazione. Al momento l'unico parametro è KM_TAG_ALGORITHM, che deve essere KM_ALGORITHM_EC o KM_ALGORITHM_RSA. In questo modo viene selezionata la chiave di attestazione di cui è stato eseguito il provisioning da utilizzare per firmare il certificato.
[out]	cert_chain	Un array di certificati X.509 con codifica DER. Il primo sarà il certificato per key_to_attest . Le voci rimanenti verranno ricollegate alla radice. Il chiamante acquisisce la proprietà e deve eseguire lo scollegamento con keymaster_free_cert_chain.

Definizione alla riga 239 del file keymaster2.h .

Avvia un'operazione di crittografia utilizzando la chiave specificata. Se tutto va bene, begin() restituirà KM_ERROR_OK e creerà un handle dell'operazione che deve essere passato alle chiamate successive a update() , finish() oppure abort() .

È fondamentale che ogni chiamata a begin() sia accoppiata a una chiamata successiva a finish() o abort() , per consentire all'implementazione di Keymaster di ripulire qualsiasi stato di operazione interno. Se non lo fai, potresti perdere spazio di stato interno o altre risorse interne e alla fine potresti causare begin() a restituire KM_ERROR_TOO_MANY_OPERATIONS quando non è più disponibile spazio per le operazioni. Qualsiasi risultato diverso da KM_ERROR_OK di begin() , update() o finish() comporta l'interruzione implicita dell'operazione, nel qual caso abort() non deve essere chiamato (e restituirà KM_ERROR_INVALID_OPERATION_HANDLE se chiamato).

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	scopo	Lo scopo dell'operazione, uno dei valori KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN o KM_PURPOSE_VERIFY. Tieni presente che per le modalità AEAD, la crittografia e la decrittografia implicano rispettivamente la firma e la verifica, ma devono essere specificate come KM_PURPOSE_ENCRYPT e KM_PURPOSE_DECRYPT.
[in]	chiave	La chiave da utilizzare per l'operazione. key deve avere uno scopo compatibile con purpose e tutti i relativi requisiti di utilizzo devono essere soddisfatti, altrimenti begin() restituirà un codice di errore appropriato.
[in]	in_params	Parametri aggiuntivi per l'operazione. Questo viene in genere utilizzato per fornire i dati di autenticazione, con KM_TAG_AUTH_TOKEN. Se durante la generazione sono stati forniti KM_TAG_APPLICATION_ID o KM_TAG_APPLICATION_DATA, devono essere forniti qui, altrimenti l'operazione non andrà a buon fine con KM_ERROR_INVALID_KEY_BLOB. Per le operazioni che richiedono un nonce o un IV, nelle chiavi generate con KM_TAG_CALLER_NONCE, in_params può contenere un tag KM_TAG_NONCE.
[out]	out_params	Parametri di output. Utilizzato per restituire dati aggiuntivi dall'inizializzazione dell'operazione, in particolare per restituire l'IV o il nonce dalle operazioni che generano un IV o un nonce. L'utente che chiama acquisisce la proprietà dell'array di parametri di output e deve liberarlo con keymaster_free_param_set() . out_params può essere impostato su NULL se non sono previsti parametri di output. Se out_params è NULL e vengono generati i parametri di output, begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	operation_handle	L'handle dell'operazione appena creato che deve essere passato a update() , finish() o abort() . Se operation_handle è NULL, begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.

Definizione nella riga 332 del file keymaster2.h .

Metodi comuni del dispositivo Keymaster. Questo deve essere il primo membro di keymaster_device, poiché gli utenti di questa struttura eseguiranno il casting di un hw_device_t al puntatore keymaster_device in contesti in cui è noto che hw_device_t fa riferimento a un keymaster_device.

Definizione nella riga 35 del file keymaster2.h .

Configura Keymaster. Questo metodo deve essere chiamato una volta aperto il dispositivo e prima che venga utilizzato. Viene utilizzato per fornire KM_TAG_OS_VERSION e KM_TAG_OS_PATCHLEVEL a Keymaster. Fino a quando non viene chiamato questo metodo, tutti gli altri metodi restituiranno KM_ERROR_KEYMASTER_NOT_CONFIGURED. I valori forniti da questo metodo vengono accettati da Keymaster una sola volta per avvio. Le chiamate successive restituiranno KM_ERROR_OK, ma non faranno nulla.

Se l'implementazione di Keymaster è in hardware sicuro e i valori della versione del sistema operativo e del livello di patch forniti non corrispondono a quelli forniti all'hardware sicuro dal bootloader (o se il bootloader non ha fornito valori), questo metodo restituirà KM_ERROR_INVALID_ARGUMENT e tutti gli altri metodi continueranno a restituire KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Definizione nella riga 58 del file keymaster2.h .

Definizione nella riga 37 del file keymaster2.h .

Consente di eliminare tutte le chiavi nel keystore hardware. Utilizzato quando il keystore viene reimpostato completamente. Dopo aver chiamato questa funzione, sarà impossibile utilizzare i blob delle chiavi generati o importati in precedenza per qualsiasi operazione.

Questa funzione è facoltativa e deve essere impostata su NULL se non è implementata.

Parametri

[in]

dev

La struttura del dispositivo Keymaster.

Definizione nella riga 288 del file keymaster2.h .

Consente di eliminare la chiave o la coppia di chiavi associata al blob della chiave. Dopo aver chiamato questa funzione, non sarà possibile utilizzare la chiave per altre operazioni. Può essere applicato alle chiavi di radici di attendibilità esterne (chiavi non utilizzabili nell'attuale radice di attendibilità).

Questa funzione è facoltativa e deve essere impostata su NULL se non è implementata.

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	chiave	La chiave da eliminare.

Definizione nella riga 276 del file keymaster2.h .

Esporta una chiave pubblica o simmetrica, restituendo un array di byte nel formato specificato.

Tieni presente che l'esportazione di chiavi simmetriche è consentita solo se la chiave è stata creata con KM_TAG_EXPORTABLE e solo se sono soddisfatti tutti i requisiti per l'utilizzo della chiave (ad es. l'autenticazione).

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	export_format	Il formato da utilizzare per l'esportazione della chiave.
[in]	key_to_export	La chiave da esportare.
[in]	client_id	Blob dell'ID cliente, che deve corrispondere al blob fornito in KM_TAG_APPLICATION_ID durante la generazione della chiave (se presente).
[in]	app_data	Blob di dati dell'applicazione, che deve corrispondere al blob fornito in KM_TAG_APPLICATION_DATA durante la generazione della chiave (se presente).
[out]	export_data	Il materiale della chiave esportato. Il chiamante assume la proprietà.

Definizione nella riga 213 del file keymaster2.h .

Finalizza un'operazione di crittografia iniziata con begin() e invalida operation_handle .

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	operation_handle	L'handle dell'operazione restituito da begin() . Questo handle verrà invalidato.
[in]	in_params	Parametri aggiuntivi per l'operazione. Per le modalità AEAD, viene utilizzato per specificare KM_TAG_ADDITIONAL_DATA, ma solo se non sono stati forniti dati di input a update() .
[in]	ingresso	Dati da elaborare, in base ai parametri stabiliti nella chiamata a begin() . finish() deve utilizzare tutti i dati forniti o restituire KM_ERROR_INVALID_INPUT_LENGTH.
[in]	firma	La firma da verificare se lo scopo specificato nella chiamata begin() era KM_PURPOSE_VERIFY.
[out]	output	Gli eventuali dati di output. Il chiamante assume la proprietà del buffer allocato.

Se l'operazione in fase di completamento è una verifica della firma o una decrittografia in modalità AEAD e la verifica non va a buon fine, finish() restituirà KM_ERROR_VERIFICATION_FAILED.

Definizione nella riga 405 del file keymaster2.h .

Consulta i flag definiti per keymaster0_devices::flags in keymaster_common.h . Utilizzato solo per la compatibilità con le versioni precedenti. I dispositivi hardware keymaster2 devono impostarlo su zero.

Definizione nella riga 43 del file keymaster2.h .

Genera una chiave o una coppia di chiavi, restituendo un blob della chiave e/o una descrizione della chiave.

I parametri di generazione delle chiavi sono definiti come coppie di tag/valore keymaster, forniti in params . Consulta keymaster_tag_t per l'elenco completo. Alcuni valori sempre richiesti per la generazione di chiavi utili sono:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; e
• (KM_TAG_USER_SECURE_ID e KM_TAG_USER_AUTH_TYPE) o KM_TAG_NO_AUTH_REQUIRED.

In genere, è necessario specificare KM_TAG_AUTH_TIMEOUT, a meno che non sia presente KM_TAG_NO_AUTH_REQUIRED, altrimenti l'utente dovrà autenticarsi per ogni utilizzo.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH e KM_TAG_DIGEST devono essere specificati per gli algoritmi che li richiedono.

I seguenti tag non possono essere specificati; i relativi valori verranno forniti dall'implementazione.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	params	Array di parametri di generazione della chiave
[out]	key_blob	restituisce la chiave generata. key_blob non deve essere NULL. L'utente che chiama assume la proprietà di key_blob->key_material e deve eseguire free() su questa.
[out]	caratteristiche	restituisce le caratteristiche della chiave generata, se non è NULL. Se non è NULL, il chiamante ne assume la proprietà e deve eseguire la deallocazione con keymaster_free_characteristics() . Tieni presente che KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA non vengono mai restituiti.

Definizione nella riga 112 del file keymaster2.h .

Restituisce le caratteristiche della chiave specificata o KM_ERROR_INVALID_KEY_BLOB se key_blob non è valido (le implementazioni devono convalidare completamente l'integrità della chiave). client_id e app_data devono essere l'ID e i dati forniti durante la generazione o l'importazione della chiave oppure essere vuoti se KM_TAG_APPLICATION_ID e/o KM_TAG_APPLICATION_DATA non sono stati forniti durante la generazione. Questi valori non sono inclusi nelle caratteristiche restituite. L'utente che chiama assume la proprietà dell'oggetto delle caratteristiche allocato, che deve essere deallocato con keymaster_free_characteristics() .

Tieni presente che KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA non vengono mai restituiti.

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	key_blob	La chiave da cui recuperare le caratteristiche.
[in]	client_id	I dati dell'ID cliente o NULL se non è associato alcun ID cliente.
[in]	app_id	I dati dell'app o NULL se non è associato nessuno.
[out]	caratteristiche	Le caratteristiche principali. Non deve essere NULL. L'utente che chiama assume la proprietà dei contenuti e deve eseguire la deallocazione con keymaster_free_characteristics() .

Definizione nella riga 139 del file keymaster2.h .

Importa una chiave o una coppia di chiavi, restituendo un blob della chiave e/o una descrizione della chiave.

La maggior parte dei parametri di importazione delle chiavi è definita come coppie di tag/valori keymaster, forniti in "params". Consulta keymaster_tag_t per l'elenco completo. I valori sempre richiesti per l'importazione di chiavi utili sono:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE; e
• (KM_TAG_USER_SECURE_ID e KM_TAG_USER_AUTH_TYPE) o KM_TAG_NO_AUTH_REQUIRED.

In genere, è necessario specificare KM_TAG_AUTH_TIMEOUT. Se non specificato, l'utente dovrà autenticarsi per ogni utilizzo.

Se non specificati, i seguenti tag assumeranno i valori predefiniti:

• Per impostazione predefinita, KM_TAG_KEY_SIZE corrisponde alle dimensioni della chiave fornita.
• Per impostazione predefinita, KM_TAG_RSA_PUBLIC_EXPONENT assume il valore della chiave fornita (per le chiavi RSA)

I seguenti tag non possono essere specificati; i relativi valori verranno forniti dall'implementazione.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	params	Parametri che definiscono la chiave importata.
[in]	params_count	Il numero di voci in params .
[in]	key_format	specifica il formato dei dati della chiave in key_data.
[out]	key_blob	Utilizzato per restituire il blob della chiave opaca. Non deve essere NULL. L'utente che chiama assume la proprietà del materiale della chiave contenuto.
[out]	caratteristiche	Utilizzato per restituire le caratteristiche della chiave importata. Può essere NULL, nel qual caso non verranno restituite caratteristiche. Se non è NULL, il chiamante assume la proprietà dei contenuti e deve eseguire lo scollegamento con keymaster_free_characteristics() . Tieni presente che KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA non vengono mai restituiti.

Definizione nella riga 186 del file keymaster2.h .

Fornisce dati a un'operazione di crittografia in corso iniziata con begin() e possibilmente ne riceve l'output.

Se operation_handle non è valido, update() restituirà KM_ERROR_INVALID_OPERATION_HANDLE.

update() potrebbe non utilizzare tutti i dati forniti nel buffer di dati. update() restituirà la quantità consumata in *data_consumed. L'utente che effettua la chiamata deve fornire i dati non utilizzati in una chiamata successiva.

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	operation_handle	L'handle dell'operazione restituito da begin() .
[in]	in_params	Parametri aggiuntivi per l'operazione. Per le modalità AEAD, viene utilizzato per specificare KM_TAG_ADDITIONAL_DATA. Tieni presente che è possibile fornire dati aggiuntivi in più chiamate a update() , ma solo fino a quando non sono stati forniti i dati di input.
[in]	ingresso	Dati da elaborare, in base ai parametri stabiliti nella chiamata a begin() . Tieni presente che update() potrebbe o meno utilizzare tutti i dati forniti. Consulta input_consumed .
[out]	input_consumed	Quantità di dati consumati da update() . Se è inferiore all'importo fornito, l'utente che chiama deve fornire il resto in una chiamata successiva a update() .
[out]	out_params	Parametri di output. Viene utilizzato per restituire dati aggiuntivi dall'operazione. L'autore della chiamata acquisisce la proprietà dell'array di parametri di output e deve liberarlo con keymaster_free_param_set() . out_params può essere impostato su NULL se non sono previsti parametri di output. Se out_params è NULL e vengono generati i parametri di output, begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	output	Gli eventuali dati di output. L'autore della chiamata assume la proprietà del buffer allocato. L'output non deve essere NULL.

Tieni presente che update() potrebbe non fornire alcun output, nel qual caso output->data_length sarà pari a zero e output->data potrebbe essere NULL o avere una lunghezza pari a zero (quindi l'utente che chiama deve sempre eseguire free() su di esso).

Definizione nella riga 376 del file keymaster2.h .

Esegue l'upgrade di una vecchia chiave. Le chiavi possono diventare "vecchie" in due modi: è possibile eseguire l'upgrade di Keymaster a una nuova versione oppure il sistema può essere aggiornato in modo da invalidare la versione del sistema operativo e/o il livello patch. In entrambi i casi, i tentativi di utilizzare una vecchia chiave faranno sì che Keymaster restituisca KM_ERROR_KEY_REQUIRES_UPGRADE. Questo metodo deve quindi essere chiamato per eseguire l'upgrade della chiave.

Parametri

[in]	dev	La struttura del dispositivo Keymaster.
[in]	key_to_upgrade	La chiave keymaster di cui eseguire l'upgrade.
[in]	upgrade_params	Parametri necessari per completare l'upgrade. In particolare, KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA saranno obbligatori se sono stati definiti per la chiave.
[out]	upgraded_key	Il blob della chiave di cui è stato eseguito l'upgrade.

Definizione nella riga 260 del file keymaster2.h .