Riferimento alla struttura keymaster2_device

Interrompe un'operazione crittografica iniziata con Begin() , liberando tutte le risorse interne e invalidando operation_handle .

Definizione alla riga 415 del file keymaster2.h .

Aggiunge entropia all'RNG utilizzato dal keymaster. È garantito che l'entropia aggiunta tramite questo metodo non sia l'unica fonte di entropia utilizzata e la funzione di miscelazione deve essere sicura, nel senso che se l'RNG viene seminato (da qualsiasi fonte) con dati l'attaccante non può prevedere (o controllo), allora l'uscita RNG non è distinguibile da quella casuale. Pertanto, se l’entropia proveniente da qualsiasi fonte è buona, il risultato sarà buono.

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	dati	Dati casuali da mescolare.
[In]	lunghezza_dati	Lunghezza dei data .

Definizione alla riga 74 del file keymaster2.h .

Genera una catena di certificati X.509 firmata che attesta la presenza di key_to_attest nel keymaster (TODO(swillden): descrivere il contenuto del certificato in maggiore dettaglio). Il certificato conterrà un'estensione con OID 1.3.6.1.4.1.11129.2.1.17 e valore definito in <TODO:swillden – inserisci link qui> che contiene la descrizione della chiave.

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	chiave_per_attestare	La chiave principale per la quale verrà generato il certificato di attestazione.
[In]	attesta_params	Parametri che definiscono come eseguire l'attestazione. Al momento l'unico parametro è KM_TAG_ALGORITHM, che deve essere KM_ALGORITHM_EC o KM_ALGORITHM_RSA. Seleziona quale delle chiavi di attestazione fornite verrà utilizzata per firmare il certificato.
[fuori]	catena_cert	Una matrice di certificati X.509 con codifica DER. Il primo sarà il certificato per key_to_attest . Le voci rimanenti verranno riconcatenate alla radice. Il chiamante assume la proprietà e deve deallocare con keymaster_free_cert_chain.

Definizione alla riga 239 del file keymaster2.h .

Inizia un'operazione di crittografia utilizzando la chiave specificata. Se tutto va bene, Begin() restituirà KM_ERROR_OK e creerà un handle di operazione che dovrà essere passato alle chiamate successive a update() , finish() o abort() .

È fondamentale che ogni chiamata a Begin() sia accoppiata con una successiva chiamata a Finish() o abort() , per consentire all'implementazione keymaster di ripulire qualsiasi stato operativo interno. In caso contrario, potrebbe verificarsi una perdita di spazio di stato interno o di altre risorse interne e potrebbe causare la restituzione di Begin() KM_ERROR_TOO_MANY_OPERATION quando esaurisce lo spazio per le operazioni. Qualsiasi risultato diverso da KM_ERROR_OK da Begin() , Update() o Finish() interrompe implicitamente l'operazione, nel qual caso non è necessario chiamare abort() (e restituirà KM_ERROR_INVALID_OPERATION_HANDLE se chiamato).

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	scopo	Lo scopo dell'operazione, uno tra 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 suoi 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 dati di autenticazione, con KM_TAG_AUTH_TOKEN. Se durante la generazione sono stati forniti KM_TAG_APPLICATION_ID o KM_TAG_APPLICATION_DATA, è necessario fornirli qui altrimenti l'operazione fallirà con KM_ERROR_INVALID_KEY_BLOB. Per le operazioni che richiedono un nonce o un IV, sulle chiavi generate con KM_TAG_CALLER_NONCE, in_params può contenere un tag KM_TAG_NONCE.
[fuori]	out_params	Parametri di uscita. 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. Il chiamante diventa proprietario dell'array dei 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 parametri di output, Begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.
[fuori]	operazione_handle	L'handle dell'operazione appena creato che deve essere passato a update() , finish() o abort() . Se operazione_handle è NULL, Begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.

Definizione alla 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 trasformeranno un puntatore hw_device_t in keymaster_device in contesti in cui è noto che hw_device_t fa riferimento a keymaster_device.

Definizione alla riga 35 del file keymaster2.h .

Configura il keymaster. Questo metodo deve essere chiamato una volta dopo l'apertura del dispositivo e prima del suo utilizzo. Viene utilizzato per fornire KM_TAG_OS_VERSION e KM_TAG_OS_PATCHLEVEL al keymaster. Fino a quando questo metodo non viene chiamato, tutti gli altri metodi restituiranno KM_ERROR_KEYMASTER_NOT_CONFIGURED. I valori forniti da questo metodo vengono accettati da keymaster solo una volta per avvio. Le chiamate successive restituiranno KM_ERROR_OK, ma non faranno nulla.

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

Definizione alla riga 58 del file keymaster2.h .

Definizione alla riga 37 del file keymaster2.h .

Elimina tutte le chiavi nell'archivio chiavi hardware. Utilizzato quando il keystore viene ripristinato completamente. Dopo aver chiamato questa funzione sarà impossibile utilizzare i key blob precedentemente generati o importati per qualsiasi operazione.

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

Parametri

[In]

dev

La struttura del dispositivo keymaster.

Definizione alla riga 288 del file keymaster2.h .

Elimina la chiave, o la coppia di chiavi, associata al BLOB di chiavi. Dopo aver richiamato questa funzione sarà impossibile utilizzare il tasto per qualsiasi altra operazione. Può essere applicato a chiavi provenienti da radici di fiducia esterne (chiavi non utilizzabili con la radice di fiducia corrente).

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 alla riga 276 del file keymaster2.h .

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

Tieni presente che l'esportazione della chiave simmetrica è 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 esempio l'autenticazione).

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	formato_esportazione	Il formato da utilizzare per esportare la chiave.
[In]	chiave_per_esportare	La chiave per esportare.
[In]	Identificativo cliente	BLOB ID client, 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).
[fuori]	dati_esporta	Il materiale chiave esportato. Il chiamante ne assume la proprietà.

Definizione alla riga 213 del file keymaster2.h .

Finalizza un'operazione crittografica iniziata con Begin() e invalida operation_handle .

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	operazione_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, secondo i parametri stabiliti nella chiamata a Begin() . finish() deve consumare 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.
[fuori]	produzione	I dati di output, se presenti. Il chiamante assume la proprietà del buffer allocato.

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

Definizione alla riga 405 del file keymaster2.h .

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

Definizione alla riga 43 del file keymaster2.h .

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

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

• KM_TAG_ALGORITMO;
• 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 loro valori saranno forniti dall'implementazione.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTENTE,
• KM_TAG_CREATION_DATETIME

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	parametri	Array di parametri di generazione chiave
[fuori]	key_blob	restituisce la chiave generata. key_blob non deve essere NULL. Il chiamante assume la proprietà key_blob->key_material e deve liberarlo.
[fuori]	caratteristiche	restituisce le caratteristiche della chiave che è stata generata, se diversa da NULL. Se diverso da NULL, il chiamante ne assume la proprietà e deve effettuare 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 alla 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 al momento della generazione o dell'importazione della chiave oppure vuoti se KM_TAG_APPLICATION_ID e/o KM_TAG_APPLICATION_DATA non sono stati forniti durante la generazione. Tali valori non sono inclusi nelle caratteristiche restituite. Il chiamante assume la proprietà dell'oggetto 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]	Identificativo cliente	I dati dell'ID client o NULL se nessuno è associato.
[In]	app_id	I dati dell'app o NULL se non associati.
[fuori]	caratteristiche	Le caratteristiche chiave. Non deve essere NULL. Il chiamante assume la proprietà dei contenuti e deve deallocare con keymaster_free_characteristics() .

Definizione alla riga 139 del file keymaster2.h .

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

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

• KM_TAG_ALGORITMO;
• 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 ad ogni utilizzo.

I seguenti tag assumeranno valori predefiniti se non specificati:

• KM_TAG_KEY_SIZE utilizzerà per impostazione predefinita la dimensione della chiave fornita.
• KM_TAG_RSA_PUBLIC_EXPONENT utilizzerà per impostazione predefinita il valore nella chiave fornita (per chiavi RSA)

I seguenti tag non possono essere specificati; i loro valori saranno forniti dall'implementazione.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTENTE,
• KM_TAG_CREATION_DATETIME

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	parametri	Parametri che definiscono la chiave importata.
[In]	params_count	Il numero di voci in params .
[In]	formato_chiave	specifica il formato dei dati chiave in key_data.
[fuori]	key_blob	Utilizzato per restituire il BLOB della chiave opaca. Deve essere diverso da NULL. Il chiamante assume la proprietà del key_material contenuto.
[fuori]	caratteristiche	Utilizzato per restituire le caratteristiche della chiave importata. Può essere NULL, nel qual caso non verrà restituita alcuna caratteristica. Se diverso da NULL, il chiamante assume la proprietà del contenuto e deve deallocare con keymaster_free_characteristics() . Tieni presente che KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA non vengono mai restituiti.

Definizione alla riga 186 del file keymaster2.h .

Fornisce dati e possibilmente riceve output da un'operazione crittografica in corso iniziata con Begin() .

Se operazione_handle non è valida, update() restituirà KM_ERROR_INVALID_OPERATION_HANDLE.

update() potrebbe non consumare tutti i dati forniti nel buffer di dati. update() restituirà l'importo consumato in *data_consumed. Il chiamante dovrà fornire i dati non utilizzati in una chiamata successiva.

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	operazione_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 dati aggiuntivi potrebbero essere forniti in più chiamate a update() , ma solo fino a quando non saranno stati forniti i dati di input.
[In]	ingresso	Dati da elaborare, secondo i parametri stabiliti nella chiamata a Begin() . Tieni presente che update() potrebbe consumare o meno tutti i dati forniti. Vedi input_consumed .
[fuori]	input_consumato	Quantità di dati consumati da update() . Se questo è inferiore all'importo fornito, il chiamante dovrebbe fornire il resto in una chiamata successiva a update() .
[fuori]	out_params	Parametri di uscita. Utilizzato per restituire dati aggiuntivi dall'operazione. Il chiamante diventa proprietario dell'array dei 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 parametri di output, Begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.
[fuori]	produzione	I dati di output, se presenti. Il chiamante 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à zero e output->data potrebbe essere NULL o zero-length (quindi il chiamante dovrebbe sempre liberarlo).

Definizione alla riga 376 del file keymaster2.h .

Aggiorna una vecchia chiave. Le chiavi possono diventare "vecchie" in due modi: Keymaster può essere aggiornato a una nuova versione oppure il sistema può essere aggiornato per invalidare la versione del sistema operativo e/o il livello di patch. In entrambi i casi, i tentativi di utilizzare una vecchia chiave comporteranno che il keymaster restituisca KM_ERROR_KEY_REQUIRES_UPGRADE. Questo metodo dovrebbe quindi essere chiamato per aggiornare la chiave.

Parametri

[In]	dev	La struttura del dispositivo keymaster.
[In]	chiave_per_aggiornare	La chiave principale per l'aggiornamento.
[In]	upgrade_params	Parametri necessari per completare l'aggiornamento. In particolare, saranno richiesti KM_TAG_APPLICATION_ID e KM_TAG_APPLICATION_DATA se sono stati definiti per la chiave.
[fuori]	chiave_aggiornata	Il BLOB della chiave aggiornato.

Definizione alla riga 260 del file keymaster2.h .