keymaster2_device Riferimento alla struttura

keymaster2_device Riferimento alla struttura

#include < keymaster2.h >

Campi dati

struttura hw_device_t Comune
vuoto * contesto
uint32_t bandiere
keymaster_error_t (* configure )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)
keymaster_error_t (* add_rng_entropy )(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)
keymaster_error_t (* generate_key )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)
keymaster_error_t (* get_key_characteristics )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *characteristics)
keymaster_error_t (* import_key )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)
keymaster_error_t (* export_key )(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)
keymaster_error_t (* attest_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain)
keymaster_error_t (* upgrade_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key)
keymaster_error_t (* delete_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)
keymaster_error_t (* delete_all_keys )(const struct keymaster2_device *dev)
keymaster_error_t (* begin )(const struct keymaster2_device *dev, keymaster_purpose_t scopo, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle)
keymaster_error_t (* update )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
keymaster_error_t (* finish )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
keymaster_error_t (* abort )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

Descrizione dettagliata

Definizione del dispositivo Keymaster2

Definizione alla riga 28 del file keymaster2.h .

Documentazione sul campo

keymaster_error_t (* abort)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

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

Definizione alla riga 415 del file keymaster2.h .

keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)

Aggiunge entropia all'RNG utilizzato da keymaster. L'entropia aggiunta attraverso questo metodo è garantita per non essere 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 qualsiasi dato l'attaccante non può prevedere (o controllo), quindi l'uscita RNG è indistinguibile da casuale. Pertanto, se l'entropia da qualsiasi fonte è buona, l'output sarà buono.

Parametri
[in] div La struttura del dispositivo keymaster.
[in] dati Dati casuali da mischiare.
[in] lunghezza_dati Lunghezza dei data .

Definizione alla riga 74 del file keymaster2.h .

keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain)

Genera una catena di certificati X.509 firmata che attesta la presenza di key_to_attest in keymaster (TODO(swillden): Descrivi il contenuto del certificato in modo più dettagliato). 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] div La struttura del dispositivo keymaster.
[in] chiave_per_attestare La chiave keymaster per la quale verrà generato il certificato di attestazione.
[in] attesta_params Parametri che definiscono come eseguire l'attestazione. Attualmente l'unico parametro è KM_TAG_ALGORITHM, che deve essere KM_ALGORITHM_EC o KM_ALGORITHM_RSA. Questo seleziona quale delle chiavi di attestazione fornite verrà utilizzata per firmare il certificato.
[fuori] catena_certificata 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 .

keymaster_error_t (* begin)(const struct keymaster2_device *dev, keymaster_purpose_t scopo, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle)

Avvia un'operazione di crittografia utilizzando la chiave specificata. Se tutto va bene, begin() restituirà KM_ERROR_OK e creerà un handle di operazione che deve essere passato alle successive chiamate 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 del keymaster di ripulire qualsiasi stato operativo interno. In caso contrario, potrebbe perdere lo spazio di stato interno o altre risorse interne e alla fine potrebbe causare la restituzione di KM_ERROR_TOO_MANY_OPERATIONS da parte di Begin() quando si 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] div 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. Si noti 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 Ulteriori parametri per l'operazione. 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, devono essere forniti qui, altrimenti l'operazione avrà esito negativo con KM_ERROR_INVALID_KEY_BLOB. Per le operazioni che richiedono un nonce o un IV, sulle chiavi che sono state 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 IV o nonce da operazioni che generano un IV o nonce. Il chiamante assume la proprietà 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 operation_handle è NULL, begin() restituirà KM_ERROR_OUTPUT_PARAMETER_NULL.

Definizione alla riga 332 del file keymaster2.h .

struct hw_device_t comune

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

Definizione alla riga 35 del file keymaster2.h .

keymaster_error_t (* configure)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)

Configura keymaster. Questo metodo deve essere chiamato una volta dopo l'apertura del dispositivo e prima di essere utilizzato. 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 del keymaster è in 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 tutto altri metodi continueranno a restituire KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Definizione alla riga 58 del file keymaster2.h .

contesto vuoto*

Definizione alla riga 37 del file keymaster2.h .

keymaster_error_t (* delete_all_keys)(const struct keymaster2_device *dev)

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

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

Parametri
[in] div La struttura del dispositivo keymaster.

Definizione alla riga 288 del file keymaster2.h .

keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)

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

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

Parametri
[in] div La struttura del dispositivo keymaster.
[in] chiave La chiave da cancellare.

Definizione alla riga 276 del file keymaster2.h .

keymaster_error_t (* export_key)(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)

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

Si noti 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 (es. autenticazione).

Parametri
[in] div La struttura del dispositivo keymaster.
[in] formato_esportazione Il formato da utilizzare per esportare la chiave.
[in] chiave_da_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] dati_app Blob di dati dell'applicazione, che deve corrispondere al BLOB fornito in KM_TAG_APPLICATION_DATA durante la generazione della chiave (se presente).
[fuori] export_data Il materiale chiave esportato. Il chiamante assume la proprietà.

Definizione alla riga 213 del file keymaster2.h .

keymaster_error_t (* finish)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

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

Parametri
[in] div La struttura del dispositivo keymaster.
[in] operazione_handle L'handle dell'operazione restituito da begin() . Questo handle verrà invalidato.
[in] in_params Ulteriori parametri 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 per 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 corso è una verifica della firma o una decrittografia in modalità AEAD e la verifica non riesce, finish() restituirà KM_ERROR_VERIFICATION_FAILED.

Definizione alla riga 405 del file keymaster2.h .

flag uint32_t

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

Definizione alla riga 43 del file keymaster2.h .

keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)

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

I parametri di generazione delle chiavi sono definiti come coppie tag/valore keymaster, forniti 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_SCOPO; e
  • (KM_TAG_USER_SECURE_ID e KM_TAG_USER_AUTH_TYPE) o KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT dovrebbe generalmente essere specificato a meno che KM_TAG_NO_AUTH_REQUIRED non sia presente, 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 potrebbero non essere specificati; i loro valori saranno forniti dall'implementazione.

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Parametri
[in] div La struttura del dispositivo keymaster.
[in] parametri Array di parametri di generazione della 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 non NULL. Se non NULL, il chiamante assume la proprietà e deve deallocare 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 .

keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *characteristics)

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 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] div 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 nessuno è associato.
[fuori] caratteristiche Le caratteristiche chiave. Non deve essere NULL. Il chiamante assume la proprietà del contenuto e deve deallocare con keymaster_free_characteristics() .

Definizione alla riga 139 del file keymaster2.h .

keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)

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

La maggior parte dei parametri di importazione delle chiavi sono definiti come coppie tag/valore keymaster, forniti 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_SCOPO; 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.

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 verrà impostato automaticamente sul valore nella chiave fornita (per chiavi RSA)

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

  • KM_TAG_ORIGIN,
  • KM_TAG_ROLLBACK_RESISTANT,
  • KM_TAG_CREATION_DATETIME
Parametri
[in] div La struttura del dispositivo keymaster.
[in] parametri Parametri che definiscono la chiave importata.
[in] conteggio_parametri 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 chiave opaco. Deve essere non 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 verranno restituite le caratteristiche. Se non NULL, il chiamante assume la proprietà dei contenuti 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 .

keymaster_error_t (* update)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

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

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

update() potrebbe non consumare tutti i dati forniti nel buffer di dati. update() restituirà la quantità consumata in *data_consumed. Il chiamante dovrebbe fornire i dati non consumati in una chiamata successiva.

Parametri
[in] div La struttura del dispositivo keymaster.
[in] operazione_handle L'handle dell'operazione restituito da begin() .
[in] in_params Ulteriori parametri per l'operazione. Per le modalità AEAD, viene utilizzato per specificare KM_TAG_ADDITIONAL_DATA. Si noti che dati aggiuntivi possono essere forniti in più chiamate a update() , ma solo fino a quando non sono stati forniti i dati di input.
[in] ingresso Dati da elaborare, secondo i parametri stabiliti nella chiamata a begin() . Tieni presente che update() può consumare o meno tutti i dati forniti. Vedi input_consumed .
[fuori] input_consumato Quantità di dati consumata da update() . Se questo è inferiore all'importo fornito, il chiamante dovrebbe fornire il resto in una successiva chiamata a update() .
[fuori] out_params Parametri di uscita. Utilizzato per restituire dati aggiuntivi dall'operazione Il chiamante assume la proprietà 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.

Nota che update() potrebbe non fornire alcun output, nel qual caso output->data_length sarà zero e output->data potrebbe essere NULL o lunghezza zero (quindi il chiamante dovrebbe sempre liberarlo()).

Definizione alla riga 376 del file keymaster2.h .

keymaster_error_t (* upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key)

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 la restituzione di KM_ERROR_KEY_REQUIRES_UPGRADE da parte del keymaster. Questo metodo dovrebbe quindi essere chiamato per aggiornare la chiave.

Parametri
[in] div 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 di chiavi aggiornato.

Definizione alla riga 260 del file keymaster2.h .


La documentazione per questa struttura è stata generata dal seguente file: