Funzioni del tastierista

Questa pagina fornisce dettagli per assistere gli implementatori di Keymaster Hardware Abstraction Layers (HAL). Copre ogni funzione nell'API e in quale versione di Keymaster è disponibile tale funzione e descrive l'implementazione predefinita. Per i tag, consulta la pagina Tag Keymaster .

Linee guida generali per l'attuazione

Le seguenti linee guida si applicano a tutte le funzioni dell'API.

Parametri del puntatore di input

Versione : 1, 2

I parametri del puntatore di input che non vengono utilizzati per una determinata chiamata possono essere NULL . Al chiamante non è richiesto di fornire segnaposto. Ad esempio, alcuni tipi e modalità di chiave potrebbero non utilizzare alcun valore dall'argomento inParams per Begin , quindi il chiamante potrebbe impostare inParams su NULL o fornire un set di parametri vuoto. I chiamanti possono anche fornire parametri inutilizzati e i metodi Keymaster non dovrebbero generare errori.

Se un parametro di input richiesto è NULL, i metodi Keymaster dovrebbero restituire ErrorCode::UNEXPECTED_NULL_POINTER .

A partire da Keymaster 3, non ci sono parametri del puntatore. Tutti i parametri vengono passati per valore o riferimenti const.

Parametri del puntatore di output

Versione : 1, 2

Analogamente ai parametri del puntatore di input, i parametri del puntatore di output inutilizzati possono essere NULL . Se un metodo deve restituire dati in un parametro di output trovato NULL , dovrebbe restituire ErrorCode::OUTPUT_PARAMETER_NULL .

A partire da Keymaster 3, non ci sono parametri del puntatore. Tutti i parametri vengono passati per valore o riferimenti const.

Uso improprio dell'API

Versione : 1, 2, 3

Esistono molti modi in cui i chiamanti possono avanzare richieste senza senso o insensate ma non tecnicamente sbagliate. In questi casi non è necessario che le implementazioni Keymaster falliscano o emettano una diagnostica. L'uso di chiavi troppo piccole, la specifica di parametri di input irrilevanti, il riutilizzo di IV o nonce, la generazione di chiavi senza scopo (quindi inutili) e simili non dovrebbero essere diagnosticati dalle implementazioni. È necessario diagnosticare l'omissione di parametri richiesti, la specifica di parametri richiesti non validi ed errori simili.

È responsabilità delle app, del framework e del keystore Android garantire che le chiamate ai moduli Keymaster siano sensate e utili.

Funzioni

getCaratteristiche hardware

Versione : 3

Il nuovo metodo getHardwareFeatures espone ai client alcune importanti caratteristiche dell'hardware sicuro sottostante. Il metodo non accetta argomenti e restituisce quattro valori, tutti booleani:

  • isSecure è true se le chiavi sono archiviate in hardware sicuro (TEE, ecc.) e non lo lasciano mai.
  • supportsEllipticCurve è true se l'hardware supporta la crittografia della curva ellittica con le curve NIST (P-224, P-256, P-384 e P-521).
  • supportsSymmetricCryptography è true se l'hardware supporta la crittografia simmetrica, inclusi AES e HMAC.
  • supportsAttestation è true se l'hardware supporta la generazione di certificati di attestazione a chiave pubblica Keymaster, firmati con una chiave inserita in un ambiente sicuro.

Gli unici codici di errore che questo metodo può restituire sono ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED o uno dei codici di errore che indicano un'impossibilità di comunicare con l'hardware protetto.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

configurare

Versione : 2

Questa funzione è stata introdotta in Keymaster 2 e deprecata in Keymaster 3, poiché queste informazioni sono disponibili nei file delle proprietà del sistema e le implementazioni del produttore leggono tali file durante l'avvio.

Configura il keymaster. Questo metodo viene chiamato una volta dopo l'apertura del dispositivo e prima dell'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 restituiscono KM_ERROR_KEYMASTER_NOT_CONFIGURED . I valori forniti da questo metodo vengono accettati da keymaster solo una volta per avvio. Le chiamate successive restituiscono KM_ERROR_OK , ma non fanno 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 restituisce KM_ERROR_INVALID_ARGUMENT e tutti gli altri i metodi continuano a restituire KM_ERROR_KEYMASTER_NOT_CONFIGURED .

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

addRngEntropia

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come add_rng_entropy e rinominata in Keymaster 3.

Aggiunge entropia fornita dal chiamante al pool utilizzato dall'implementazione Keymaster 1 per generare numeri casuali, chiavi, IV, ecc.

Le implementazioni di Keymaster devono mescolare in modo sicuro l'entropia fornita nel loro pool, che deve anche contenere entropia generata internamente da un generatore di numeri casuali hardware. Il mixaggio dovrebbe essere gestito in modo tale che un utente malintenzionato che ha il controllo completo dei bit forniti da addRngEntropy o dei bit generati dall'hardware, ma non di entrambi, non abbia un vantaggio non trascurabile nel prevedere i bit generati dal pool di entropia.

Le implementazioni Keymaster che tentano di stimare l'entropia nel loro pool interno presuppongono che i dati forniti da addRngEntropy non contengano entropia. Le implementazioni Keymaster possono restituire ErrorCode::INVALID_INPUT_LENGTH se ricevono più di 2 KiB di dati in una singola chiamata.

generateKey

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come generate_key e rinominata in Keymaster 3.

Genera una nuova chiave crittografica, specificando le autorizzazioni associate, che sono permanentemente legate alla chiave. Le implementazioni Keymaster rendono impossibile l'utilizzo di una chiave in qualsiasi modo non coerente con le autorizzazioni specificate al momento della generazione. Per quanto riguarda le autorizzazioni che l'hardware sicuro non può applicare, l'obbligo dell'hardware sicuro è limitato a garantire che le autorizzazioni non applicabili associate alla chiave non possano essere modificate, in modo che ogni chiamata a getKeyCharacteristics restituisca il valore originale. Inoltre, le caratteristiche restituite da generateKey allocano correttamente le autorizzazioni tra gli elenchi applicati dall'hardware e quelli applicati dal software. Vedi getKeyCharacteristics per maggiori dettagli.

I parametri forniti a generateKey dipendono dal tipo di chiave generata. Questa sezione riepiloga i tag necessari e facoltativi per ciascun tipo di chiave. Tag::ALGORITHM è sempre necessario per specificare il tipo.

Chiavi RSA

I seguenti parametri sono necessari per generare una chiave RSA.

  • Tag::KEY_SIZE specifica la dimensione del modulo pubblico, in bit. Se omesso, il metodo restituisce ErrorCode::UNSUPPORTED_KEY_SIZE . I valori supportati sono 1024, 2048, 3072 e 4096. I valori consigliati sono tutte le dimensioni delle chiavi che sono multipli di 8.
  • Tag::RSA_PUBLIC_EXPONENT specifica il valore dell'esponente pubblico RSA. Se omesso, il metodo restituisce ErrorCode::INVALID_ARGUMENT . I valori supportati sono 3 e 65537. I valori consigliati sono tutti valori primi fino a 2^64.

I seguenti parametri non sono necessari per generare una chiave RSA, ma la creazione di una chiave RSA senza di essi produce una chiave inutilizzabile. Tuttavia, la funzione generateKey non restituisce un errore se questi parametri vengono omessi.

  • Tag::PURPOSE specifica gli scopi consentiti. Tutti gli scopi devono essere supportati per le chiavi RSA, in qualsiasi combinazione.
  • Tag::DIGEST specifica gli algoritmi digest che possono essere utilizzati con la nuova chiave. Le implementazioni che non supportano tutti gli algoritmi digest devono accettare richieste di generazione di chiavi che includono digest non supportati. I digest non supportati devono essere inseriti nell'elenco "applicato dal software" nelle caratteristiche chiave restituite. Questo perché la chiave è utilizzabile con gli altri digest, ma la digest viene eseguita nel software. Quindi viene chiamato l'hardware per eseguire l'operazione con Digest::NONE .
  • Tag::PADDING specifica le modalità di riempimento che possono essere utilizzate con la nuova chiave. Le implementazioni che non supportano tutti gli algoritmi digest devono inserire PaddingMode::RSA_PSS e PaddingMode::RSA_OAEP nell'elenco applicato dal software delle caratteristiche chiave se vengono specificati algoritmi digest non supportati.

Chiavi ECDSA

Solo Tag::KEY_SIZE è necessario per generare una chiave ECDSA. Viene utilizzato per selezionare il gruppo EC. I valori supportati sono 224, 256, 384 e 521, che indicano rispettivamente le curve NIST p-224, p-256, p-384 e p521.

Anche Tag::DIGEST è necessario per una chiave ECDSA utile, ma non è richiesto per la generazione.

Chiavi AES

Per generare una chiave AES è necessario solo Tag::KEY_SIZE . Se omesso, il metodo restituisce ErrorCode::UNSUPPORTED_KEY_SIZE . I valori supportati sono 128 e 256, con supporto opzionale per chiavi AES a 192 bit.

I seguenti parametri sono particolarmente rilevanti per le chiavi AES, ma non necessari per generarne una:

  • Tag::BLOCK_MODE specifica le modalità di blocco con cui può essere utilizzata la nuova chiave.
  • Tag::PADDING specifica le modalità di riempimento che possono essere utilizzate. Ciò è rilevante solo per le modalità BCE e CBC.

Se è specificata la modalità di blocco GCM, fornire Tag::MIN_MAC_LENGTH . Se omesso, il metodo restituisce ErrorCode::MISSING_MIN_MAC_LENGTH . Il valore del tag è un multiplo di 8 ed è compreso tra 96 ​​e 128.

Chiavi HMAC

Per la generazione della chiave HMAC sono richiesti i seguenti parametri:

  • Tag::KEY_SIZE specifica la dimensione della chiave in bit. I valori inferiori a 64 e i valori che non sono multipli di 8 non sono supportati. Sono supportati tutti i multipli di 8, da 64 a 512. Potrebbero essere supportati valori più grandi.
  • Tag::MIN_MAC_LENGTH specifica la lunghezza minima dei MAC che possono essere generati o verificati con questa chiave. Il valore è un multiplo di 8 e almeno 64.
  • Tag::DIGEST specifica l'algoritmo digest per la chiave. Viene specificato esattamente un digest, altrimenti restituisce ErrorCode::UNSUPPORTED_DIGEST . Se il digest non è supportato dal trustlet, restituisce ErrorCode::UNSUPPORTED_DIGEST .

Caratteristiche chiave

Se l'argomento delle caratteristiche è diverso da NULL, generateKey restituisce le caratteristiche della chiave appena generata suddivise opportunamente in elenchi imposti dall'hardware e applicati dal software. Vedi getKeyCharacteristics per una descrizione di quali caratteristiche vanno in quale elenco. Le caratteristiche restituite includono tutti i parametri specificati per la generazione della chiave, ad eccezione di Tag::APPLICATION_ID e Tag::APPLICATION_DATA . Se questi tag erano inclusi nei parametri chiave, vengono rimossi dalle caratteristiche restituite in modo che non sia possibile trovare i loro valori esaminando il key blob restituito. Tuttavia, sono associati crittograficamente al BLOB di chiave, in modo che se non vengono forniti i valori corretti quando viene utilizzata la chiave, l'utilizzo non riesce. Allo stesso modo, Tag::ROOT_OF_TRUST è legato crittograficamente alla chiave, ma potrebbe non essere specificato durante la creazione o l'importazione della chiave e non verrà mai restituito.

Oltre ai tag forniti, il trustlet aggiunge anche Tag::ORIGIN , con il valore KeyOrigin::GENERATED e se la chiave è resistente al rollback,

Etichetta::ROLLBACK_RESISTENTE .

Resistenza al rollback

La resistenza al rollback significa che una volta che una chiave viene eliminata con deleteKey o deleteAllKeys , l'hardware sicuro garantisce che non sarà mai più utilizzabile. Le implementazioni senza resistenza al rollback in genere restituiscono al chiamante il materiale della chiave generato o importato come un BLOB di chiavi, un modulo crittografato e autenticato. Quando il keystore elimina il BLOB della chiave, la chiave scompare, ma un utente malintenzionato che è riuscito in precedenza a recuperare il materiale della chiave può potenzialmente ripristinarlo sul dispositivo.

Una chiave è resistente al rollback se l'hardware sicuro garantisce che le chiavi eliminate non possano essere ripristinate in seguito. Ciò avviene generalmente memorizzando metadati chiave aggiuntivi in ​​una posizione attendibile che non può essere manipolata da un utente malintenzionato. Sui dispositivi mobili, il meccanismo utilizzato a questo scopo è solitamente Replay Protected Memory Blocks (RPMB). Poiché il numero di chiavi che possono essere create è essenzialmente illimitato e lo spazio di archiviazione attendibile utilizzato per la resistenza al rollback può essere di dimensioni limitate, questo metodo deve avere successo anche se non è possibile fornire la resistenza al rollback per la nuova chiave. In tal caso, Tag::ROLLBACK_RESISTANT non dovrebbe essere aggiunto alle caratteristiche chiave.

getKeyCharacteristics

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come get_key_characteristics e rinominata in Keymaster 3.

Restituisce i parametri e le autorizzazioni associati alla chiave fornita, divisi in due set: imposto dall'hardware e applicato dal software. La descrizione qui si applica ugualmente agli elenchi di caratteristiche chiave restituiti da generateKey e importKey .

Se Tag::APPLICATION_ID è stato fornito durante la generazione o l'importazione della chiave, lo stesso valore viene fornito a questo metodo nell'argomento clientId . In caso contrario, il metodo restituisce ErrorCode::INVALID_KEY_BLOB . Allo stesso modo, se Tag::APPLICATION_DATA è stato fornito durante la generazione o l'importazione, lo stesso valore viene fornito a questo metodo nell'argomento appData .

Le caratteristiche restituite da questo metodo descrivono completamente il tipo e l'utilizzo della chiave specificata.

La regola generale per decidere se un dato tag appartiene all'elenco applicato dall'hardware o dal software è che se il significato del tag è completamente garantito dall'hardware sicuro, è applicato dall'hardware. Altrimenti, è applicato dal software. Di seguito è riportato un elenco di tag specifici la cui corretta allocazione potrebbe non essere chiara:

  • Tag::ALGORITHM , Tag::KEY_SIZE e Tag::RSA_PUBLIC_EXPONENT sono proprietà intrinseche della chiave. Per qualsiasi chiave protetta dall'hardware, questi tag saranno nell'elenco applicato dall'hardware.
  • I valori Tag::DIGEST supportati dall'hardware protetto vengono inseriti nell'elenco supportato dall'hardware. I digest non supportati vengono inseriti nell'elenco dei software supportati.
  • I valori Tag::PADDING generalmente vanno nell'elenco supportato dall'hardware, a meno che non vi sia la possibilità che una modalità di riempimento specifica debba essere eseguita dal software. In tal caso, vanno nell'elenco applicato dal software. Tale possibilità si presenta per le chiavi RSA che consentono il riempimento PSS o OAEP con algoritmi digest che non sono supportati dall'hardware sicuro.
  • Tag::USER_SECURE_ID e Tag::USER_AUTH_TYPE sono applicati tramite hardware solo se l'autenticazione utente è applicata tramite hardware. Per raggiungere questo obiettivo, il trustlet Keymaster e il relativo trustlet di autenticazione devono essere entrambi sicuri e condividere una chiave HMAC segreta utilizzata per firmare e convalidare i token di autenticazione. Consulta la pagina Autenticazione per i dettagli.
  • I tag Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME e Tag ::USAGE_EXPIRE_DATETIME richiedono l'accesso a un orologio da parete verificabilmente corretto. L'hardware più sicuro ha accesso solo alle informazioni temporali fornite dal sistema operativo non sicuro, il che significa che i tag sono applicati dal software.
  • Tag::ORIGIN è sempre nell'elenco hardware per le chiavi associate all'hardware. La sua presenza in tale elenco è il modo in cui i livelli superiori determinano che una chiave è supportata dall'hardware.

importKey

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come import_key e rinominata in Keymaster 3.

Importa il materiale chiave nell'hardware Keymaster. I parametri di definizione della chiave e le caratteristiche di output vengono gestiti allo stesso modo di generateKey , con le seguenti eccezioni:

  • Tag::KEY_SIZE e Tag::RSA_PUBLIC_EXPONENT (solo per chiavi RSA) non sono necessari nei parametri di input. Se non fornito, il trustlet deduce i valori dal materiale chiave fornito e aggiunge tag e valori appropriati alle caratteristiche chiave. Se vengono forniti i parametri, il trustlet li convalida rispetto al materiale della chiave. In caso di mancata corrispondenza, il metodo restituisce ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • Il Tag::ORIGIN restituito ha lo stesso valore di KeyOrigin::IMPORTED .

ExportKey

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come export_key e rinominata in Keymaster 3.

Esporta una chiave pubblica da una coppia di chiavi Keymaster RSA o EC.

Se Tag::APPLICATION_ID è stato fornito durante la generazione o l'importazione della chiave, lo stesso valore viene fornito a questo metodo nell'argomento clientId . In caso contrario, il metodo restituisce ErrorCode::INVALID_KEY_BLOB . Allo stesso modo, se Tag::APPLICATION_DATA è stato fornito durante la generazione o l'importazione, lo stesso valore viene fornito a questo metodo nell'argomento appData .

deleteKey

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come delete_key e rinominata in Keymaster 3.

Elimina la chiave fornita. Questo metodo è facoltativo ed è implementato solo dai moduli Keymaster che forniscono resistenza al rollback.

deleteAllKeys

Versione : 1, 2, 3

Questa funzione è stata introdotta in Keymaster 1 come delete_all_keys e rinominata in Keymaster 3.

Elimina tutte le chiavi. Questo metodo è facoltativo ed è implementato solo dai moduli Keymaster che forniscono resistenza al rollback.

destroyAttestationIds

Versione : 3

Il metodo destroyAttestationIds() viene utilizzato per disabilitare in modo permanente la nuova funzionalità di attestazione dell'ID (facoltativa, ma altamente consigliata). Se il TEE non ha modo di garantire che l'attestazione dell'ID sia permanentemente disabilitata dopo la chiamata a questo metodo, allora l'attestazione dell'ID non deve essere implementata affatto, nel qual caso questo metodo non fa nulla e restituisce ErrorCode::UNIMPLEMENTED . Se l'attestazione dell'ID è supportata, questo metodo deve essere implementato e deve disabilitare in modo permanente tutti i futuri tentativi di attestazione dell'ID. Il metodo può essere chiamato un numero qualsiasi di volte. Se l'attestazione dell'ID è già disabilitata in modo permanente, il metodo non fa nulla e restituisce ErrorCode::OK .

Gli unici codici di errore che questo metodo può restituire sono ErrorCode::UNIMPLEMENTED (se l'attestazione ID non è supportata), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED o uno dei codici di errore che indicano un errore di comunicazione con l'hardware protetto.

inizio

Versione : 1, 2, 3

Inizia un'operazione di crittografia, utilizzando la chiave specificata, per lo scopo specificato, con i parametri specificati (a seconda dei casi) e restituisce un handle dell'operazione utilizzato con update e finish per completare l'operazione. L'handle dell'operazione viene utilizzato anche come token di "sfida" nelle operazioni autenticate e per tali operazioni è incluso nel campo challenge del token di autenticazione.

Un'implementazione Keymaster supporta almeno 16 operazioni simultanee. Keystore ne utilizza fino a 15, lasciandone uno a vold da utilizzare per la crittografia della password. Quando Keystore ha 15 operazioni in corso (è stato chiamato begin , ma finish o abort non sono ancora stati chiamati) e riceve una richiesta per iniziare una sedicesima, chiama abort sull'operazione utilizzata meno recentemente per ridurre il numero di operazioni attive alle 14 prima di begin a chiamare per avviare l'operazione appena richiesta.

Se Tag::APPLICATION_ID o Tag::APPLICATION_DATA sono stati specificati durante la generazione o l'importazione della chiave, le chiamate a begin includono tali tag con i valori originariamente specificati nell'argomento inParams di questo metodo.

Esecuzione dell'autorizzazione

Durante questo metodo, le seguenti autorizzazioni chiave vengono applicate dal trustlet se l'implementazione le ha inserite nelle caratteristiche "applicate dall'hardware" e se l'operazione non è un'operazione di chiave pubblica. Le operazioni con chiave pubblica, ovvero KeyPurpose::ENCRYPT e KeyPurpose::VERIFY , con chiavi RSA o EC, possono avere esito positivo anche se i requisiti di autorizzazione non sono soddisfatti.

  • Tag::PURPOSE : lo scopo specificato nella chiamata begin() deve corrispondere a uno degli scopi nelle autorizzazioni della chiave, a meno che l'operazione richiesta non sia un'operazione con chiave pubblica. Se lo scopo specificato non corrisponde e l'operazione non è un'operazione di chiave pubblica, begin restituirà ErrorCode::UNSUPPORTED_PURPOSE . Le operazioni con chiave pubblica sono operazioni di crittografia o verifica asimmetriche.
  • Tag::ACTIVE_DATETIME può essere applicato solo se è disponibile un'origine ora UTC attendibile. Se la data e l'ora correnti sono precedenti al valore del tag, il metodo restituisce ErrorCode::KEY_NOT_YET_VALID .
  • Il tag::ORIGINATION_EXPIRE_DATETIME può essere applicato solo se è disponibile un'origine ora UTC attendibile. Se la data e l'ora correnti sono successive al valore del tag e lo scopo è KeyPurpose::ENCRYPT o KeyPurpose::SIGN , il metodo restituisce ErrorCode::KEY_EXPIRED .
  • Tag::USAGE_EXPIRE_DATETIME può essere applicato solo se è disponibile un'origine ora UTC attendibile. Se la data e l'ora correnti sono successive al valore del tag e lo scopo è KeyPurpose::DECRYPT o KeyPurpose::VERIFY , il metodo restituisce ErrorCode::KEY_EXPIRED .
  • Tag::MIN_SECONDS_BETWEEN_OPS viene confrontato con un timer relativo attendibile che indica l'ultimo utilizzo della chiave. Se l'ora dell'ultimo utilizzo più il valore del tag è inferiore all'ora corrente, il metodo restituisce ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Consulta la descrizione del tag per importanti dettagli di implementazione.
  • Tag::MAX_USES_PER_BOOT viene confrontato con un contatore sicuro che tiene traccia degli utilizzi della chiave dal momento dell'avvio. Se il conteggio degli utilizzi precedenti supera il valore del tag, il metodo restituisce ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • Tag::USER_SECURE_ID viene applicato con questo metodo solo se la chiave ha anche Tag::AUTH_TIMEOUT . Se la chiave li ha entrambi, questo metodo deve ricevere un Tag::AUTH_TOKEN valido in inParams . Affinché il token di autenticazione sia valido, tutte le seguenti condizioni devono essere vere:
    • Il campo HMAC viene convalidato correttamente.
    • Almeno uno dei valori Tag::USER_SECURE_ID della chiave corrisponde ad almeno uno dei valori ID protetti nel token.
    • La chiave ha un Tag::USER_AUTH_TYPE che corrisponde al tipo di autenticazione nel token.

    Se una qualsiasi di queste condizioni non è soddisfatta, il metodo restituisce ErrorCode::KEY_USER_NOT_AUTHENTICATED .

  • Tag::CALLER_NONCE consente al chiamante di specificare un nonce o un vettore di inizializzazione (IV). Se la chiave non ha questo tag, ma il chiamante ha fornito Tag::NONCE a questo metodo, viene restituito ErrorCode::CALLER_NONCE_PROHIBITED .
  • Tag::BOOTLOADER_ONLY specifica che solo il bootloader può utilizzare la chiave. Se questo metodo viene chiamato con una chiave riservata solo al bootloader dopo che il bootloader ha terminato l'esecuzione, restituisce ErrorCode::INVALID_KEY_BLOB .

Chiavi RSA

Tutte le operazioni chiave RSA specificano esattamente una modalità di riempimento in inParams . Se non specificato o specificato più di una volta, il metodo restituisce ErrorCode::UNSUPPORTED_PADDING_MODE .

Le operazioni di firma e verifica RSA necessitano di un digest, così come le operazioni di crittografia e decrittografia RSA con modalità di riempimento OAEP. In questi casi, il chiamante specifica esattamente un digest in inParams . Se non specificato o specificato più di una volta, il metodo restituisce ErrorCode::UNSUPPORTED_DIGEST .

Le operazioni con chiave privata ( KeyPurpose::DECYPT e KeyPurpose::SIGN ) richiedono l'autorizzazione di digest e riempimento, il che significa che le autorizzazioni della chiave devono contenere i valori specificati. In caso contrario, il metodo restituisce ErrorCode::INCOMPATIBLE_DIGEST o ErrorCode::INCOMPATIBLE_PADDING , a seconda dei casi. Le operazioni con chiave pubblica ( KeyPurpose::ENCRYPT e KeyPurpose::VERIFY ) sono consentite con digest o riempimento non autorizzati.

Ad eccezione di PaddingMode::NONE , tutte le modalità di riempimento RSA sono applicabili solo a determinati scopi. Nello specifico, PaddingMode::RSA_PKCS1_1_5_SIGN e PaddingMode::RSA_PSS supportano solo la firma e la verifica, mentre PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT e PaddingMode::RSA_OAEP supportano solo la crittografia e la decrittografia. Il metodo restituisce ErrorCode::UNSUPPORTED_PADDING_MODE se la modalità specificata non supporta lo scopo specificato.

Esistono alcune interazioni importanti tra le modalità di riempimento e i digest:

  • PaddingMode::NONE indica che viene eseguita un'operazione RSA "grezza". Se si firma o si verifica, viene specificato Digest::NONE per il digest. Non è necessario alcun digest per la crittografia o decrittografia senza riempimento.
  • PaddingMode::RSA_PKCS1_1_5_SIGN richiede un digest. Il digest può essere Digest::NONE , nel qual caso l'implementazione Keymaster non può creare una struttura di firma PKCS#1 v1.5 corretta, perché non può aggiungere la struttura DigestInfo. Invece, l'implementazione costruisce 0x00 || 0x01 || PS || 0x00 || M , dove M è il messaggio fornito e PS è la stringa di riempimento. La dimensione della chiave RSA deve essere almeno 11 byte più grande del messaggio, altrimenti il ​​metodo restituisce ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT il riempimento non richiede un digest.
  • PaddingMode::RSA_PSS Il riempimento richiede un digest, che potrebbe non essere Digest::NONE . Se viene specificato Digest::NONE , il metodo restituisce ErrorCode::INCOMPATIBLE_DIGEST . Inoltre, la dimensione della chiave RSA deve essere almeno 2 + D byte maggiore della dimensione di output del digest, dove D è la dimensione del digest, in byte. Altrimenti il ​​metodo restituisce ErrorCode::INCOMPATIBLE_DIGEST . La dimensione del sale è D.
  • PaddingMode::RSA_OAEP Il riempimento richiede un digest, che potrebbe non essere Digest::NONE . Se viene specificato Digest::NONE , il metodo restituisce ErrorCode::INCOMPATIBLE_DIGEST .

Chiavi CE

Le operazioni chiave EC specificano esattamente una modalità di riempimento in inParams . Se non specificato o specificato più di una volta, il metodo restituisce ErrorCode::UNSUPPORTED_PADDING_MODE .

Le operazioni con chiave privata ( KeyPurpose::SIGN ) richiedono l'autorizzazione di digest e riempimento, il che significa che le autorizzazioni della chiave devono contenere i valori specificati. In caso contrario, restituisce ErrorCode::INCOMPATIBLE_DIGEST . Le operazioni con chiave pubblica ( KeyPurpose::VERIFY ) sono consentite con digest o riempimento non autorizzati.

Chiavi AES

Le operazioni chiave AES specificano esattamente una modalità di blocco e una modalità di riempimento in inParams . Se uno dei due valori non è specificato o è specificato più di una volta, restituisce ErrorCode::UNSUPPORTED_BLOCK_MODE o ErrorCode::UNSUPPORTED_PADDING_MODE . Le modalità specificate devono essere autorizzate dalla chiave, altrimenti il ​​metodo restituisce ErrorCode::INCOMPATIBLE_BLOCK_MODE o ErrorCode::INCOMPATIBLE_PADDING_MODE .

Se la modalità di blocco è BlockMode::GCM , inParams specifica Tag::MAC_LENGTH e il valore specificato è un multiplo di 8 che non è maggiore di 128 o inferiore al valore di Tag::MIN_MAC_LENGTH nelle autorizzazioni della chiave. Per lunghezze MAC superiori a 128 o non multipli di 8, restituire ErrorCode::UNSUPPORTED_MAC_LENGTH . Per valori inferiori alla lunghezza minima della chiave, restituire ErrorCode::INVALID_MAC_LENGTH .

Se la modalità di blocco è BlockMode::GCM o BlockMode::CTR , la modalità di riempimento specificata deve essere PaddingMode::NONE . Per BlockMode::ECB o BlockMode::CBC , la modalità può essere PaddingMode::NONE o PaddingMode::PKCS7 . Se la modalità di riempimento non soddisfa queste condizioni, restituisce ErrorCode::INCOMPATIBLE_PADDING_MODE .

Se la modalità di blocco è BlockMode::CBC , BlockMode::CTR o BlockMode::GCM , è necessario un vettore di inizializzazione o un nonce. Nella maggior parte dei casi, i chiamanti non devono fornire un IV o un nonce. In tal caso, l'implementazione Keymaster genera un IV o nonce casuale e lo restituisce tramite Tag::NONCE in outParams . I CBC e CTR IV sono 16 byte. I nonce GCM sono 12 byte. Se le autorizzazioni della chiave contengono Tag::CALLER_NONCE , il chiamante può fornire un IV/nonce con Tag::NONCE in inParams . Se viene fornito un nonce quando Tag::CALLER_NONCE non è autorizzato, restituisce ErrorCode::CALLER_NONCE_PROHIBITED . Se non viene fornito un nonce quando Tag::CALLER_NONCE è autorizzato, genera un IV/nonce casuale.

Chiavi HMAC

Le operazioni chiave HMAC specificano Tag::MAC_LENGTH in inParams . Il valore specificato deve essere un multiplo di 8 che non sia maggiore della lunghezza del digest o minore del valore di Tag::MIN_MAC_LENGTH nelle autorizzazioni della chiave. Per lunghezze MAC superiori alla lunghezza del digest o non multipli di 8, restituire ErrorCode::UNSUPPORTED_MAC_LENGTH . Per valori inferiori alla lunghezza minima della chiave, restituire ErrorCode::INVALID_MAC_LENGTH .

aggiornamento

Versione : 1, 2, 3

Fornisce i dati da elaborare in un'operazione in corso iniziata con Begin . L'operazione è specificata dal parametro operationHandle .

Per fornire maggiore flessibilità per la gestione del buffer, le implementazioni di questo metodo hanno la possibilità di consumare meno dati di quelli forniti. Il chiamante è responsabile del loop per alimentare il resto dei dati nelle chiamate successive. La quantità di input consumato viene restituita nel parametro inputConsumed . Le implementazioni consumano sempre almeno un byte, a meno che l'operazione non possa accettarne di più; se vengono forniti più di zero byte e vengono consumati zero byte, i chiamanti considerano questo un errore e interrompono l'operazione.

Le implementazioni possono anche scegliere la quantità di dati da restituire, come risultato dell'aggiornamento. Ciò è rilevante solo per le operazioni di crittografia e decrittografia, poiché la firma e la verifica non restituiscono dati fino al termine . Restituisci i dati il ​​prima possibile, anziché memorizzarli nel buffer.

Gestione degli errori

Se questo metodo restituisce un codice di errore diverso da ErrorCode::OK , l'operazione viene interrotta e l'handle dell'operazione viene invalidato. Qualsiasi utilizzo futuro dell'handle, con questo metodo, finish o abort , restituisce ErrorCode::INVALID_OPERATION_HANDLE .

Esecuzione dell'autorizzazione

L'applicazione dell'autorizzazione chiave viene eseguita principalmente in Begin . L'unica eccezione è il caso in cui la chiave ha:

In questo caso, la chiave richiede un'autorizzazione per operazione e il metodo di aggiornamento riceve un Tag::AUTH_TOKEN nell'argomento inParams . HMAC verifica che il token sia valido e contenga un ID utente sicuro corrispondente, corrisponda al Tag::USER_AUTH_TYPE della chiave e contenga l'handle dell'operazione dell'operazione corrente nel campo di verifica. Se queste condizioni non sono soddisfatte, restituisci ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Il chiamante fornisce il token di autenticazione a ogni chiamata per aggiornarla e terminarla . L'implementazione deve convalidare il token solo una volta, se preferisce.

Chiavi RSA

Per le operazioni di firma e verifica con Digest::NONE , questo metodo accetta che l'intero blocco venga firmato o verificato in un unico aggiornamento. Potrebbe non consumare solo una parte del blocco. Tuttavia, se il chiamante sceglie di fornire i dati in più aggiornamenti, questo metodo li accetta. Se il chiamante fornisce più dati da firmare di quelli che possono essere utilizzati (la lunghezza dei dati supera la dimensione della chiave RSA), restituisce ErrorCode::INVALID_INPUT_LENGTH .

Chiavi ECDSA

Per le operazioni di firma e verifica con Digest::NONE , questo metodo accetta che l'intero blocco venga firmato o verificato in un unico aggiornamento. Questo metodo potrebbe non consumare solo una parte del blocco.

Tuttavia, se il chiamante sceglie di fornire i dati in più aggiornamenti, questo metodo li accetta. Se il chiamante fornisce più dati da firmare di quelli che possono essere utilizzati, i dati vengono troncati automaticamente. (Ciò differisce dalla gestione dei dati in eccesso forniti in operazioni RSA simili. La ragione di ciò è la compatibilità con i client legacy.)

Chiavi AES

La modalità AES GCM supporta i "dati di autenticazione associati", forniti tramite il tag Tag::ASSOCIATED_DATA nell'argomento inParams . I dati associati possono essere forniti in chiamate ripetute (importante se i dati sono troppo grandi per essere inviati in un unico blocco) ma precedono sempre i dati da crittografare o decrittografare. Una chiamata di aggiornamento può ricevere sia dati associati che dati da crittografare/decrittografare, ma gli aggiornamenti successivi potrebbero non includere dati associati. Se il chiamante fornisce dati associati a una chiamata di aggiornamento dopo una chiamata che include dati da crittografare/decrittografare, restituire ErrorCode::INVALID_TAG .

Per la crittografia GCM, il tag viene aggiunto al testo cifrato tramite finish . Durante la decrittografia, l'ultimo byte Tag::MAC_LENGTH dei dati forniti all'ultima chiamata di aggiornamento è il tag. Poiché una determinata invocazione di update non può sapere se è l'ultima invocazione, elabora tutto tranne la lunghezza del tag e memorizza nel buffer i possibili dati del tag durante finish .

fine

Versione : 1, 2, 3

Termina un'operazione in corso iniziata con Begin , elaborando tutti i dati non ancora elaborati forniti da update (s).

Questo metodo è l'ultimo chiamato in un'operazione, quindi tutti i dati elaborati vengono restituiti.

Sia che si completa correttamente o restituisce un errore, questo metodo finalizza l'operazione e quindi invalida la maniglia dell'operazione fornita. Qualsiasi uso futuro dell'impugnatura, con questo metodo o aggiornamento o abort , restituisce ErrorCode::INVALID_OPERATION_HANDLE .

Le operazioni di firma restituiscono la firma come output. Le operazioni di verifica accettano la firma nel parametro signature e non restituiscono alcun output.

Applicazione dell'autorizzazione

L'applicazione chiave dell'autorizzazione viene eseguita principalmente all'inizio . L'unica eccezione è il caso in cui la chiave ha:

In questo caso, la chiave richiede un'autorizzazione per operazione e il metodo di aggiornamento riceve un tag :: auth_token nell'argomento inParams . HMAC verifica che il token sia valido e contiene un ID utente sicuro corrispondente, corrisponda al tag del tasto :: user_auth_type e contiene la maniglia dell'operazione dell'operazione corrente nel campo della sfida. Se queste condizioni non sono soddisfatte, restituisce ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Il chiamante fornisce il token di autenticazione a ogni chiamata da aggiornare e finire . L'implementazione deve convalidare il token solo una volta se preferisce.

Tasti RSA

Alcuni requisiti aggiuntivi, a seconda della modalità di imbottitura:

  • PaddingMode::NONE . Per le operazioni di firma e crittografia non pagate, se i dati forniti sono più brevi della chiave, i dati vengono messi a dura prova a sinistra prima della firma/crittografia. Se i dati hanno la stessa lunghezza della chiave, ma numericamente più grande, restituisce ErrorCode::INVALID_ARGUMENT . Per le operazioni di verifica e decrittografia, i dati devono essere esattamente lunghi quanto la chiave. Altrimenti, restituisce ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . Per le operazioni di firma imbottite da PSS, il sale PSS è la dimensione del messaggio digest e generato casualmente. Il digest specificato con tag :: digest in inputParams on Begin è usato come algoritmo Digest PSS e come algoritmo Digest MGF1.
  • PaddingMode::RSA_OAEP . Il digest specificato con tag :: digest in inputParams On Begin è usato come algoritmo Digest OAEP e SHA1 è usato come algoritmo Digest MGF1.

Tasti ECDSA

Se i dati forniti per la firma o la verifica non pagati sono troppo lunghi, troncarli.

Tasti AES

Alcune condizioni aggiuntive, a seconda della modalità di blocco:

  • BlockMode::ECB o BlockMode::CBC . Se l'imbottigliamento è PaddingMode::NONE e la lunghezza dei dati non è un multiplo della dimensione del blocco AES, restituisce ErrorCode::INVALID_INPUT_LENGTH . Se l'imbottigliamento è PaddingMode::PKCS7 , imporre i dati per la specifica PKCS#7. Si noti che PKCS#7 consiglia di aggiungere un blocco di imbottitura aggiuntivo se i dati sono un multiplo della lunghezza del blocco.
  • BlockMode::GCM . Durante la crittografia, dopo aver elaborato tutto il testo in chiaro, calcola il tag ( tag :: mac_length bytes) e aggiungilo al testo cifrato restituito. Durante la decrittografia, elabora l'ultimo tag :: mac_length byte come tag. Se la verifica del tag non riesce, restituire ErrorCode::VERIFICATION_FAILED .

abortire

Versione : 1, 2, 3

Abortisce l'operazione in corso. Dopo la chiamata a Abort, restituisce ErrorCode::INVALID_OPERATION_HANDLE per qualsiasi uso successivo del manico dell'operazione fornito con aggiornamento , finitura o abort .

get_supported_algorithms

Versione : 1

Restituisce l'elenco di algoritmi supportati dall'implementazione hardware di Keymaster. Un'implementazione del software restituisce un elenco vuoto; Un'implementazione ibrida restituisce un elenco contenente solo gli algoritmi supportati dall'hardware.

Le implementazioni di Keymaster 1 supportano RSA, EC, AES e HMAC.

get_supported_block_modes

Versione : 1

Restituisce l'elenco delle modalità di blocco AES supportate dall'implementazione hardware di KeyMaster per un algoritmo e uno scopo specificato.

Per RSA, EC e HMAC, che non sono cifre di blocco, il metodo restituisce un elenco vuoto per tutti gli scopi validi. Gli scopi non validi dovrebbero causare il metodo a restituire ErrorCode::INVALID_PURPOSE .

Le implementazioni di KeyMaster 1 supportano la BCE, CBC, CTR e GCM per la crittografia e la decrittografia AES.

get_supported_padding_modes

Versione : 1

Restituisce l'elenco delle modalità di imbottitura supportate dall'implementazione hardware di Keymaster per un algoritmo e uno scopo specifici.

HMAC ed EC non hanno alcuna nozione di imbottitura, quindi il metodo restituisce un elenco vuoto per tutti gli scopi validi. Gli scopi non validi dovrebbero causare il metodo a restituire ErrorCode::INVALID_PURPOSE .

Per RSA, supporto alle implementazioni di Keymaster 1:

  • Crittografia, decrittazione, firma e verifica non pagati. Per la crittografia e la firma non imbottite, se il messaggio è più breve del modulo pubblico, le implementazioni devono recarsi a sinistra con zeri. Per decrittazione e verifica non pagata, la lunghezza dell'input deve corrispondere alla dimensione del modulo pubblico.
  • PKCS#1 V1.5 Crittografia e modalità di imbottitura della firma
  • PSS con una lunghezza minima del sale di 20
  • Oaep

Per gli AE nelle modalità BCE e CBC, le implementazioni di KeyMaster 1 non supportano imbottitura e PKCS#7-padding. Le modalità CTR e GCM non supportano solo imbottitura.

get_supported_digests

Versione : 1

Restituisce l'elenco delle modalità Digest supportate dall'implementazione hardware di Keymaster per un algoritmo e uno scopo specifici.

Nessuna modalità AES supporta o richiede digestione, quindi il metodo restituisce un elenco vuoto per scopi validi.

Le implementazioni di KeyMaster 1 possono implementare un sottoinsieme dei digest definiti. Le implementazioni forniscono SHA-256 e possono fornire MD5, SHA1, SHA-224, SHA-256, SHA384 e SHA512 (il set completo di digest definiti).

get_supported_import_formats

Versione : 1

Restituisce l'elenco dei formati di importazione supportati dall'implementazione hardware di keymaster di un algoritmo specificato.

Le implementazioni di KeyMaster 1 supportano il formato PKCS#8 (senza protezione da password) per l'importazione di coppie di tasti RSA ed EC e supportano l'importazione indatrice di eventi avversi e materiale chiave HMAC.

GET_SUPPORTED_EXPORT_FORMATS

Versione : 1

Restituisce l'elenco dei formati di esportazione supportati dall'implementazione hardware di keymaster di un algoritmo specificato.

Le implementazioni di KeyMaster1 supportano il formato X.509 per l'esportazione di chiavi pubbliche RSA ed EC. L'esportazione di chiavi private o chiavi asimmetriche non è supportata.

Funzioni storiche

Keymaster 0

Le seguenti funzioni appartengono alla definizione originale di KeyMaster 0. Erano presenti in keymaster 1 struct keymaster1_device_t. Tuttavia, in Keymaster 1.0 non sono stati implementati e i loro puntatori di funzione sono stati impostati su NULL.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Keymaster 1

Le seguenti funzioni appartengono alla definizione di KeyMaster 1, ma sono state rimosse in Keymaster 2, insieme alle funzioni di Keymaster 0 elencate sopra.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

Le seguenti funzioni appartengono alla definizione di Keymaster 2, ma sono state rimosse in Keymaster 3, insieme alle funzioni di Keymaster 1 elencate sopra.

  • configure