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. Es ist garantiert, dass die durch diese Methode hinzugefügte Entropie nicht die einzige verwendete Entropiequelle ist, und die Mischfunktion muss sicher sein, in dem Sinne, dass der Angreifer nicht vorhersagen kann (bzw Steuerung), dann ist die RNG-Ausgabe nicht von einer Zufallsausgabe zu unterscheiden. Wenn also die Entropie aus irgendeiner Quelle gut ist, ist auch die Ausgabe gut.

Parameter

[In]	Entwickler	Die Keymaster-Gerätestruktur.
[In]	Daten	Zufällige Daten zum Einmischen.
[In]	Datenlänge	Länge der data .

Definition in Zeile 74 der Datei keymaster2.h .

Erzeugt eine signierte X.509-Zertifikatskette, die das Vorhandensein von key_to_attest im Keymaster bestätigt (TODO(swillden): Beschreiben Sie den Inhalt des Zertifikats detaillierter). Das Zertifikat enthält eine Erweiterung mit OID 1.3.6.1.4.1.11129.2.1.17 und einem in <TODO:swillden – Link hier einfügen> definierten Wert, der die Schlüsselbeschreibung enthält.

Parameter

[In]	Entwickler	Die Keymaster-Gerätestruktur.
[In]	key_to_attest	Der Keymaster-Schlüssel, für den das Attestierungszertifikat generiert wird.
[In]	attest_params	Parameter, die definieren, wie die Bescheinigung 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 Nachweisschlü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 zurück zum Stammverzeichnis verkettet. Der Aufrufer übernimmt den Besitz und muss die Zuordnung zu keymaster_free_cert_chain aufheben.

Definition in Zeile 239 der Datei keymaster2.h .

Beginnt 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. Andernfalls kann es zu einem Verlust des internen Statusraums oder anderer interner Ressourcen kommen, was schließlich dazu führen kann, dass begin() KM_ERROR_TOO_MANY_OPERATIONS zurückgibt, wenn der Speicherplatz für Vorgänge knapp wird. Jedes andere Ergebnis als KM_ERROR_OK von begin() , update() oder finish() bricht den Vorgang 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 des Vorgangs, einer von KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN oder KM_PURPOSE_VERIFY. Beachten Sie, dass für AEAD-Modi die Verschlüsselung und Entschlüsselung eine Signierung bzw. Verifizierung 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 purpose kompatibel ist, und alle seine Verwendungsanforderungen müssen erfüllt sein, sonst gibt begin() einen entsprechenden Fehlercode zurück.
[In]	in_params	Zusätzliche Parameter für den Vorgang. Dies wird normalerweise zur Bereitstellung von Authentifizierungsdaten mit KM_TAG_AUTH_TOKEN verwendet. Wenn KM_TAG_APPLICATION_ID oder KM_TAG_APPLICATION_DATA während der Generierung bereitgestellt wurden, müssen sie hier bereitgestellt werden, sonst schlägt der Vorgang mit KM_ERROR_INVALID_KEY_BLOB fehl. Für Vorgänge, die eine Nonce oder IV erfordern, kann in_params bei Schlüsseln, die mit KM_TAG_CALLER_NONCE generiert wurden, ein Tag KM_TAG_NONCE enthalten.
[aus]	out_params	Ausgabeparameter. Wird verwendet, um zusätzliche Daten aus der Operationsinitialisierung zurückzugeben, insbesondere um den IV oder Nonce von Vorgängen zurückzugeben, die einen 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 Operationshandle, 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 einmal nach dem Öffnen des Geräts und vor seiner 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 Start akzeptiert. Nachfolgende Aufrufe geben KM_ERROR_OK zurück, führen jedoch nichts aus.

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

Definition in Zeile 58 der Datei keymaster2.h .

Definition in Zeile 37 der Datei keymaster2.h .

Löscht alle Schlüssel im Hardware-Keystore. Wird verwendet, wenn der Keystore vollständig zurückgesetzt wird. Nach dem Aufruf dieser Funktion ist es nicht mehr möglich, zuvor generierte oder importierte Schlüsselblobs für Vorgänge zu verwenden.

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 ist es nicht mehr möglich, die Taste für andere Vorgänge zu verwenden. Kann auf Schlüssel von fremden Vertrauenswurzeln angewendet werden (Schlüssel, die unter der aktuellen Vertrauenswurzel nicht verwendet werden können).

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 Export symmetrischer Schlüssel nur zulässig ist, wenn der Schlüssel mit KM_TAG_EXPORTABLE erstellt wurde und alle Anforderungen 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 Export.
[In]	Kunden ID	Client-ID-Blob, das mit dem Blob übereinstimmen muss, das in KM_TAG_APPLICATION_ID während der Schlüsselgenerierung bereitgestellt wurde (sofern vorhanden).
[In]	Anwendungsdaten	Anwendungsdatenblob, das mit dem Blob übereinstimmen muss, das in KM_TAG_APPLICATION_DATA während der Schlüsselgenerierung bereitgestellt wurde (sofern vorhanden).
[aus]	Daten exportieren	Das exportierte Schlüsselmaterial. Der Anrufer übernimmt das Eigentum.

Definition in Zeile 213 der Datei keymaster2.h .

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

Parameter

[In]	Entwickler	Die Keymaster-Gerätestruktur.
[In]	operation_handle	Das von begin() zurückgegebene Operationshandle. Dieses Handle wird ungültig.
[In]	in_params	Zusätzliche Parameter für den Vorgang. Für AEAD-Modi wird dies verwendet, um KM_TAG_ADDITIONAL_DATA anzugeben, jedoch 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 begin() -Aufruf angegebene Zweck KM_PURPOSE_VERIFY war.
[aus]	Ausgabe	Die Ausgabedaten, falls vorhanden. Der Aufrufer übernimmt den Besitz des zugewiesenen Puffers.

Wenn es sich bei dem abgeschlossenen Vorgang um eine Signaturüberprüfung oder eine Entschlüsselung und Überprüfung im AEAD-Modus handelt, schlägt die Funktion „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 .

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

Schlüsselgenerierungsparameter werden als Keymaster-Tag/Wert-Paare definiert und in params bereitgestellt. Die vollständige Liste finden Sie unter keymaster_tag_t. 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, da sich der Benutzer sonst bei jeder Verwendung authentifizieren muss.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH und KM_TAG_DIGEST müssen für Algorithmen angegeben werden, die dies 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 Schlüsselgenerierungsparametern
[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 dieser 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 der 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 angegeben wurden, oder leer sein, wenn KM_TAG_APPLICATION_ID und/oder KM_TAG_APPLICATION_DATA bei der Generierung nicht angegeben wurden. Diese Werte sind nicht in den zurückgegebenen Merkmalen enthalten. Der Aufrufer übernimmt den Besitz des zugewiesenen Characteristics-Objekts, dessen Zuordnung mit keymaster_free_characteristics() aufgehoben 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 Eigenschaften.
[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 Merkmale. Darf nicht NULL sein. Der Aufrufer übernimmt den Besitz des Inhalts 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 einen Schlüsselblob und/oder eine Beschreibung des Schlüssels zurück.

Die meisten Schlüsselimportparameter werden als Keymaster-Tag/Wert-Paare definiert und in „params“ bereitgestellt. Die vollständige Liste finden Sie unter keymaster_tag_t. Werte, die für den Import 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.

Generell sollte KM_TAG_AUTH_TIMEOUT angegeben werden. Wenn keine Angabe erfolgt, muss sich der Benutzer bei jeder Verwendung authentifizieren.

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

• KM_TAG_KEY_SIZE verwendet standardmäßig die Größe des bereitgestellten Schlüssels.
• KM_TAG_RSA_PUBLIC_EXPONENT verwendet standardmäßig den Wert im bereitgestellten Schlüssel (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 den undurchsichtigen Schlüssel-Blob zurückzugeben. Darf nicht NULL sein. Der Aufrufer übernimmt den Besitz des enthaltenen key_material.
[aus]	Eigenschaften	Wird verwendet, um die Eigenschaften des importierten Schlüssels zurückzugeben. Kann NULL sein. In diesem Fall werden keine Merkmale zurückgegeben. Wenn nicht NULL, übernimmt der Aufrufer den Besitz des Inhalts 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 einen laufenden kryptografischen Vorgang bereit, der mit begin() begonnen wurde, und empfängt möglicherweise Ausgaben von diesem.

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 in *data_consumed verbrauchte Menge zurück. Der Anrufer sollte die nicht verbrauchten Daten in einem nachfolgenden Anruf bereitstellen.

Parameter

[In]	Entwickler	Die Keymaster-Gerätestruktur.
[In]	operation_handle	Das von begin() zurückgegebene Operationshandle.
[In]	in_params	Zusätzliche Parameter für den Vorgang. 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 die 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]	input_consumed	Datenmenge, die von update() verbraucht wurde. Wenn dieser Betrag geringer ist als der angegebene Betrag, sollte der Aufrufer den Rest in einem nachfolgenden Aufruf von update() bereitstellen.
[aus]	out_params	Ausgabeparameter. Wird verwendet, um zusätzliche Daten von 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]	Ausgabe	Die Ausgabedaten, falls vorhanden. Der Aufrufer übernimmt den Besitz des zugewiesenen Puffers. Die Ausgabe darf nicht NULL sein.

Beachten Sie, dass update() möglicherweise keine Ausgabe bereitstellt. In diesem Fall ist „output->data_length“ Null und „output->data“ kann entweder NULL oder die Länge Null sein (der Aufrufer sollte es also immer „free()“ verwenden).

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ühren Versuche, 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	Der aktualisierte Schlüssel-Blob.

Definition in Zeile 260 der Datei keymaster2.h .