Funzioni Keymaster

Questa pagina fornisce dettagli per assistere gli utenti che implementano Keymaster Strati di astrazione hardware (HAL). Copre ogni funzione del e la versione Keymaster in cui è disponibile la funzione. descrive l'implementazione predefinita. Per i tag, consulta Pagina Tag Keymaster.

Linee guida generali di implementazione

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

Parametri del puntatore di input

Versione: 1, 2

I parametri di puntatore di input che non vengono utilizzati per una determinata chiamata possono essere NULL. Il chiamante non deve necessariamente fornire dei segnaposto. Ad esempio, alcuni tipi e modalità di chiavi potrebbero non utilizzare alcun valore inParams per begin, quindi il chiamante potrebbe imposta inParams su NULL o fornisci un parametro vuoto per iniziare. I chiamanti possono anche fornire parametri inutilizzati e i metodi Keymaster non generare errori.

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

A partire da Keymaster 3, non ci sono parametri puntatore. Tutti i parametri vengono passati dai riferimenti value o const.

Parametri del puntatore di output

Versione: 1, 2

Simili ai parametri del puntatore di input, i parametri inutilizzati del puntatore di output potrebbe essere NULL. Se un metodo deve restituire dati in un output risulta essere NULL, deve essere restituito ErrorCode::OUTPUT_PARAMETER_NULL.

A partire da Keymaster 3, non ci sono parametri puntatore. Tutti i parametri vengono passati dai riferimenti value o const.

Uso improprio delle API

Versione: 1, 2, 3

Esistono molti modi in cui i chiamanti possono effettuare richieste senza senso o sono sciocchi ma non tecnicamente sbagliati. Le implementazioni Keymaster non sono in caso di esito negativo o di fornire una diagnostica. L'uso di tasti troppo piccoli specifica di parametri di input irrilevanti, riutilizzo di IV o nonce, chiave senza scopo (quindi inutile) e simili non dovrebbero essere diagnosticati dalle implementazioni. Omissione dei parametri obbligatori, specifica del parametri obbligatori non validi ed errori simili devono essere diagnosticati.

È responsabilità delle app, del framework e dell'archivio chiavi Android per assicurare che le chiamate ai moduli Keymaster siano sensate e utili.

Funzioni

getHardwareFeatures

Versione: 3

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

  • isSecure è true se le chiavi sono archiviate in hardware protetto (TEE ecc.) e non abbandonarlo mai.
  • supportsEllipticCurve è true se supporta la crittografia basata su curve ellittiche 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 supporta la generazione di certificati di attestazione della chiave pubblica Keymaster, 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 indica una mancata comunicazione con l'hardware protetto. 

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

configura

Versione: 2

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

Configura keymaster. Questo metodo viene chiamato una volta dopo l'apertura del dispositivo e prima di utilizzarlo. È utilizzato per fornire KM_TAG_OS_VERSION e Da KM_TAG_OS_PATCHLEVEL a keymaster. Finché non viene chiamato questo metodo, tutti gli altri metodi restituiscono KM_ERROR_KEYMASTER_NOT_CONFIGURED. I valori forniti da questo sono accettati dal keymaster soltanto una volta per avvio. Successiva le chiamate restituiscono KM_ERROR_OK, ma non eseguono alcuna operazione.

Se l'implementazione keymaster è su hardware sicuro e la versione del sistema operativo e i valori a livello di patch forniti non corrispondono a quelli forniti alla hardware dal bootloader (o se il bootloader non ha fornito valori), questo metodo restituisce KM_ERROR_INVALID_ARGUMENT e tutti gli altri che continuano a restituire KM_ERROR_KEYMASTER_NOT_CONFIGURED.

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

Entropia AddRng

Versione: 1, 2, 3

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

Aggiunge l'entropia fornita dal chiamante al pool utilizzato dall'implementazione di Keymaster 1 per generare numeri casuali, chiavi, IV e così via.

Le implementazioni Keymaster devono combinare in modo sicuro all'interno del pool, che a sua volta deve contenere generata internamente da un generatore di numeri casuali hardware. Il mix deve essere gestito in modo che un aggressore che abbia il controllo completo dei bit forniti da addRngEntropy o di quelli generati dall'hardware ma non entrambi, non ha alcun vantaggio non trascurabile nel prevedere i bit generate dal pool di entropia.

Implementazioni Keymaster che tentano di stimare l'entropia nei loro il pool interno presuppone che i dati forniti addRngEntropy non contiene entropia. Le implementazioni Keymaster possono restituisce ErrorCode::INVALID_INPUT_LENGTH se vengono forniti più di 2 KiB di dati in una singola chiamata.

generaChiave

Versione: 1, 2, 3

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

Genera una nuova chiave di crittografia, specificando le autorizzazioni associate, associati in modo permanente alla chiave. Le implementazioni Keymaster impossibile utilizzare una chiave in qualsiasi modo non coerente con le autorizzazioni specificato al momento della generazione. Per quanto riguarda le autorizzazioni hardware non può essere applicato, l'obbligo dell'hardware protetto è limitato garantendo che le autorizzazioni non azionabili associate alla chiave essere modificato, in modo che ogni chiamata getKeyCharacteristics restituisce il valore originale. Inoltre, le caratteristiche restituite generateKey alloca correttamente le autorizzazioni tra basate su hardware e software. Consulta getKeyFeatureistics per ulteriori dettagli.

I parametri forniti a generateKey dipendono dal tipo di chiave vengono generati. Questa sezione riepiloga i tag necessari e facoltativi per ogni tipo di chiave. Tag::ALGORITMO è sempre necessario 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. Valori consigliati sono tutte dimensioni della chiave che sono un multiplo 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 i valori primi fino a 2^64.

I seguenti parametri non sono necessari per generare una chiave RSA, ma se crei una chiave RSA senza di essi, ne viene generata una inutilizzabile. Tuttavia, La funzione generateKey non restituisce un errore se questi parametri vengono omessi.

  • Tag::PURPOSE specifica scopi consentiti. Tutte le finalità devono essere supportate per le chiavi RSA, in qualsiasi combinazione.
  • Tag::DIGEST specifica algoritmi digest che possono essere usati con la nuova chiave. Implementazioni che non supportano tutti gli algoritmi digest devono accettare la generazione di chiavi che includono sintesi non supportate. Le sintesi non supportate devono essere collocata nella categoria "applicata dal software" nelle caratteristiche chiave restituite. Questo perché la chiave può essere usata con gli altri digest, ma la digestione è eseguita nel software. Quindi viene chiamato l'hardware per eseguire l'operazione con Digest::NONE.
  • Tag::PADDING specifica la modalità di spaziatura interna utilizzabili con la nuova chiave. Implementazioni che non supportano tutti gli algoritmi digest, devono inserire PaddingMode::RSA_PSS e PaddingMode::RSA_OAEP pollici l'elenco delle caratteristiche principali applicate dal software, se non supportate vengono specificati algoritmi digest.

Chiavi ECDSA

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

Tag::DIGEST è necessaria anche per un'utile chiave ECDSA, ma non sono necessari per la generazione.

Chiavi AES

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

I seguenti parametri sono particolarmente rilevanti per le chiavi AES, ma non necessarie per generarne uno:

  • Tag::BLOCK_MODE specifica le modalità di blocco con cui può essere utilizzata la nuova chiave.
  • Tag::PADDING specifica le possibili modalità di spaziatura interna in uso. Questo vale solo per le modalità ECB e CBC.

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

Chiavi HMAC

Per la generazione di chiavi HMAC sono necessari i seguenti parametri:

  • Tag::KEY_SIZE specifica la dimensione della chiave in bit. Valori inferiori a 64 e i valori che non sono multipli di 8 non sono supportati. Tutti sono supportati multipli di 8, da 64 a 512. I valori più alti possono essere: supportati.
  • Tag::MIN_MAC_LENGTH specifica la lunghezza minima 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. Esattamente viene specificato un digest, altrimenti restituisce ErrorCode::UNSUPPORTED_DIGEST. Se il digest non è supportato dal trustlet, restituisce ErrorCode::UNSUPPORTED_DIGEST.

Caratteristiche principali

Se l'argomento delle caratteristiche è non-NULL, generateKey restituisce le caratteristiche della chiave appena generata, separate correttamente in basate su hardware e software. Consulta getKeyCharacteristics per una descrizione delle caratteristiche da inserire in un elenco. Le caratteristiche restituite includere tutti i parametri specificati per la generazione delle chiavi, tranne Tag::APPLICATION_ID e Tag::APPLICATION_DATA. Se questi tag sono stati inclusi nei parametri chiave, vengono rimossi da le caratteristiche restituite in modo che non sia possibile trovarne i valori esaminando il blob della chiave restituito. Tuttavia, sono legati crittograficamente al blob della chiave, in modo che se non vengono forniti i valori corretti quando la chiave non va a buon fine, l'utilizzo non riesce. Analogamente, Tag::ROOT_OF_TRUST è crittograficamente associato alla chiave, ma potrebbe non essere specificata creazione o importazione della chiave e non viene mai restituita.

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

Tag::ROLLBACK_RESISTANT

Resistenza al rollback

Resistenza al rollback significa che, quando una chiave viene eliminata deleteKey o deleteAllKeys, sono garantiti da hardware sicuro non sarà mai più utilizzabile. Implementazioni tipicamente senza resistenza al rollback restituire al chiamante il materiale della chiave generato o importato sotto forma di blob di chiavi, formato criptato e autenticato. Quando l'archivio chiavi elimina il blob della chiave, la chiave viene ma un aggressore che in precedenza è riuscito a recuperare il materiale della chiave potrebbe potenzialmente ripristinarlo sul dispositivo.

Una chiave è resistente al rollback se l'hardware sicuro garantisce che l'eliminazione non possono essere ripristinate in un secondo momento. Questo di solito viene fatto memorizzando le chiavi metadati in un luogo attendibile che non può essere manipolato da un utente malintenzionato. Attivato dispositivi mobili, il meccanismo usato solitamente è Replay Protected Memory Blocchi (RPMB). Poiché il numero di chiavi che possono essere create è essenzialmente illimitato e lo spazio di archiviazione affidabile utilizzato per la resistenza al rollback potrebbe essere limitato di dimensioni, questo metodo deve avere successo anche in caso di resistenza al rollback non può essere fornito per la nuova chiave. In questo caso, Tag::ROLLBACK_RESISTANT alle caratteristiche principali.

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, suddivisi in due insiemi: basata sull'hardware e basata sul software. La descrizione qui si applica anche agli elenchi di caratteristiche chiave restituiti da generateKey e importKey.

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

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

La regola generale per decidere se un determinato tag appartiene al con forzatamente hardware o software si intende che se il significato del tag è completamente garantito da un hardware sicuro. Altrimenti, l'applicazione forzata del software. Di seguito è riportato un elenco di tag specifici la cui allocazione corretta potrebbero non essere chiare:

  • Tag::ALGORITMO, Tag::KEY_SIZE, e Tag::RSA_PUBLIC_EXPONENT sono proprietà intrinseche della chiave. Per le chiavi protette dall'hardware, questi tag verranno inseriti nell'elenco delle applicazioni applicate all'hardware.
  • Valori Tag::DIGEST supportate dall'hardware sicuro, dell'hardware. Le sintesi non supportate vengono inserite nell'elenco dei software supportati.
  • Tag::PADDING valori vengono generalmente inseriti nell'elenco dei supporti hardware, a meno che non esista un possibilità che una specifica modalità di spaziatura interna debba essere eseguita da software. In questo caso, vengono inseriti nell'elenco delle applicazioni forzate dal software. Una tale possibilità riguarda le chiavi RSA che consentono il riempimento PSS o OAEP con algoritmi digest non supportate dall'hardware protetto.
  • Tag::USER_SECURE_ID e Tag::USER_AUTH_TYPE vengono applicate tramite hardware solo se l'autenticazione utente è applicata in modo forzato. A ottenere questo risultato, il trustlet Keymaster e il modello di il trustlet deve essere sicuro e condividere una chiave HMAC segreta usata per firmare e convalidare i token di autenticazione. Consulta le Autenticazione per maggiori dettagli.
  • Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME, e Tag::USAGE_EXPIRE_DATETIME richiedono l'accesso a un orologio da parete verificabile correttamente. Hardware più sicuro ha accesso solo alle informazioni sull'ora fornite dal sistema operativo non sicuro, che significa che i tag sono applicati a livello software.
  • Tag::ORIGIN è sempre nell'elenco hardware per le chiavi associate all'hardware. La sua presenza in quel è il modo in cui i livelli più alti determinano che una chiave è supportata da hardware.

importKey

Versione: 1, 2, 3

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

Importa il materiale della chiave nell'hardware Keymaster. Parametri di definizione chiave e le caratteristiche dell'output vengono gestite come per generateKey, con le seguenti eccezioni:

  • Tag::KEY_SIZE e Tag::RSA_PUBLIC_EXPONENT (solo per le chiavi RSA) non sono necessarie nei parametri di input. Se non viene specificato, il trustlet deduce i valori dal materiale della chiave fornito e aggiunge i tag e i valori appropriati alle caratteristiche principali. Se i parametri sono fornito, il trustlet le convalida in base al materiale della chiave. Nella in caso di mancata corrispondenza, il metodo restituisce ErrorCode::IMPORT_PARAMETER_MISMATCH.
  • Il valore Tag::ORIGIN restituito ha i valori lo stesso valore di KeyOrigin::IMPORTED.

EsportazioneChiave

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 durante la generazione della chiave è stato fornito Tag::APPLICATION_ID , lo stesso valore viene fornito a questo metodo nella clientId argomento. In caso contrario, il metodo restituisce ErrorCode::INVALID_KEY_BLOB. Analogamente, se Tag::APPLICATION_DATA durante la generazione o l'importazione, lo stesso valore viene fornito 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 è implementate da moduli Keymaster che offrono 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 da moduli Keymaster che offrono resistenza al rollback.

DELETEAttestationIds

Versione: 3

Il metodo destroyAttestationIds() viene utilizzato per creare disattiva il nuovo (facoltativo, ma vivamente consigliato) Attestazione ID funzionalità. Se il TEE non ha modo di garantire che l'attestazione dell'ID sia permanente disattivata dopo la chiamata di questo metodo, l'attestazione dell'ID non deve essere del tutto implementato, nel qual caso questo metodo non fa nulla e restituisce ErrorCode::UNIMPLEMENTED. Se l'attestazione dell'ID è supportato, questo metodo deve essere implementato e deve essere disattivato definitivamente per tutti i futuri tentativi di attestazione dell'ID. Il metodo può essere chiamato volte. Se l'attestazione dell'ID è già disattivata definitivamente, il metodo zero e restituisce ErrorCode::OK.

Gli unici codici di errore che questo metodo può restituire sono ErrorCode::UNIMPLEMENTED (se l'attestazione dell'ID non è supportata), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED o uno dei codici di errore che indica la mancata comunicazione con il responsabile hardware.

inizia

Versione: 1, 2, 3

Avvia un'operazione crittografica, utilizzando la chiave specificata, per l'oggetto dello scopo, 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 utilizzata anche come "sfida" il token di sicurezza nelle operazioni autenticate e, operazioni è incluso nel campo challenge della token di autenticazione.

Un'implementazione Keymaster supporta almeno 16 elementi simultanei operazioni. L'archivio chiavi ne utilizza fino a 15, lasciandone uno per vold da usare per la password la crittografia. Quando sono in corso 15 operazioni nell'archivio chiavi (begin è è stato chiamato, ma finish o abort non sono stati ancora chiamato) e riceve una richiesta di inizio del sedicesimo, chiama abort sull'operazione utilizzata meno di recente per ridurre il numero di operazioni attive alla 14 prima di chiamare begin per avviare il dell'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 quelle tag con i valori originariamente specificati nell'argomento inParams in questo metodo.

Applicazione dell'autorizzazione

Durante questo metodo, le seguenti autorizzazioni chiave vengono applicate trustlet se l'implementazione li ha inseriti nella categoria e se l'operazione non è di chiave pubblica. Chiave pubblica operazioni, ovvero KeyPurpose::ENCRYPT e KeyPurpose::VERIFY, con chiavi RSA o EC, possano avere esito positivo anche se i non sono soddisfatti.

  • Tag::SCOPO: lo scopo specificato nella chiamata begin() deve corrispondere a uno degli scopi nelle autorizzazioni della chiave, a meno che l'operazione richiesta non sia una chiave pubblica operativa. Se lo scopo specificato non corrisponde e l'operazione non viene un'operazione con chiave pubblica, begin restituirà ErrorCode::UNSUPPORTED_PURPOSE. Le operazioni con le chiavi pubbliche la crittografia asimmetrica o le operazioni di verifica.
  • Tag::ACTIVE_DATETIME possono essere applicate in modo forzato 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.
  • Tag::ORIGINATION_EXPIRE_DATETIME possono essere applicate in modo forzato 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 possono essere applicate in modo forzato 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 la 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 le descrizione del tag per importanti dettagli sull'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, l'errore restituisce ErrorCode::KEY_MAX_OPS_EXCEEDED.
  • Tag::USER_SECURE_ID viene applicata con questo metodo solo se anche la chiave ha Tag::AUTH_TIMEOUT. Se nella chiave sono presenti entrambi, questo metodo deve ricevere una Tag::AUTH_TOKEN in inParams. Affinché il token di autenticazione sia valido, tutti i seguenti elementi deve essere vero:
    • Il campo HMAC viene convalidato correttamente.
    • Almeno uno dei Tag::USER_SECURE_ID della chiave corrisponda ad almeno uno dei valori ID sicuro nella di accesso.
    • La chiave ha un valore Tag::USER_AUTH_TYPE che corrisponde al tipo di autenticazione nel token.

    Se una 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 per questo metodo, Viene restituito ErrorCode::CALLER_NONCE_PROHIBITED.
  • Tag::BOOTLOADER_ONLY specifica che solo il bootloader può utilizzare la chiave. Se questo metodo è chiamata con una chiave solo bootloader al termine dell'esecuzione del bootloader, restituisce ErrorCode::INVALID_KEY_BLOB.

Chiavi RSA

Tutte le operazioni relative alle chiavi RSA specificano esattamente una modalità di spaziatura interna 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 richiedono una sintesi, così come la crittografia RSA e le operazioni di decrittografia con la modalità di spaziatura interna 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.

Operazioni con le chiavi private (KeyPurpose::DECYPT e KeyPurpose::SIGN) necessitano dell'autorizzazione di digest e padding, il che significa che le autorizzazioni chiave devono contenere i valori specificati. In caso contrario, il metodo restituisce ErrorCode::INCOMPATIBLE_DIGEST o ErrorCode::INCOMPATIBLE_PADDING, a seconda dei casi. Operazioni sulle chiavi pubbliche (KeyPurpose::ENCRYPT e KeyPurpose::VERIFY) sono consentiti con digest o spaziatura interna non autorizzati.

Ad eccezione di PaddingMode::NONE, tutte le modalità di spaziatura interna RSA sono applicabile solo a determinate finalità. In particolare, 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 decriptazione. Il metodo restituisce ErrorCode::UNSUPPORTED_PADDING_MODE se il valore la modalità specificata non supporta lo scopo specificato.

Esistono alcune interazioni importanti tra le modalità di spaziatura interna e le sintesi:

  • PaddingMode::NONE indica che un valore "non elaborato" L'operazione RSA è in esecuzione. Se firmi o verifichi la verifica, Digest::NONE specificato per il digest. Non è necessario un digest per la crittografia senza padding la decrittografia.
  • La spaziatura interna PaddingMode::RSA_PKCS1_1_5_SIGN richiede un digest. La digest può essere Digest::NONE, nel qual caso Keymaster dell'implementazione 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 è fornito, mentre PS è la stringa di spaziatura interna. Le dimensioni della chiave RSA devono essere almeno 11 byte più grande del messaggio, altrimenti il metodo restituisce ErrorCode::INVALID_INPUT_LENGTH.
  • La spaziatura interna PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT non richiede un digest.
  • La spaziatura interna PaddingMode::RSA_PSS richiede un digest, che potrebbe non essere Digest::NONE. Se Digest::NONE è specificato, il valore restituisce ErrorCode::INCOMPATIBLE_DIGEST. Inoltre, la dimensione della chiave RSA deve essere almeno 2 + D byte più grandi dell'output la dimensione del digest, dove D è la dimensione del digest, in byte. Altrimenti Il metodo restituisce ErrorCode::INCOMPATIBLE_DIGEST. Dimensione del sale è D.
  • La spaziatura interna PaddingMode::RSA_OAEP richiede un digest, che potrebbe non essere Digest::NONE. Se Digest::NONE è specificato, il valore restituisce ErrorCode::INCOMPATIBLE_DIGEST.

Chiavi EC

Le operazioni con i tasti EC specificano esattamente una modalità di spaziatura interna in inParams. Se non specificato o specificato più di una volta, il metodo restituisce ErrorCode::UNSUPPORTED_PADDING_MODE.

Le operazioni con le chiavi private (KeyPurpose::SIGN) richiedono l'autorizzazione di digest e spaziatura interna, il che significa che le autorizzazioni devono contenere i valori specificati. In caso contrario, restituisci ErrorCode::INCOMPATIBLE_DIGEST. Operazioni sulle chiavi pubbliche (KeyPurpose::VERIFY) sono consentiti con digest o spaziatura interna non autorizzate.

Chiavi AES

Le operazioni con i tasti AES specificano esattamente una modalità di blocco e una modalità di spaziatura interna a inParams. Se uno dei due valori non è specificato o è specificato più più di una volta, restituisci ErrorCode::UNSUPPORTED_BLOCK_MODE oppure ErrorCode::UNSUPPORTED_PADDING_MODE. Le modalità specificate devono essere autorizzato 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, il valore specificato è un multiplo di 8 non maggiore di 128 o inferiore al valore di Tag::MIN_MAC_LENGTH nel le autorizzazioni delle chiavi. Per lunghezze MAC superiori a 128 o non multipli di 8, restituisci ErrorCode::UNSUPPORTED_MAC_LENGTH. Per valori inferiori della lunghezza minima della chiave, restituisce ErrorCode::INVALID_MAC_LENGTH.

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

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

Chiavi HMAC

Le operazioni con le chiavi HMAC specificano Tag::MAC_LENGTH in inParams. Il valore specificato deve essere un multiplo di 8 non maggiore del lunghezza digest o inferiore al valore di Tag::MIN_MAC_LENGTH nelle autorizzazioni della chiave. Per lunghezze MAC superiori alla lunghezza del digest o non multipli di 8, restituisce ErrorCode::UNSUPPORTED_MAC_LENGTH. Per i valori inferiori alla lunghezza minima della chiave, restituisce ErrorCode::INVALID_MAC_LENGTH.

update

Versione: 1, 2, 3

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

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

Le implementazioni possono anche scegliere la quantità di dati da restituire, come risultato aggiornamento. Ciò è pertinente solo per le operazioni di crittografia e decriptazione, le firme 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 non è più valido. Qualsiasi un uso futuro dell'handle, con questo metodo, finire o interrompere, restituisce ErrorCode::INVALID_OPERATION_HANDLE.

Applicazione dell'autorizzazione

L'applicazione forzata dell'autorizzazione delle chiavi viene eseguita principalmente in begin. L'unica eccezione è il caso in cui la chiave abbia:

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

Il chiamante fornisce il token di autenticazione a ogni chiamata per aggiornare finisci. L'implementazione deve convalidare il token solo una volta, se preferisci.

Chiavi RSA

Per le operazioni di firma e verifica con Digest::NONE, questo metodo accetta la firma o la verifica dell'intero blocco in un'unica aggiornamento. Non può 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 quanti ne è possibile utilizzare (lunghezza superano le dimensioni della chiave RSA), restituiscono ErrorCode::INVALID_INPUT_LENGTH.

Chiavi ECDSA

Per le operazioni di firma e verifica con Digest::NONE, questo metodo accetta la firma o la verifica dell'intero blocco in un'unica aggiornamento. Questo metodo non può consumare solo una parte del blocco.

Tuttavia, se il chiamante sceglie di fornire i dati in più aggiornamenti, questo metodo lo accetta. Se il chiamante fornisce più dati per firmare di quello che è possibile utilizzare, i dati vengono troncati automaticamente. (Ciò differisce dal dei dati in eccesso forniti in operazioni RSA simili. Il motivo è la compatibilità con i client legacy).

Chiavi AES

La modalità AES-GCM supporta i "dati di autenticazione associati", forniti tramite Tag::ASSOCIATED_DATA nell'argomento inParams. I dati associati potrebbero essere forniti in chiamate ripetute (importante se i dati sono troppo grandi per essere inviati in un solo blocco), ma sono sempre precedenti ai dati essere criptati o decriptati. Una chiamata di aggiornamento può ricevere entrambi i dati associati e i dati da criptare/decriptare, ma gli aggiornamenti successivi potrebbero non includere e i dati di Google Cloud. Se il chiamante fornisce i dati associati a una chiamata di aggiornamento al termine di una chiamata che include dati da criptare/decriptare, restituire ErrorCode::INVALID_TAG.

Per la crittografia GCM, il tag viene aggiunto al testo crittografato da finire. Durante la decrittografia, l'ultima Tag::MAC_LENGTH byte dei dati forniti all'ultimo aggiornamento è il tag. Poiché una determinata chiamata update non può sapere se si tratta dell'ultima chiamata, elabora tutti i tag tranne la lunghezza e memorizza nel buffer i possibili dati di tag alla fine.

fine

Versione: 1, 2, 3

Completa un'operazione in corso iniziata con begin di tutti i dati non ancora elaborati forniti aggiornamenti.

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

Se viene completato correttamente o restituisce un errore, questo metodo finalizza dell'operazione e, di conseguenza, invalida l'handle dell'operazione fornito. Qualsiasi utilizzo futuro dell'handle, con questo metodo o update oppure abort, restituisce ErrorCode::INVALID_OPERATION_HANDLE.

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

Applicazione dell'autorizzazione

L'applicazione forzata dell'autorizzazione delle chiavi viene eseguita principalmente inizia. L'unica eccezione è il caso in cui la chiave abbia:

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

Il chiamante fornisce il token di autenticazione a ogni chiamata a update e finish. L'implementazione deve convalidare il token solo una volta, se preferisci.

Chiavi RSA

Di seguito sono riportati alcuni requisiti aggiuntivi, a seconda della modalità di spaziatura interna:

  • PaddingMode::NONE. Per le operazioni di firma e crittografia senza padding, Se i dati forniti sono più corti della chiave, i dati hanno il riempimento pari a zero a sinistra prima di eseguire la firma/crittografia. Se i dati sono della stessa lunghezza della chiave, ma numericamente più grande, restituisce ErrorCode::INVALID_ARGUMENT. Per operazioni di verifica e decriptazione, i dati devono essere lunghi come chiave. Altrimenti, restituisci ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS. Per le operazioni di firma con riempitivo PSS, il sale PSS è la dimensione del digest del messaggio e generato in modo casuale. Il digest specificato con Tag::DIGEST in inputParams su begin viene utilizzato come digest PSS e l'algoritmo digest MGF1.
  • PaddingMode::RSA_OAEP. Il digest specificato con Tag::DIGEST in inputParams di begin viene utilizzato come OAEP algoritmo digest e SHA1 è utilizzato come algoritmo digest MGF1.

Chiavi ECDSA

Se i dati forniti per la firma o la verifica senza padding sono troppo lunghi, troncali li annotino.

Chiavi AES

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

  • BlockMode::ECB o BlockMode::CBC. Se la spaziatura interna è PaddingMode::NONE e il valore la lunghezza dei dati non è un multiplo della dimensione del blocco AES, ErrorCode::INVALID_INPUT_LENGTH. Se la spaziatura interna è PaddingMode::PKCS7, inserisci i dati in base alla specifica PKCS#7. Tieni presente che PKCS#7 consiglia di aggiungere un ulteriore blocco di spaziatura interna se i dati sono un multiplo della lunghezza del blocco.
  • BlockMode::GCM. Durante la crittografia, dopo l'elaborazione testo non crittografato, calcola il tag (Tag::MAC_LENGTH byte) e la aggiungerai al testo crittografato restituito. Durante la decrittografia, elabora l'ultimo Tag::MAC_LENGTH byte come tag. Se la verifica del tag non va a buon fine, restituisci ErrorCode::VERIFICATION_FAILED.

interrompi

Versione: 1, 2, 3

Interrompe l'operazione in corso. Al termine della chiamata, torna indietro ErrorCode::INVALID_OPERATION_HANDLE per qualsiasi utilizzo successivo dell'handle dell'operazione fornito con update, terminare o interrompere.

algoritmi_supportati

Versione: 1

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

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

modalità_di_blocco_supportate

Versione: 1

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

Per RSA, EC e HMAC, che non sono crittografie a blocchi, il metodo restituisce un vuoto per tutti gli scopi validi. Per motivi non validi, il metodo non dovrebbe restituisce ErrorCode::INVALID_PURPOSE.

Le implementazioni Keymaster 1 supportano ECB, CBC, CTR e GCM per AES la crittografia e la decrittografia.

modalità_porto_spaziatura_supportata

Versione: 1

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

HMAC ed EC non hanno la nozione di spaziatura interna, quindi il metodo restituisce un elenco vuoto per tutti gli scopi validi. Gli scopi non validi devono causare la restituzione del metodo ErrorCode::INVALID_PURPOSE.

Per gli RSA, le implementazioni Keymaster 1 supportano:

  • Crittografia, decrittografia, firma e verifica senza riempimenti. Non imbottiti la crittografia e la firma, se il messaggio è più breve del modulo pubblico, le implementazioni devono contenere degli zeri. Per la decrittografia senza padding la lunghezza dell'input deve corrispondere alle dimensioni del modulo pubblico.
  • Modalità di crittografia e spaziatura interna della firma PKCS#1 v1.5
  • PSS con una lunghezza minima di sale di 20
  • OAEP

Per AES in modalità ECB e CBC, le implementazioni Keymaster 1 non supportano e PKCS#7. Le modalità CTR e GCM non supportano solo la spaziatura interna.

digest_supportato

Versione: 1

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

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

Le implementazioni Keymaster 1 possono implementare un sottoinsieme delle digest. Le implementazioni forniscono SHA-256 e possono fornire MD5, SHA1, SHA-224, SHA-256, SHA384 e SHA512 (l'insieme completo dei digest definiti).

formati_importazione_supportati

Versione: 1

Restituisce l'elenco dei formati di importazione supportati dall'hardware Keymaster di un determinato algoritmo.

Le implementazioni Keymaster 1 supportano il formato PKCS#8 (senza password (protezione) per l'importazione di coppie di chiavi RSA ed EC e supporta l'importazione RAW Materiale delle chiavi AES e HMAC.

formati_esportazione_supportati

Versione: 1

Restituisce l'elenco dei formati di esportazione supportati dall'hardware Keymaster di un determinato algoritmo.

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

Funzioni storiche

Keymaster 0

Le seguenti funzioni appartengono alla definizione originale di Keymaster 0. Loro nello struct Keymaster 1 keymaster1_device_t. Tuttavia, in Keymaster 1.0 non erano implementati e i loro puntatori di funzione erano 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 erano rimosso in Keymaster 2, insieme alle funzioni 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 erano rimosso in Keymaster 3, insieme alle funzioni di Keymaster 1 elencate sopra.

  • configure