keymaster2_device Strukturreferenz

Bricht eine mit begin() begonnene kryptografische Operation ab, gibt alle internen Ressourcen frei und macht operation_handle ungültig.

Definition in Zeile 415 der Datei keymaster2.h .

Fügt dem von Keymaster verwendeten RNG Entropie hinzu. Die durch diese Methode hinzugefügte Entropie ist garantiert nicht die einzige verwendete Entropiequelle, und die Mischfunktion muss sicher sein, in dem Sinne, dass der Angreifer nicht vorhersagen kann (oder Kontrolle), dann ist die RNG-Ausgabe nicht von zufällig zu unterscheiden. Wenn also die Entropie von irgendeiner Quelle gut ist, wird die Ausgabe gut sein.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	Daten	Zufallsdaten zum Einmischen.
[in]	Datenlänge	Länge der data .

Definition in Zeile 74 der Datei keymaster2.h .

Generiert eine signierte X.509-Zertifikatskette, die das Vorhandensein von key_to_attest in keymaster bestätigt (TODO(swillden): Zertifikatsinhalt genauer beschreiben). Das Zertifikat enthält eine Erweiterung mit OID 1.3.6.1.4.1.11129.2.1.17 und einem in <TODO:swillden – Insert link here> definierten Wert, der die Schlüsselbeschreibung enthält.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	key_to_attest	Der Schlüsselhauptschlüssel, für den das Beglaubigungszertifikat generiert wird.
[in]	attest_params	Parameter, die definieren, wie die Beglaubigung durchgeführt wird. Derzeit ist der einzige Parameter KM_TAG_ALGORITHM, der entweder KM_ALGORITHM_EC oder KM_ALGORITHM_RSA sein muss. Dadurch wird ausgewählt, welcher der bereitgestellten Beglaubigungsschlüssel zum Signieren des Zertifikats verwendet wird.
[aus]	cert_chain	Ein Array von DER-codierten X.509-Zertifikaten. Das erste ist das Zertifikat für key_to_attest . Die verbleibenden Einträge werden mit der Wurzel zurückverkettet. Der Aufrufer übernimmt den Besitz und muss die Zuordnung mit keymaster_free_cert_chain aufheben.

Definition in Zeile 239 der Datei keymaster2.h .

Startet einen kryptografischen Vorgang mit dem angegebenen Schlüssel. Wenn alles in Ordnung ist, gibt begin() KM_ERROR_OK zurück und erstellt ein Operationshandle, das an nachfolgende Aufrufe von update() , finish() oder abort() übergeben werden muss.

Es ist wichtig, dass jeder Aufruf von begin() mit einem nachfolgenden Aufruf von finish() oder abort() gepaart wird, damit die Keymaster-Implementierung alle internen Betriebszustände bereinigen kann. Wenn Sie dies nicht tun, kann interner Zustandsraum oder andere interne Ressourcen verloren gehen und kann schließlich dazu führen, dass begin() KM_ERROR_TOO_MANY_OPERATIONS zurückgibt, wenn es keinen Platz mehr für Operationen hat. Jedes andere Ergebnis als KM_ERROR_OK von begin() , update() oder finish() bricht die Operation implizit ab, in diesem Fall muss abort() nicht aufgerufen werden (und gibt KM_ERROR_INVALID_OPERATION_HANDLE zurück, wenn es aufgerufen wird).

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	Zweck	Der Zweck der Operation, entweder KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN oder KM_PURPOSE_VERIFY. Beachten Sie, dass für AEAD-Modi Verschlüsselung und Entschlüsselung Signieren bzw. Verifizieren implizieren, aber als KM_PURPOSE_ENCRYPT und KM_PURPOSE_DECRYPT angegeben werden sollten.
[in]	Schlüssel	Der Schlüssel, der für den Vorgang verwendet werden soll. key muss einen Zweck haben, der mit dem purpose kompatibel ist, und alle seine Verwendungsanforderungen müssen erfüllt sein, oder begin() gibt einen entsprechenden Fehlercode zurück.
[in]	in_params	Zusätzliche Parameter für die Operation. Dies wird normalerweise verwendet, um Authentifizierungsdaten mit KM_TAG_AUTH_TOKEN bereitzustellen. Wenn KM_TAG_APPLICATION_ID oder KM_TAG_APPLICATION_DATA während der Generierung bereitgestellt wurden, müssen sie hier bereitgestellt werden, oder der Vorgang schlägt mit KM_ERROR_INVALID_KEY_BLOB fehl. Für Operationen, die eine Nonce oder IV erfordern, kann in_params auf Schlüsseln, die mit KM_TAG_CALLER_NONCE generiert wurden, ein Tag KM_TAG_NONCE enthalten.
[aus]	out_params	Ausgangsparameter. Wird verwendet, um zusätzliche Daten aus der Operationsinitialisierung zurückzugeben, insbesondere um die IV oder Nonce von Operationen zurückzugeben, die eine IV oder Nonce generieren. Der Aufrufer übernimmt den Besitz des Ausgabeparameter-Arrays und muss es mit keymaster_free_param_set() freigeben . out_params kann auf NULL gesetzt werden, wenn keine Ausgabeparameter erwartet werden. Wenn out_params NULL ist und Ausgabeparameter generiert werden, gibt begin() KM_ERROR_OUTPUT_PARAMETER_NULL zurück.
[aus]	operation_handle	Das neu erstellte Operations-Handle, das an update() , finish() oder abort() übergeben werden muss. Wenn operation_handle NULL ist, gibt begin() KM_ERROR_OUTPUT_PARAMETER_NULL zurück.

Definition in Zeile 332 der Datei keymaster2.h .

Gängige Methoden des Keymaster-Geräts. Dies muss das erste Mitglied von keymaster_device sein, da Benutzer dieser Struktur in Kontexten, in denen bekannt ist, dass hw_device_t auf ein keymaster_device verweist, einen hw_device_t auf einen keymaster_device-Zeiger umwandeln.

Definition in Zeile 35 der Datei keymaster2.h .

Konfiguriert Keymaster. Diese Methode muss einmalig nach dem Öffnen des Geräts und vor der Verwendung aufgerufen werden. Es wird verwendet, um Keymaster KM_TAG_OS_VERSION und KM_TAG_OS_PATCHLEVEL bereitzustellen. Bis diese Methode aufgerufen wird, geben alle anderen Methoden KM_ERROR_KEYMASTER_NOT_CONFIGURED zurück. Die von dieser Methode bereitgestellten Werte werden von Keymaster nur einmal pro Boot akzeptiert. Nachfolgende Aufrufe geben KM_ERROR_OK zurück, tun aber nichts.

Wenn sich die Keymaster-Implementierung in sicherer Hardware befindet und die bereitgestellten OS-Versions- und Patch-Level-Werte nicht mit den Werten übereinstimmen, die der Bootloader für die sichere Hardware bereitgestellt hat (oder wenn der Bootloader keine Werte bereitgestellt hat), gibt diese Methode KM_ERROR_INVALID_ARGUMENT und alle zurück andere Methoden werden weiterhin KM_ERROR_KEYMASTER_NOT_CONFIGURED zurückgeben.

Definition in Zeile 58 der Datei keymaster2.h .

Definition in Zeile 37 der Datei keymaster2.h .

Löscht alle Schlüssel im Hardware-Schlüsselspeicher. Wird verwendet, wenn der Schlüsselspeicher vollständig zurückgesetzt wird. Nach dem Aufruf dieser Funktion können keine zuvor generierten oder importierten Key-Blobs für Operationen verwendet werden.

Diese Funktion ist optional und sollte auf NULL gesetzt werden, wenn sie nicht implementiert ist.

Parameter

[in]

Entwickler

Die Keymaster-Gerätestruktur.

Definition in Zeile 288 der Datei keymaster2.h .

Löscht den Schlüssel oder das Schlüsselpaar, das dem Schlüsselblob zugeordnet ist. Nach dem Aufruf dieser Funktion kann die Taste nicht mehr für andere Operationen verwendet werden. Kann auf Schlüssel aus fremden Vertrauensstämmen angewendet werden (Schlüssel, die unter dem aktuellen Vertrauensstränge nicht verwendbar sind).

Diese Funktion ist optional und sollte auf NULL gesetzt werden, wenn sie nicht implementiert ist.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	Schlüssel	Der zu löschende Schlüssel.

Definition in Zeile 276 der Datei keymaster2.h .

Exportiert einen öffentlichen oder symmetrischen Schlüssel und gibt ein Byte-Array im angegebenen Format zurück.

Beachten Sie, dass der symmetrische Schlüsselexport nur erlaubt ist, wenn der Schlüssel mit KM_TAG_EXPORTABLE erstellt wurde und nur dann, wenn alle Voraussetzungen für die Schlüsselverwendung (z. B. Authentifizierung) erfüllt sind.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	export_format	Das Format, das zum Exportieren des Schlüssels verwendet werden soll.
[in]	key_to_export	Der Schlüssel zum Exportieren.
[in]	Kunden ID	Client-ID-Blob, das mit dem in KM_TAG_APPLICATION_ID während der Schlüsselgenerierung (falls vorhanden) bereitgestellten Blob übereinstimmen muss.
[in]	Anwendungsdaten	Anwendungsdaten-Blob, das mit dem in KM_TAG_APPLICATION_DATA während der Schlüsselgenerierung (falls vorhanden) bereitgestellten Blob übereinstimmen muss.
[aus]	Daten exportieren	Das exportierte Schlüsselmaterial. Der Aufrufer übernimmt das Eigentum.

Definition in Zeile 213 der Datei keymaster2.h .

Schließt eine mit begin() begonnene kryptographische Operation ab und macht operation_handle ungültig.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	operation_handle	Das von begin() zurückgegebene Vorgangshandle. Dieses Handle wird ungültig.
[in]	in_params	Zusätzliche Parameter für die Operation. Für AEAD-Modi wird dies verwendet, um KM_TAG_ADDITIONAL_DATA anzugeben, aber nur, wenn keine Eingabedaten für update() bereitgestellt wurden.
[in]	Eingang	Zu verarbeitende Daten gemäß den im Aufruf von begin() festgelegten Parametern. finish() muss alle bereitgestellten Daten verbrauchen oder KM_ERROR_INVALID_INPUT_LENGTH zurückgeben.
[in]	Unterschrift	Die zu überprüfende Signatur, wenn der im Aufruf begin() angegebene Zweck KM_PURPOSE_VERIFY war.
[aus]	Ausgang	Die Ausgabedaten, falls vorhanden. Der Aufrufer übernimmt den Besitz des zugewiesenen Puffers.

Wenn die zu beendende Operation eine Signaturverifizierung oder eine Entschlüsselung im AEAD-Modus ist und die Verifizierung fehlschlägt, gibt finish() KM_ERROR_VERIFICATION_FAILED zurück.

Definition in Zeile 405 der Datei keymaster2.h .

Siehe Flags, die für keymaster0_devices::flags in keymaster_common.h definiert sind. Wird nur aus Gründen der Abwärtskompatibilität verwendet; Keymaster2-Hardwaregeräte müssen dies auf Null setzen.

Definition in Zeile 43 der Datei keymaster2.h .

Generiert einen Schlüssel oder ein Schlüsselpaar und gibt einen Schlüsselblob und/oder eine Beschreibung des Schlüssels zurück.

Parameter für die Schlüsselgenerierung werden als Keymaster-Tag/Wert-Paare definiert, die in params bereitgestellt werden. Siehe keymaster_tag_t für die vollständige Liste. Einige Werte, die für die Generierung nützlicher Schlüssel immer erforderlich sind, sind:

• KM_TAG_ALGORITHMUS;
• KM_TAG_PURPOSE; und
• (KM_TAG_USER_SECURE_ID und KM_TAG_USER_AUTH_TYPE) oder KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT sollte im Allgemeinen angegeben werden, es sei denn, KM_TAG_NO_AUTH_REQUIRED ist vorhanden, oder der Benutzer muss sich für jede Verwendung authentifizieren.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH und KM_TAG_DIGEST müssen für Algorithmen angegeben werden, die sie erfordern.

Die folgenden Tags dürfen nicht angegeben werden; ihre Werte werden von der Implementierung bereitgestellt.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	Parameter	Array von Parametern zur Schlüsselgenerierung
[aus]	key_blob	gibt den generierten Schlüssel zurück. key_blob darf nicht NULL sein. Der Aufrufer übernimmt den Besitz von key_blob->key_material und muss es freigeben().
[aus]	Eigenschaften	gibt die Merkmale des Schlüssels zurück, der generiert wurde, wenn er nicht NULL ist. Wenn nicht NULL, übernimmt der Aufrufer den Besitz und muss die Zuordnung mit keymaster_free_characteristics() aufheben . Beachten Sie, dass KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA niemals zurückgegeben werden.

Definition in Zeile 112 der Datei keymaster2.h .

Gibt die Merkmale des angegebenen Schlüssels oder KM_ERROR_INVALID_KEY_BLOB zurück, wenn key_blob ungültig ist (Implementierungen müssen die Integrität des Schlüssels vollständig validieren). client_id und app_data müssen die ID und die Daten sein, die beim Generieren oder Importieren des Schlüssels bereitgestellt wurden, oder leer sein, wenn KM_TAG_APPLICATION_ID und/oder KM_TAG_APPLICATION_DATA während der Generierung nicht bereitgestellt wurden. Diese Werte sind nicht in den zurückgegebenen Merkmalen enthalten. Der Aufrufer übernimmt den Besitz des zugewiesenen Merkmalsobjekts, das mit keymaster_free_characteristics() freigegeben werden muss.

Beachten Sie, dass KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA niemals zurückgegeben werden.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	key_blob	Der Schlüssel zum Abrufen von Merkmalen aus.
[in]	Kunden ID	Die Client-ID-Daten oder NULL, wenn keine zugeordnet sind.
[in]	app_id	Die App-Daten oder NULL, wenn keine zugeordnet sind.
[aus]	Eigenschaften	Die wichtigsten Eigenschaften. Darf nicht NULL sein. Der Aufrufer übernimmt das Eigentum an den Inhalten und muss die Zuordnung mit keymaster_free_characteristics() aufheben .

Definition in Zeile 139 der Datei keymaster2.h .

Importiert einen Schlüssel oder ein Schlüsselpaar und gibt ein Schlüssel-Blob und/oder eine Beschreibung des Schlüssels zurück.

Die meisten wichtigen Importparameter sind als Keymaster-Tag/Wert-Paare definiert, die in "params" bereitgestellt werden. Siehe keymaster_tag_t für die vollständige Liste. Werte, die für den Import nützlicher Schlüssel immer benötigt werden, sind:

• KM_TAG_ALGORITHMUS;
• KM_TAG_PURPOSE; und
• (KM_TAG_USER_SECURE_ID und KM_TAG_USER_AUTH_TYPE) oder KM_TAG_NO_AUTH_REQUIRED.

Generell sollte KM_TAG_AUTH_TIMEOUT angegeben werden. Wenn nicht angegeben, muss sich der Benutzer für jede Verwendung authentifizieren.

Die folgenden Tags nehmen Standardwerte an, wenn sie nicht angegeben sind:

• KM_TAG_KEY_SIZE nimmt standardmäßig die Größe des bereitgestellten Schlüssels an.
• KM_TAG_RSA_PUBLIC_EXPONENT wird standardmäßig auf den Wert im bereitgestellten Schlüssel gesetzt (für RSA-Schlüssel)

Die folgenden Tags dürfen nicht angegeben werden; ihre Werte werden von der Implementierung bereitgestellt.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	Parameter	Parameter, die den importierten Schlüssel definieren.
[in]	params_count	Die Anzahl der Einträge in params .
[in]	key_format	gibt das Format der Schlüsseldaten in key_data an.
[aus]	key_blob	Wird verwendet, um das undurchsichtige Schlüssel-Blob zurückzugeben. Muss nicht NULL sein. Der Aufrufer übernimmt das Eigentum an dem enthaltenen key_material.
[aus]	Eigenschaften	Wird verwendet, um die Merkmale des importierten Schlüssels zurückzugeben. Kann NULL sein, dann werden keine Merkmale zurückgegeben. Wenn nicht NULL, übernimmt der Aufrufer das Eigentum an den Inhalten und muss die Zuordnung mit keymaster_free_characteristics() aufheben . Beachten Sie, dass KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA niemals zurückgegeben werden.

Definition in Zeile 186 der Datei keymaster2.h .

Stellt Daten für eine laufende kryptografische Operation bereit, die mit begin() begonnen wurde, und empfängt möglicherweise Ausgaben von ihr.

Wenn operation_handle ungültig ist, gibt update() KM_ERROR_INVALID_OPERATION_HANDLE zurück.

update() verbraucht möglicherweise nicht alle im Datenpuffer bereitgestellten Daten. update() gibt die verbrauchte Menge in *data_consumed zurück. Der Anrufer sollte die unverbrauchten Daten in einem nachfolgenden Anruf bereitstellen.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	operation_handle	Das von begin() zurückgegebene Vorgangshandle.
[in]	in_params	Zusätzliche Parameter für die Operation. Für AEAD-Modi wird dies verwendet, um KM_TAG_ADDITIONAL_DATA anzugeben. Beachten Sie, dass zusätzliche Daten in mehreren Aufrufen von update() bereitgestellt werden können, jedoch nur, bis Eingabedaten bereitgestellt wurden.
[in]	Eingang	Zu verarbeitende Daten gemäß den im Aufruf von begin() festgelegten Parametern. Beachten Sie, dass update() möglicherweise alle bereitgestellten Daten verbraucht oder nicht. Siehe input_consumed .
[aus]	Eingabe_verbraucht	Datenmenge, die von update() verbraucht wurde. Wenn dies weniger als der bereitgestellte Betrag ist, sollte der Aufrufer den Rest in einem nachfolgenden Aufruf von update() bereitstellen.
[aus]	out_params	Ausgangsparameter. Wird verwendet, um zusätzliche Daten aus der Operation zurückzugeben. Der Aufrufer übernimmt den Besitz des Ausgabeparameter-Arrays und muss es mit keymaster_free_param_set() freigeben . out_params kann auf NULL gesetzt werden, wenn keine Ausgabeparameter erwartet werden. Wenn out_params NULL ist und Ausgabeparameter generiert werden, gibt begin() KM_ERROR_OUTPUT_PARAMETER_NULL zurück.
[aus]	Ausgang	Die Ausgabedaten, falls vorhanden. Der Aufrufer übernimmt den Besitz des zugewiesenen Puffers. Ausgabe darf nicht NULL sein.

Beachten Sie, dass update() möglicherweise keine Ausgabe liefert, in diesem Fall ist output->data_length null und output->data kann entweder NULL oder die Länge null haben (der Aufrufer sollte es also immer freigeben()).

Definition in Zeile 376 der Datei keymaster2.h .

Aktualisiert einen alten Schlüssel. Schlüssel können auf zwei Arten „alt“ werden: Keymaster kann auf eine neue Version aktualisiert werden, oder das System kann aktualisiert werden, um die Betriebssystemversion und/oder den Patch-Level ungültig zu machen. In beiden Fällen führt der Versuch, einen alten Schlüssel zu verwenden, dazu, dass Keymaster KM_ERROR_KEY_REQUIRES_UPGRADE zurückgibt. Diese Methode sollte dann aufgerufen werden, um den Schlüssel zu aktualisieren.

Parameter

[in]	Entwickler	Die Keymaster-Gerätestruktur.
[in]	key_to_upgrade	Der zu aktualisierende Keymaster-Schlüssel.
[in]	upgrade_params	Parameter, die zum Abschließen des Upgrades erforderlich sind. Insbesondere sind KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA erforderlich, wenn sie für den Schlüssel definiert wurden.
[aus]	upgraded_key	Das aktualisierte Schlüsselblob.

Definition in Zeile 260 der Datei keymaster2.h .