keymaster2_device-Strukturreferenz

Bricht einen kryptografischen Vorgang ab, der mit begin() gestartet wurde, und 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 Zufallszahlengenerator Entropie hinzu. Die mit dieser Methode hinzugefügte Entropie ist garantiert nicht die einzige verwendete Entropiequelle. Die Mischfunktion muss sicher sein, d. h. wenn der Zufallsgenerator (aus einer beliebigen Quelle) mit Daten initialisiert wird, die der Angreifer nicht vorhersagen oder steuern kann, ist die Ausgabe des Zufallsgenerators nicht von einer zufälligen Ausgabe zu unterscheiden. Wenn also die Entropie einer Quelle hoch ist, ist auch die Ausgabe hoch.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	Daten	Zufällige Daten, die eingemischt werden sollen.
[in]	data_length	Länge von 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): Zertifikatsinhalte genauer beschreiben). Das Zertifikat enthält eine Erweiterung mit der OID 1.3.6.1.4.1.11129.2.1.17 und dem Wert, der in <TODO:swillden – insert link here> definiert ist und die Schlüsselbeschreibung enthält.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	key_to_attest	Der Keymaster-Schlüssel, für den das Attestierungszertifikat generiert wird.
[in]	attest_params	Parameter, die festlegen, wie die Attestierung durchgeführt werden soll. Derzeit ist der einzige Parameter KM_TAG_ALGORITHM, der entweder KM_ALGORITHM_EC oder KM_ALGORITHM_RSA sein muss. Damit wird ausgewählt, welcher der bereitgestellten Attestierungsschlüssel zum Signieren des Zertifikats verwendet wird.
[out]	cert_chain	Ein Array von DER-codierten X.509-Zertifikaten. Das erste ist das Zertifikat für key_to_attest . Die übrigen Einträge werden zurück zur Wurzel verkettet. Der Aufrufer übernimmt die Inhaberschaft und muss die Dealokation mit keymaster_free_cert_chain ausführen.

Definition in Zeile 239 der Datei keymaster2.h .

Beginnt einen kryptografischen Vorgang mit dem angegebenen Schlüssel. Wenn alles in Ordnung ist, gibt begin() den Wert KM_ERROR_OK zurück und erstellt einen Vorgangs-Handle, der 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() gekoppelt ist, damit die Keymaster-Implementierung den internen Betriebsstatus bereinigen kann. Andernfalls kann es zu einem Leck des internen Statusbereichs oder anderer interner Ressourcen kommen und schließlich dazu führen, dass begin() den Fehler KM_ERROR_TOO_MANY_OPERATIONS zurückgibt, wenn der Speicherplatz für Vorgänge aufgebraucht ist. Jedes andere Ergebnis als KM_ERROR_OK von begin() , update() oder finish() löst eine implizite Abbruch des Vorgangs aus. In diesem Fall muss abort() nicht aufgerufen werden. Wird er dennoch aufgerufen, wird KM_ERROR_INVALID_OPERATION_HANDLE zurückgegeben.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	Zweck	Der Zweck des Vorgangs, einer der folgenden Werte: KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN oder KM_PURPOSE_VERIFY. Hinweis: Bei AEAD-Modi implizieren Verschlüsselung und Entschlüsselung Signatur und Überprüfung, sollten aber als KM_PURPOSE_ENCRYPT und KM_PURPOSE_DECRYPT angegeben werden.
[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 Nutzungsanforderungen müssen erfüllt sein. Andernfalls gibt begin() einen entsprechenden Fehlercode zurück.
[in]	in_params	Zusätzliche Parameter für den Vorgang. Dieser Parameter wird in der Regel zusammen mit KM_TAG_AUTH_TOKEN verwendet, um Authentifizierungsdaten bereitzustellen. Wenn KM_TAG_APPLICATION_ID oder KM_TAG_APPLICATION_DATA während der Generierung angegeben wurden, müssen sie auch hier angegeben werden. Andernfalls schlägt der Vorgang mit KM_ERROR_INVALID_KEY_BLOB fehl. Bei Vorgängen, für die eine Nonce oder IV erforderlich ist, kann in_params für Schlüssel, die mit KM_TAG_CALLER_NONCE generiert wurden, das Tag KM_TAG_NONCE enthalten.
[out]	out_params	Ausgabeparameter Wird verwendet, um zusätzliche Daten aus der Vorgangsinitialisierung zurückzugeben, insbesondere die IV oder Nonce von Vorgängen, die eine IV oder Nonce generieren. Der Aufrufer übernimmt die Besitzrechte für das Array der Ausgabeparameter 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() den Fehlerwert „KM_ERROR_OUTPUT_PARAMETER_NULL“ zurück.
[out]	operation_handle	Der neu erstellte Vorgangs-Handle, der an update() , finish() oder abort() übergeben werden muss. Wenn „operation_handle“ NULL ist, gibt begin() den Fehler „KM_ERROR_OUTPUT_PARAMETER_NULL“ zurück.

Definition in Zeile 332 der Datei keymaster2.h .

Gängige Methoden des Keymaster-Geräts. Dieser muss das erste Mitglied von „keymaster_device“ sein, da Nutzer dieser Struktur einen hw_device_t-Wert in einen „keymaster_device“-Zeiger umwandeln, wenn bekannt ist, dass hw_device_t auf ein „keymaster_device“ verweist.

Definition in Zeile 35 der Datei keymaster2.h .

Konfiguriert Keymaster. Diese Methode muss einmal nach dem Öffnen des Geräts und vor der Verwendung aufgerufen werden. Sie wird verwendet, um KM_TAG_OS_VERSION und KM_TAG_OS_PATCHLEVEL an Keymaster bereitzustellen. Bis diese Methode aufgerufen wird, geben alle anderen Methoden KM_ERROR_KEYMASTER_NOT_CONFIGURED zurück. Die mit dieser Methode bereitgestellten Werte werden vom Keymaster nur einmal pro Start akzeptiert. Bei nachfolgenden Aufrufen wird KM_ERROR_OK zurückgegeben, es passiert aber nichts.

Wenn sich die Keymaster-Implementierung in sicherer Hardware befindet und die angegebenen Werte für die Betriebssystemversion und die Patchebene nicht mit den Werten übereinstimmen, die der Bootloader der sicheren Hardware zur Verfügung gestellt hat (oder wenn der Bootloader keine Werte angegeben hat), gibt diese Methode KM_ERROR_INVALID_ARGUMENT zurück und alle anderen 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 .

Alle Schlüssel im Hardware-Schlüsselspeicher werden gelöscht. Wird verwendet, wenn der Schlüsselspeicher vollständig zurückgesetzt wird. Nach dem Aufrufen dieser Funktion können zuvor generierte oder importierte Schlüssel-Blobs für keine Vorgänge mehr verwendet werden.

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

Parameter

[in]

dev

Die Keymaster-Gerätestruktur.

Definition in Zeile 288 der Datei keymaster2.h .

Löscht den Schlüssel oder das Schlüsselpaar, das mit dem Schlüssel-Blob verknüpft ist. Nach dem Aufrufen dieser Funktion kann der Schlüssel nicht mehr für andere Vorgänge verwendet werden. Kann auf Schlüssel aus fremden Stammvertrauensstellen angewendet werden (Schlüssel, die unter der aktuellen Stammvertrauensstelle nicht verwendet werden können).

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

Parameter

[in]	dev	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.

Der Export symmetrischer Schlüssel ist nur zulässig, wenn der Schlüssel mit KM_TAG_EXPORTABLE erstellt wurde und alle Anforderungen an die Schlüsselnutzung (z.B. Authentifizierung) erfüllt sind.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	export_format	Das Format, das für den Export des Schlüssels verwendet werden soll.
[in]	key_to_export	Der zu exportierende Schlüssel.
[in]	client_id	Client-ID-Blob, der mit dem Blob in KM_TAG_APPLICATION_ID übereinstimmen muss, der bei der Schlüsselgenerierung angegeben wurde (falls vorhanden).
[in]	app_data	Blob mit Anwendungsdaten, der mit dem Blob in KM_TAG_APPLICATION_DATA während der Schlüsselgenerierung übereinstimmen muss (falls vorhanden).
[out]	export_data	Das exportierte Schlüsselmaterial. Der Anrufer übernimmt die Verantwortung.

Definition in Zeile 213 der Datei keymaster2.h .

Schließt einen kryptografischen Vorgang ab, der mit begin() begonnen wurde, und macht operation_handle ungültig.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	operation_handle	Der Vorgangs-Handle, der von begin() zurückgegeben wird. Dieser Alias wird ungültig.
[in]	in_params	Zusätzliche Parameter für den Vorgang. Bei AEAD-Modi wird damit KM_TAG_ADDITIONAL_DATA angegeben, aber nur, wenn für update() keine Eingabedaten bereitgestellt wurden.
[in]	Eingabe	Zu verarbeitende Daten gemäß den Parametern, die im Aufruf von begin() festgelegt wurden. finish() muss alle angegebenen Daten verarbeiten oder KM_ERROR_INVALID_INPUT_LENGTH zurückgeben.
[in]	Signatur	Die Signatur, die überprüft werden soll, wenn der im Aufruf von begin() angegebene Zweck KM_PURPOSE_VERIFY war.
[out]	output	Die Ausgabedaten, falls vorhanden. Der Aufrufer übernimmt die Inhaberschaft des zugewiesenen Buffers.

Wenn der abgeschlossene Vorgang eine Signaturprüfung oder eine Entschlüsselung im AEAD-Modus ist und die Prüfung 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 für die Abwärtskompatibilität verwendet. Bei Keymaster2-Hardwaregeräten muss dieser Wert auf null gesetzt werden.

Definition in Zeile 43 der Datei keymaster2.h .

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

Die Parameter für die Schlüsselgenerierung werden als Tag/Wert-Paare für den Keymaster definiert und in params angegeben. Eine vollständige Liste findest du unter „keymaster_tag_t“. Einige Werte, die für die Generierung nützlicher Schlüssel immer erforderlich sind:

• KM_TAG_ALGORITHM;
• 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 in der Regel angegeben werden, es sei denn, KM_TAG_NO_AUTH_REQUIRED ist vorhanden. Andernfalls muss sich der Nutzer bei jeder Verwendung authentifizieren.

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

Die folgenden Tags können nicht angegeben werden; ihre Werte werden von der Implementierung bereitgestellt.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	params	Array von Parametern für die Schlüsselgenerierung
[out]	key_blob	gibt den generierten Schlüssel zurück. key_blob darf nicht NULL sein. Der Aufrufer übernimmt die Inhaberschaft von „key_blob“ -> „key_material“ und muss es mit „free()“ freigeben.
[out]	Eigenschaften	Gibt die Eigenschaften des generierten Schlüssels zurück, sofern er nicht NULL ist. Wenn der Wert nicht NULL ist, übernimmt der Aufrufer die Inhaberschaft und muss die Dealokalisierung mit keymaster_free_characteristics() vornehmen. Hinweis: KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA werden nie zurückgegeben.

Definition in Zeile 112 der Datei keymaster2.h .

Gibt die Eigenschaften des angegebenen Schlüssels zurück oder KM_ERROR_INVALID_KEY_BLOB, wenn der Schlüssel-Blob ungültig ist. Implementierungen müssen die Integrität des Schlüssels vollständig prüfen. „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, 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 die Inhaberschaft des zugewiesenen Characteristics-Objekts, das mit keymaster_free_characteristics() freigegeben werden muss.

KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA werden nie zurückgegeben.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	key_blob	Der Schlüssel, von dem Merkmale abgerufen werden sollen.
[in]	client_id	Die Daten der Client-ID oder „NULL“, wenn keine verknüpft ist.
[in]	app_id	Die App-Daten oder NULL, wenn keine zugeordnet sind.
[out]	Eigenschaften	Die wichtigsten Merkmale. Darf nicht NULL sein. Der Aufrufer übernimmt die Inhaberschaft der Inhalte und muss sie mit keymaster_free_characteristics() zuweisen.

Definition in Zeile 139 der Datei keymaster2.h .

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

Die meisten wichtigen Importparameter werden als Keymaster-Tag/Wert-Paare definiert und unter „params“ angegeben. Eine vollständige Liste findest du unter „keymaster_tag_t“. Für den Import nützlicher Schlüssel sind immer folgende Werte erforderlich:

• KM_TAG_ALGORITHM;
• 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 in der Regel angegeben werden. Wenn nicht angegeben, muss sich der Nutzer bei jeder Verwendung authentifizieren.

Für die folgenden Tags werden Standardwerte verwendet, wenn keine Angabe erfolgt:

• KM_TAG_KEY_SIZE hat standardmäßig die Größe des bereitgestellten Schlüssels.
• Für KM_TAG_RSA_PUBLIC_EXPONENT wird standardmäßig der Wert im angegebenen Schlüssel verwendet (für RSA-Schlüssel).

Die folgenden Tags können nicht angegeben werden; ihre Werte werden von der Implementierung bereitgestellt.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	params	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.
[out]	key_blob	Wird verwendet, um den opaken Schlüssel-Blob zurückzugeben. Darf nicht NULL sein. Der Aufrufer übernimmt die Inhaberschaft des enthaltenen Schlüsselmaterials.
[out]	Eigenschaften	Wird verwendet, um die Eigenschaften des importierten Schlüssels zurückzugeben. Kann NULL sein. In diesem Fall werden keine Merkmale zurückgegeben. Wenn der Wert nicht NULL ist, übernimmt der Aufrufer die Inhaberschaft der Inhalte und muss sie mit keymaster_free_characteristics() zuweisen. KM_TAG_APPLICATION_ID und KM_TAG_APPLICATION_DATA werden nie zurückgegeben.

Definition in Zeile 186 der Datei keymaster2.h .

Stellt Daten für einen laufenden kryptografischen Vorgang bereit und empfängt möglicherweise eine Ausgabe von diesem Vorgang, der mit begin() begonnen wurde.

Wenn „operation_handle“ ungültig ist, gibt update() den Fehler KM_ERROR_INVALID_OPERATION_HANDLE zurück.

update() verarbeitet möglicherweise nicht alle Daten im Datenpuffer. update() gibt die verbrauchte Menge in *data_consumed zurück. Der Aufrufer sollte die nicht verwendeten Daten in einem nachfolgenden Aufruf angeben.

Parameter

[in]	dev	Die Keymaster-Gerätestruktur.
[in]	operation_handle	Der Vorgangs-Handle, der von begin() zurückgegeben wird.
[in]	in_params	Zusätzliche Parameter für den Vorgang. Bei AEAD-Modi wird damit KM_TAG_ADDITIONAL_DATA angegeben. Zusätzliche Daten können in mehreren Aufrufen von update() bereitgestellt werden, aber nur, bis Eingabedaten vorhanden sind.
[in]	Eingabe	Zu verarbeitende Daten gemäß den Parametern, die im Aufruf von begin() festgelegt wurden. Hinweis: Bei update() werden möglicherweise nicht alle angegebenen Daten verwendet. Weitere Informationen finden Sie unter input_consumed .
[out]	input_consumed	Die Datenmenge, die durch update() verbraucht wurde. Wenn dieser Wert unter dem angegebenen Betrag liegt, sollte der Aufrufer den Rest in einem nachfolgenden Aufruf von update() angeben.
[out]	out_params	Ausgabeparameter Wird verwendet, um zusätzliche Daten aus dem Vorgang zurückzugeben. Der Aufrufer übernimmt die Inhaberschaft 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() den Fehlerwert „KM_ERROR_OUTPUT_PARAMETER_NULL“ zurück.
[out]	output	Die Ausgabedaten, falls vorhanden. Der Aufrufer übernimmt die Inhaberschaft des zugewiesenen Buffers. „output“ darf nicht NULL sein.

Hinweis: update() liefert möglicherweise keine Ausgabe. In diesem Fall ist output->data_length gleich null und output->data ist entweder NULL oder hat eine Länge von null. Der Aufrufer sollte es daher immer mit free() 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 umgestellt oder das System kann aktualisiert werden, um die Betriebssystemversion und/oder die Patchebene 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]	dev	Die Keymaster-Gerätestruktur.
[in]	key_to_upgrade	Der Keymaster-Schlüssel, der aktualisiert werden soll.
[in]	upgrade_params	Parameter, die für die Durchführung 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.
[out]	upgraded_key	Der aktualisierte Schlüssel-Blob.

Definition in Zeile 260 der Datei keymaster2.h .