Keymaster-Funktionen

Auf dieser Seite finden Sie Details, die Implementierern von Keymaster-Hardwareabstraktionsschichten (HALs) helfen sollen. Sie deckt alle Funktionen in der API ab, listet die Keymaster-Version auf, in der die Funktion verfügbar ist, und beschreibt die Standardimplementierung. Informationen zu Tags findest du auf der Seite Keymaster-Autorisierungs-Tags.

Hinweis:Zur Unterstützung der Umstellung von Keymaster 3 von der alten C-Struktur-HAL zur C++ HAL-Schnittstelle, die aus einer Definition in der neuen Hardware Interface Definition Language (HIDL) generiert wird, haben sich die Funktionsnamen in Android 8.0 geändert. Dazu werden Funktionen jetzt in Camel Case geschrieben. Beispiel: get_key_characteristics ist jetzt getKeyCharacteristics.

Allgemeine Implementierungsrichtlinien

Die folgenden Richtlinien gelten für alle Funktionen in der API.

Eingabezeigerparameter

Version:1, 2

Eingabezeigerparameter, die für einen bestimmten Aufruf nicht verwendet werden, können NULL sein. Der Anrufer muss keine Platzhalter angeben. Bei einigen Schlüsseltypen und -modi werden beispielsweise keine Werte aus dem Argument inParams für begin verwendet. Der Aufrufer kann inParams dann auf NULL festlegen oder einen leeren Parametersatz angeben. Caller können auch nicht verwendete Parameter angeben. Keymaster-Methoden sollten keine Fehler ausgeben.

Wenn ein erforderlicher Eingabeparameter NULL ist, sollten Keymaster-Methoden ErrorCode::UNEXPECTED_NULL_POINTER zurückgeben.

Ab Keymaster 3 gibt es keine Zeigerparameter mehr. Alle Parameter werden per Wert oder Konstantenreferenz übergeben.

Ausgabezeigerparameter

Version:1, 2

Ähnlich wie bei Eingabezeigerparametern kann NULL für nicht verwendete Ausgabezeigerparameter verwendet werden. Wenn eine Methode Daten in einem Ausgabeparameter zurückgeben muss, der NULL ist, sollte sie ErrorCode::OUTPUT_PARAMETER_NULL zurückgeben.

Ab Keymaster 3 gibt es keine Zeigerparameter mehr. Alle Parameter werden per Wert oder Konstantenreferenz übergeben.

Missbrauch der API

Version:1, 2, 3

Es gibt viele Möglichkeiten, wie Anrufer Anfragen stellen können, die keinen Sinn ergeben oder unsinnig sind, aber technisch nicht falsch sind. Keymaster-Implementierungen müssen in solchen Fällen nicht fehlschlagen oder eine Diagnose ausgeben. Die Verwendung zu kleiner Schlüssel, die Angabe irrelevanter Eingabeparameter, die Wiederverwendung von IV- oder Nonce-Werten, die Generierung von Schlüsseln ohne Zweck und ähnliches sollten von Implementierungen nicht erkannt werden. Das Auslassen erforderlicher Parameter, die Angabe ungültiger erforderlicher Parameter und ähnliche Fehler müssen diagnostiziert werden.

Es liegt in der Verantwortung der Apps, des Frameworks und des Android-Schlüsselspeichers, dafür zu sorgen, dass die Aufrufe von Keymaster-Modulen sinnvoll und nützlich sind.

Achtung:Bei Keymaster-Implementierungen sollten ernsthafte Fehler wie das Auslassen erforderlicher Parameter, die Angabe ungültiger erforderlicher Parameter und ähnliche Fehler diagnostiziert werden, die die Integrität der Keymaster-Implementierung beeinträchtigen.

Funktionen

getHardwareFeatures

Version:3

Die neue getHardwareFeatures-Methode gibt Kunden einige wichtige Merkmale der zugrunde liegenden sicheren Hardware preis. Die Methode nimmt keine Argumente entgegen und gibt vier Werte zurück, alle booleschen:

• isSecure ist true, wenn Schlüssel in sicherer Hardware (z. B. TEE) gespeichert werden und diese nie verlassen.
• supportsEllipticCurve ist true, wenn die Hardware die Elliptische-Kurven-Kryptografie mit den NIST-Kurven (P-224, P-256, P-384 und P-521) unterstützt.
• supportsSymmetricCryptography ist true, wenn die Hardware symmetrische Kryptografie unterstützt, einschließlich AES und HMAC.
• supportsAttestation ist true, wenn die Hardware die Generierung von Keymaster-Public-Key-Attestierungszertifikaten unterstützt, die mit einem Schlüssel signiert sind, der in eine sichere Umgebung eingeschleust wurde.

Die einzigen Fehlercodes, die diese Methode zurückgeben kann, sind ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED oder einer der Fehlercodes, die auf eine Kommunikationsstörung mit der sicheren Hardware hinweisen.

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

konfigurieren

Version:2

Diese Funktion wurde in Keymaster 2 eingeführt und in Keymaster 3 eingestellt, da diese Informationen in Systemeigenschaftendateien verfügbar sind und Herstellerimplementierungen diese Dateien beim Start lesen.

Konfiguriert Keymaster. Diese Methode wird einmal aufgerufen, nachdem das Gerät geöffnet und bevor es verwendet wird. Damit werden KM_TAG_OS_VERSION und KM_TAG_OS_PATCHLEVEL an Keymaster gesendet. Bis diese Methode aufgerufen wird, geben alle anderen Methoden KM_ERROR_KEYMASTER_NOT_CONFIGURED zurück. Die mit dieser Methode angegebenen 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 vom Bootloader an die sichere Hardware übergeben wurden (oder 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.

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

addRngEntropy

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als add_rng_entropy eingeführt und in Keymaster 3 umbenannt.

Fügen Sie dem Pool, der von der Keymaster 1-Implementierung zum Generieren von Zufallszahlen, Schlüsseln, IV-Werten und anderen Elementen verwendet wird, vom Aufrufer bereitgestellte Entropie hinzu.

Keymaster-Implementierungen müssen die bereitgestellte Entropie sicher in ihren Pool einbinden, der auch intern generierte Entropie von einem Hardware-Zufallszahlengenerator enthalten muss. Die Mischung sollte so erfolgen, dass ein Angreifer, der entweder die von addRngEntropy bereitgestellten Bits oder die von der Hardware generierten Bits vollständig kontrollieren kann, aber nicht beides, keinen nennenswerten Vorteil bei der Vorhersage der aus dem Entropiepool generierten Bits hat.

Keymaster-Implementierungen, die versuchen, die Entropie in ihrem internen Pool zu schätzen, gehen davon aus, dass von addRngEntropy bereitgestellte Daten keine Entropie enthalten. Keymaster-Implementierungen können ErrorCode::INVALID_INPUT_LENGTH zurückgeben, wenn sie in einem einzigen Aufruf mehr als 2 KiB Daten erhalten.

generateKey

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als generate_key eingeführt und in Keymaster 3 umbenannt.

Generiert einen neuen kryptografischen Schlüssel und gibt zugehörige Autorisierungen an, die dauerhaft mit dem Schlüssel verknüpft sind. Keymaster-Implementierungen machen es unmöglich, einen Schlüssel in einer Weise zu verwenden, die nicht mit den bei der Generierung angegebenen Berechtigungen übereinstimmt. Bei Berechtigungen, die die sichere Hardware nicht erzwingen kann, beschränkt sich die Verpflichtung der sicheren Hardware darauf, dafür zu sorgen, dass die nicht durchsetzbaren Berechtigungen, die mit dem Schlüssel verknüpft sind, nicht geändert werden können, sodass jeder Aufruf von getKeyCharacteristics den ursprünglichen Wert zurückgibt. Außerdem werden mit den von generateKey zurückgegebenen Merkmalen Autorisierungen korrekt zwischen den hardware- und softwaregestützten Listen zugewiesen. Weitere Informationen finden Sie unter getKeyCharacteristics.

Die für generateKey bereitgestellten Parameter hängen vom Typ des generierten Schlüssels ab. In diesem Abschnitt werden die erforderlichen und optionalen Tags für jeden Schlüsseltyp zusammengefasst. Tag::ALGORITHM ist immer erforderlich, um den Typ anzugeben.

RSA-Schlüssel

Die folgenden Parameter sind zum Generieren eines RSA-Schlüssels erforderlich.

• Tag::KEY_SIZE gibt die Größe des öffentlichen Modulus in Bits an. Wenn sie weggelassen wird, gibt die Methode ErrorCode::UNSUPPORTED_KEY_SIZE zurück. Unterstützte Werte sind 1.024, 2.048, 3.072 und 4.096. Empfohlene Werte sind alle Schlüsselgrößen, die ein Vielfaches von 8 sind.
• Tag::RSA_PUBLIC_EXPONENT gibt den Wert des öffentlichen RSA-Exponenten an. Wenn sie weggelassen wird, gibt die Methode ErrorCode::INVALID_ARGUMENT zurück. Unterstützte Werte sind 3 und 65537. Empfohlene Werte sind alle Primzahlen bis 2^64.

Die folgenden Parameter sind nicht zum Generieren eines RSA-Schlüssels erforderlich. Wenn Sie jedoch einen RSA-Schlüssel ohne sie erstellen, ist er nicht verwendbar. Die Funktion generateKey gibt jedoch keinen Fehler zurück, wenn diese Parameter weggelassen werden.

• Tag::PURPOSE gibt die zulässigen Zwecke an. Für RSA-Schlüssel müssen alle Zwecke in beliebiger Kombination unterstützt werden.
• Tag::DIGEST gibt Digest-Algorithmen an, die mit dem neuen Schlüssel verwendet werden können. Implementierungen, die nicht alle Hash-Algorithmen unterstützen, müssen Anfragen zur Schlüsselgenerierung akzeptieren, die nicht unterstützte Hash-Werte enthalten. Die nicht unterstützten Hash-Werte sollten in der Liste der softwaregestützten Schlüsseleigenschaften in den zurückgegebenen Schlüsseleigenschaften aufgeführt werden. Das liegt daran, dass der Schlüssel mit diesen anderen Digests verwendet werden kann, die Erstellung des Digests aber in der Software erfolgt. Anschließend wird die Hardware aufgerufen, um den Vorgang mit Digest::NONE auszuführen.
• Tag::PADDING gibt die Padding-Modi an, die mit dem neuen Schlüssel verwendet werden können. Bei Implementierungen, die nicht alle Digest-Algorithmen unterstützen, müssen PaddingMode::RSA_PSS und PaddingMode::RSA_OAEP in die softwareseitig erzwungene Liste der Schlüsselmerkmale aufgenommen werden, wenn nicht unterstützte Digest-Algorithmen angegeben sind.

ECDSA-Schlüssel

Für die Generierung eines ECDSA-Schlüssels ist nur Tag::KEY_SIZE erforderlich. Mit diesem Tag wird die EC-Gruppe ausgewählt. Unterstützte Werte sind 224, 256, 384 und 521, die jeweils für die NIST-Kurven p-224, p-256, p-384 und p521 stehen.

Tag::DIGEST ist auch für einen nützlichen ECDSA-Schlüssel erforderlich, aber nicht für die Generierung.

AES-Schlüssel

Nur Tag::KEY_SIZE ist zum Generieren eines AES-Schlüssels erforderlich. Wenn sie weggelassen wird, gibt die Methode ErrorCode::UNSUPPORTED_KEY_SIZE zurück. Unterstützte Werte sind 128 und 256, optional auch 192-Bit-AES-Schlüssel.

Die folgenden Parameter sind besonders relevant für AES-Schlüssel, aber nicht erforderlich, um einen zu generieren:

• Tag::BLOCK_MODE gibt die Blockmodi an, mit denen der neue Schlüssel verwendet werden kann.
• Tag::PADDING gibt die Padding-Modi an, die verwendet werden können. Dies gilt nur für die Modi ECB und CBC.

Wenn der GCM-Blockierungsmodus angegeben ist, geben Sie Tag::MIN_MAC_LENGTH an. Wird dieser Parameter weggelassen, gibt die Methode ErrorCode::MISSING_MIN_MAC_LENGTH zurück. Der Wert des Tags ist ein Vielfaches von 8 und liegt zwischen 96 und 128.

HMAC-Schlüssel

Für die HMAC-Schlüsselgenerierung sind die folgenden Parameter erforderlich:

• Tag::KEY_SIZE gibt die Schlüsselgröße in Bit an. Werte unter 64 und keine Vielfache von 8 werden nicht unterstützt. Es werden alle Vielfachen von 8, von 64 bis 512, unterstützt. Größere Werte werden möglicherweise unterstützt.
• Tag::MIN_MAC_LENGTH: Gibt die Mindestlänge von MACs an, die mit diesem Schlüssel generiert oder verifiziert werden können. Der Wert ist ein Vielfaches von 8 und mindestens 64.
• Tag::DIGEST gibt den Digest-Algorithmus für den Schlüssel an. Es muss genau ein Digest angegeben werden. Andernfalls wird ErrorCode::UNSUPPORTED_DIGEST zurückgegeben. Wenn der Hashwert vom Trustlet nicht unterstützt wird, gib ErrorCode::UNSUPPORTED_DIGEST zurück.

Wichtige Merkmale

Wenn das Argument „characteristics“ nicht NULL ist, gibt generateKey die Eigenschaften des neu generierten Schlüssels zurück, die entsprechend in Listen für hardware- und softwaregestützte Schlüssel unterteilt sind. Eine Beschreibung dazu, welche Merkmale in welche Liste gehören, finden Sie unter getKeyCharacteristics. Die zurückgegebenen Merkmale umfassen alle für die Schlüsselgenerierung angegebenen Parameter mit Ausnahme von Tag::APPLICATION_ID und Tag::APPLICATION_DATA. Wenn diese Tags in den Schlüsselparametern enthalten waren, werden sie aus den zurückgegebenen Merkmalen entfernt, damit ihre Werte nicht durch Prüfung des zurückgegebenen Schlüssel-Blobs ermittelt werden können. Sie sind jedoch kryptografisch an den Schlüssel-Blob gebunden. Wenn also bei der Verwendung des Schlüssels nicht die richtigen Werte angegeben werden, schlägt die Verwendung fehl. Ebenso ist Tag::ROOT_OF_TRUST kryptografisch an den Schlüssel gebunden, kann aber beim Erstellen oder Importieren des Schlüssels nicht angegeben werden und wird nie zurückgegeben.

Zusätzlich zu den angegebenen Tags fügt das Trustlet Tag::ORIGIN mit dem Wert KeyOrigin::GENERATED hinzu. Wenn der Schlüssel rollback-resistent ist, wird auch Tag::ROLLBACK_RESISTANT hinzugefügt.

Rollback-Sperre

Rollback-Resistenz bedeutet, dass ein Schlüssel, der mit deleteKey oder deleteAllKeys gelöscht wird, durch sichere Hardware garantiert nie wieder verwendet werden kann. Bei Implementierungen ohne Rollback-Resistenz wird generiertes oder importiertes Schlüsselmaterial in der Regel als Schlüssel-Blob, also in verschlüsselter und authentifizierter Form, an den Aufrufer zurückgegeben. Wenn der Schlüsselspeicher den Schlüssel-Blob löscht, ist der Schlüssel nicht mehr verfügbar. Ein Angreifer, der es zuvor geschafft hat, das Schlüsselmaterial abzurufen, kann es jedoch möglicherweise auf dem Gerät wiederherstellen.

Ein Schlüssel ist rollbacksicher, wenn die sichere Hardware dafür sorgt, dass gelöschte Schlüssel später nicht wiederhergestellt werden können. Dazu werden in der Regel zusätzliche Schlüsselmetadaten an einem sicheren Ort gespeichert, der von einem Angreifer nicht manipuliert werden kann. Auf Mobilgeräten wird dafür in der Regel der Mechanismus „Replay Protected Memory Blocks“ (RPMB) verwendet. Da die Anzahl der Schlüssel, die erstellt werden können, im Grunde unbegrenzt ist und der für die Rollback-Resistenz verwendete vertrauenswürdige Speicher möglicherweise begrenzt ist, muss diese Methode auch dann erfolgreich sein, wenn für den neuen Schlüssel keine Rollback-Resistenz bereitgestellt werden kann. In diesem Fall sollte Tag::ROLLBACK_RESISTANT nicht zu den Hauptmerkmalen hinzugefügt werden.

getKeyCharacteristics

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als get_key_characteristics eingeführt und in Keymaster 3 umbenannt.

Gibt Parameter und Autorisierungen zurück, die mit dem angegebenen Schlüssel verknüpft sind. Sie werden in zwei Gruppen unterteilt: hardwaregestützt und softwaregestützt. Die Beschreibung gilt gleichermaßen für die Listen der wichtigsten Merkmale, die von generateKey und importKey zurückgegeben werden.

Wenn Tag::APPLICATION_ID bei der Schlüsselgenerierung oder dem Import angegeben wurde, wird dieser Wert dieser Methode im Argument clientId übergeben. Andernfalls gibt die Methode ErrorCode::INVALID_KEY_BLOB zurück. Wenn Tag::APPLICATION_DATA während der Generierung oder des Imports angegeben wurde, wird dieser Wert auch für diese Methode im appData-Argument verwendet.

Die von dieser Methode zurückgegebenen Merkmale beschreiben den Typ und die Verwendung des angegebenen Schlüssels vollständig.

Die allgemeine Regel, um zu entscheiden, ob ein bestimmtes Tag in die Liste der hardwaregeschützten oder softwaregeschützten Tags gehört, lautet: Wenn die Bedeutung des Tags vollständig durch sichere Hardware gewährleistet ist, wird es hardwareseitig erzwungen. Andernfalls wird sie durch Software erzwungen. Nachfolgend finden Sie eine Liste bestimmter Tags, bei denen die korrekte Zuordnung möglicherweise unklar ist:

• Tag::ALGORITHM, Tag::KEY_SIZE und Tag::RSA_PUBLIC_EXPONENT sind inhärente Eigenschaften des Schlüssels. Für jeden hardwaregeschützten Schlüssel sind diese Tags in der Liste der hardwareerzwungenen Tags enthalten.
• Tag::DIGEST-Werte, die von der sicheren Hardware unterstützt werden, werden in die Liste der von der Hardware unterstützten Werte aufgenommen. Nicht unterstützte Digests werden in die Liste der softwaregestützten Digests aufgenommen.
• Tag::PADDING-Werte werden in der Regel in die Liste der hardwareunterstützten Werte aufgenommen, es sei denn, es besteht die Möglichkeit, dass ein bestimmter Padding-Modus von der Software ausgeführt werden muss. In diesem Fall werden sie in die Liste der softwaregestützten Richtlinien aufgenommen. Diese Möglichkeit besteht bei RSA-Schlüsseln, die PSS- oder OAEP-Padding mit Digest-Algorithmen zulassen, die von der sicheren Hardware nicht unterstützt werden.
• Tag::USER_SECURE_ID und Tag::USER_AUTH_TYPE werden nur dann hardwareseitig erzwungen, wenn die Nutzerauthentifizierung hardwareseitig erzwungen wird. Dazu müssen sowohl das Keymaster-Trustlet als auch das entsprechende Authentifizierungs-Trustlet sicher sein und einen geheimen HMAC-Schlüssel teilen, der zum Signieren und Validieren von Authentifizierungstokens verwendet wird. Weitere Informationen finden Sie auf der Seite Authentifizierung.
• Für die Tags Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME und Tag::USAGE_EXPIRE_DATETIME ist Zugriff auf eine nachweislich korrekte Uhr erforderlich. Die meisten sicheren Hardwaregeräte haben nur Zugriff auf Zeitinformationen, die vom unsicheren Betriebssystem bereitgestellt werden. Das bedeutet, dass die Tags softwareseitig erzwungen werden.
• Tag::ORIGIN ist immer in der Hardwareliste für hardwaregebundene Schlüssel enthalten. Anhand seiner Anwesenheit in dieser Liste erkennen höhere Schichten, dass ein Schlüssel hardwaregestützt ist.

importKey

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als import_key eingeführt und in Keymaster 3 umbenannt.

Importiert Schlüsselmaterial in die Keymaster-Hardware. Die Parameter für die Schlüsseldefinition und die Ausgabemerkmale werden wie bei generateKey behandelt, mit folgenden Ausnahmen:

• Tag::KEY_SIZE und Tag::RSA_PUBLIC_EXPONENT (nur für RSA-Schlüssel) sind in den Eingabeparametern nicht erforderlich. Wenn keine Werte angegeben werden, leitet das Trustlet die Werte aus dem bereitgestellten Schlüsselmaterial ab und fügt den wichtigsten Merkmalen entsprechende Tags und Werte hinzu. Wenn die Parameter angegeben sind, werden sie vom Trustlet anhand des Schlüsselmaterials validiert. Im Fall einer Abweichung gibt die Methode ErrorCode::IMPORT_PARAMETER_MISMATCH zurück.
• Der zurückgegebene Wert Tag::ORIGIN hat denselben Wert wie KeyOrigin::IMPORTED.

exportKey

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als export_key eingeführt und in Keymaster 3 umbenannt.

Exportiert einen öffentlichen Schlüssel aus einem RSA- oder EC-Schlüsselpaar von Keymaster.

Wenn Tag::APPLICATION_ID bei der Schlüsselgenerierung oder dem Import angegeben wurde, wird dieser Wert dieser Methode im Argument clientId übergeben. Andernfalls gibt die Methode ErrorCode::INVALID_KEY_BLOB zurück. Wenn Tag::APPLICATION_DATA während der Generierung oder des Imports angegeben wurde, wird dieser Wert auch für diese Methode im Argument appData verwendet.

deleteKey

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als delete_key eingeführt und in Keymaster 3 umbenannt.

Löscht den angegebenen Schlüssel. Diese Methode ist optional und wird nur von Keymaster-Modulen implementiert, die Rollback-Resistenz bieten.

deleteAllKeys

Version:1, 2, 3

Diese Funktion wurde in Keymaster 1 als delete_all_keys eingeführt und in Keymaster 3 umbenannt.

Alle Schlüssel werden gelöscht. Diese Methode ist optional und wird nur von Keymaster-Modulen implementiert, die Rollback-Resistenz bieten.

destroyAttestationIds

Version:3

Mit der Methode destroyAttestationIds() können Sie die neue (optionale, aber dringend empfohlene) Funktion ID-Attestierung dauerhaft deaktivieren. Wenn die TEE nicht dafür sorgen kann, dass die ID-Attestierung nach dem Aufruf dieser Methode dauerhaft deaktiviert wird, darf die ID-Attestierung nicht implementiert werden. In diesem Fall führt diese Methode nichts aus und gibt ErrorCode::UNIMPLEMENTED zurück. Wenn die Ausweisbestätigung unterstützt wird, muss diese Methode implementiert und alle zukünftigen Versuche zur Ausweisbestätigung dauerhaft deaktiviert werden. Die Methode kann beliebig oft aufgerufen werden. Wenn die Bestätigung der Identität bereits dauerhaft deaktiviert ist, führt die Methode nichts aus und gibt ErrorCode::OK zurück.

Die einzigen Fehlercodes, die diese Methode zurückgeben kann, sind ErrorCode::UNIMPLEMENTED (wenn die ID-Attestierung nicht unterstützt wird), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED oder einer der Fehlercodes, die auf eine Kommunikationsstörung mit der sicheren Hardware hinweisen.

anfangen

Version:1, 2, 3

Beginnt einen kryptografischen Vorgang mit dem angegebenen Schlüssel, dem angegebenen Zweck und den angegebenen Parametern (sofern zutreffend) und gibt einen Vorgangs-Handle zurück, der mit update und finish verwendet wird, um den Vorgang abzuschließen. Der Vorgangs-Handle wird auch als Bestätigungstoken bei authentifizierten Vorgängen verwendet und ist bei solchen Vorgängen im Feld challenge des Authentifizierungstokens enthalten.

Eine Keymaster-Implementierung unterstützt mindestens 16 gleichzeitige Vorgänge. Der Keystore verwendet bis zu 15 Schlüssel, sodass einer für die Passwortverschlüsselung durch vold übrig bleibt. Wenn im Keystore 15 Vorgänge ausgeführt werden (begin wurde aufgerufen, finish oder abort jedoch nicht) und eine Anfrage zum Starten eines 16. Vorgangs eingeht, wird abort für den am wenigsten verwendeten Vorgang aufgerufen, um die Anzahl der aktiven Vorgänge auf 14 zu reduzieren, bevor begin aufgerufen wird, um den neu angeforderten Vorgang zu starten.

Wenn Tag::APPLICATION_ID oder Tag::APPLICATION_DATA bei der Schlüsselgenerierung oder dem Import angegeben wurden, enthalten Aufrufe von begin diese Tags mit den ursprünglich angegebenen Werten im inParams-Argument dieser Methode.

Autorisierung erzwingen

Bei dieser Methode werden die folgenden Schlüsselautorisierungen vom Trustlet erzwungen, wenn die Implementierung sie in die hardwaregestützten Merkmale aufgenommen hat und der Vorgang kein öffentlicher Schlüsselvorgang ist. Öffentliche Schlüsseloperationen, also KeyPurpose::ENCRYPT und KeyPurpose::VERIFY, mit RSA- oder EC-Schlüsseln dürfen auch dann erfolgreich sein, wenn die Autorisierungsanforderungen nicht erfüllt sind.

• Tag::PURPOSE: Der im begin()-Aufruf angegebene Zweck muss mit einem der Zwecke in den Schlüsselautorisierungen übereinstimmen, es sei denn, der angeforderte Vorgang ist ein öffentlicher Schlüsselvorgang. Wenn der angegebene Zweck nicht übereinstimmt und der Vorgang kein öffentlicher Schlüsselvorgang ist, gibt begin ErrorCode::UNSUPPORTED_PURPOSE zurück. Public-Key-Vorgänge sind asymmetrische Verschlüsselungs- oder Überprüfungsvorgänge.
• Tag::ACTIVE_DATETIME kann nur erzwungen werden, wenn eine vertrauenswürdige UTC-Zeitquelle verfügbar ist. Wenn das aktuelle Datum und die aktuelle Uhrzeit vor dem Tag-Wert liegen, gibt die Methode ErrorCode::KEY_NOT_YET_VALID zurück.
• Tag::ORIGINATION_EXPIRE_DATETIME kann nur erzwungen werden, wenn eine vertrauenswürdige UTC-Zeitquelle verfügbar ist. Wenn das aktuelle Datum und die aktuelle Uhrzeit später als der Tag-Wert sind und der Zweck KeyPurpose::ENCRYPT oder KeyPurpose::SIGN ist, gibt die Methode ErrorCode::KEY_EXPIRED zurück.
• Tag::USAGE_EXPIRE_DATETIME kann nur erzwungen werden, wenn eine vertrauenswürdige UTC-Zeitquelle verfügbar ist. Wenn das aktuelle Datum und die aktuelle Uhrzeit später als der Tag-Wert sind und der Zweck KeyPurpose::DECRYPT oder KeyPurpose::VERIFY ist, gibt die Methode ErrorCode::KEY_EXPIRED zurück.
• Tag::MIN_SECONDS_BETWEEN_OPS wird mit einem vertrauenswürdigen relativen Timer verglichen, der die letzte Verwendung des Schlüssels angibt. Wenn die letzte Nutzungszeit plus der Tag-Wert kleiner als die aktuelle Zeit ist, gibt die Methode ErrorCode::KEY_RATE_LIMIT_EXCEEDED zurück. Wichtige Implementierungsdetails finden Sie in der Tag-Beschreibung.
• Tag::MAX_USES_PER_BOOT wird mit einem sicheren Zähler verglichen, der die Verwendung des Schlüssels seit dem Start aufzeichnet. Wenn die Anzahl der bisherigen Verwendungen den Tag-Wert überschreitet, gibt die Methode ErrorCode::KEY_MAX_OPS_EXCEEDED zurück.
• Tag::USER_SECURE_ID wird mit dieser Methode nur erzwungen, wenn der Schlüssel auch Tag::AUTH_TIMEOUT enthält. Wenn der Schlüssel beides hat, muss diese Methode eine gültige Tag::AUTH_TOKEN in inParams erhalten. Damit das Authentifizierungstoken gültig ist, müssen alle folgenden Bedingungen erfüllt sein:
  • Das HMAC-Feld wird korrekt validiert.
  • Mindestens einer der Tag::USER_SECURE_ID-Werte aus dem Schlüssel stimmt mit mindestens einem der Secure-ID-Werte im Token überein.
  • Der Schlüssel hat einen Tag::USER_AUTH_TYPE, der mit dem Authentifizierungstyp im Token übereinstimmt.

  Wenn eine dieser Bedingungen nicht erfüllt ist, gibt die Methode ErrorCode::KEY_USER_NOT_AUTHENTICATED zurück.

• Tag::CALLER_NONCE ermöglicht es dem Anrufer, einen Nonce oder Initialisierungsvektor (IV) anzugeben. Wenn der Schlüssel dieses Tag nicht hat, der Aufrufer aber Tag::NONCE für diese Methode angegeben hat, wird ErrorCode::CALLER_NONCE_PROHIBITED zurückgegeben.
• Tag::BOOTLOADER_ONLY gibt an, dass nur der Bootloader den Schlüssel verwenden kann. Wenn diese Methode nach Abschluss der Ausführung des Bootloaders mit einem Schlüssel aufgerufen wird, der nur für den Bootloader gilt, wird ErrorCode::INVALID_KEY_BLOB zurückgegeben.

RSA-Schlüssel

Für alle RSA-Schlüsselvorgänge wird in inParams genau ein Padding-Modus angegeben. Wenn kein Wert angegeben oder der Wert mehrmals angegeben wird, gibt die Methode ErrorCode::UNSUPPORTED_PADDING_MODE zurück.

Für RSA-Signatur- und ‑Verifizierungsvorgänge ist ein Hashwert erforderlich, ebenso wie für RSA-Verschlüsselungs- und ‑Entschlüsselungsvorgänge mit OAEP-Padding-Modus. In diesen Fällen gibt der Aufrufer genau einen Digest in inParams an. Wenn das Argument nicht oder mehrmals angegeben wird, gibt die Methode ErrorCode::UNSUPPORTED_DIGEST zurück.

Für Operationen mit privaten Schlüsseln (KeyPurpose::DECYPT und KeyPurpose::SIGN) ist eine Autorisierung von Hashwert und Padding erforderlich. Das bedeutet, dass die Schlüsselautorisierungen die angegebenen Werte enthalten müssen. Andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST oder ErrorCode::INCOMPATIBLE_PADDING zurück. Öffentliche Schlüsselvorgänge (KeyPurpose::ENCRYPT und KeyPurpose::VERIFY) sind mit nicht autorisiertem Hashwert oder Padding zulässig.

Mit Ausnahme von PaddingMode::NONE sind alle RSA-Padding-Modi nur für bestimmte Zwecke geeignet. Insbesondere werden mit PaddingMode::RSA_PKCS1_1_5_SIGN und PaddingMode::RSA_PSS nur Signatur und Überprüfung unterstützt, während PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT und PaddingMode::RSA_OAEP nur Verschlüsselung und Entschlüsselung unterstützen. Die Methode gibt ErrorCode::UNSUPPORTED_PADDING_MODE zurück, wenn der angegebene Modus den angegebenen Zweck nicht unterstützt.

Es gibt einige wichtige Wechselwirkungen zwischen Padding-Modi und Digests:

• PaddingMode::NONE gibt an, dass ein reiner RSA-Vorgang ausgeführt wird. Bei der Signatur oder Überprüfung wird Digest::NONE für den Hashwert angegeben. Für die unverpaddede Verschlüsselung oder Entschlüsselung ist kein Hashwert erforderlich.
• Für PaddingMode::RSA_PKCS1_1_5_SIGN-Padding ist ein Hashwert erforderlich. Der Digest kann Digest::NONE sein. In diesem Fall kann die Keymaster-Implementierung keine ordnungsgemäße PKCS#1-v1.5-Signaturstruktur erstellen, da die DigestInfo-Struktur nicht hinzugefügt werden kann. Stattdessen wird 0x00 || 0x01 || PS || 0x00 || M erstellt, wobei M die bereitgestellte Nachricht und PS der Padding-String ist. Die Größe des RSA-Schlüssels muss mindestens 11 Byte größer als die Nachricht sein. Andernfalls gibt die Methode ErrorCode::INVALID_INPUT_LENGTH zurück.
• Für PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT-Padding ist kein Digest erforderlich.
• Für das PaddingMode::RSA_PSS-Padding ist ein Hashwert erforderlich, der nicht Digest::NONE sein darf. Wenn Digest::NONE angegeben ist, gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück. Außerdem muss die Größe des RSA-Schlüssels mindestens 2 + D Byte größer als die Ausgabegröße des Hashwerts sein. Dabei ist D die Größe des Hashwerts in Byte. Andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück. Die Salzgröße ist D.
• Für das PaddingMode::RSA_OAEP-Padding ist ein Hashwert erforderlich, der nicht Digest::NONE sein darf. Wenn Digest::NONE angegeben ist, gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück.

EC-Schlüssel

Bei EC-Schlüsseloperationen wird in inParams genau ein Padding-Modus angegeben. Wenn der Wert nicht angegeben oder mehrmals angegeben wird, gibt die Methode ErrorCode::UNSUPPORTED_PADDING_MODE zurück.

Für Operationen mit privaten Schlüsseln (KeyPurpose::SIGN) ist eine Autorisierung von Hashwert und Padding erforderlich. Das bedeutet, dass die Schlüsselautorisierungen die angegebenen Werte enthalten müssen. Andernfalls wird ErrorCode::INCOMPATIBLE_DIGEST zurückgegeben. Öffentliche Schlüsselvorgänge (KeyPurpose::VERIFY) sind mit nicht autorisiertem Digest oder Padding zulässig.

AES-Schlüssel

Für AES-Schlüsselvorgänge wird in inParams genau ein Blockmodus und ein Padding-Modus angegeben. Wenn einer der Werte nicht oder mehrmals angegeben ist, geben Sie ErrorCode::UNSUPPORTED_BLOCK_MODE oder ErrorCode::UNSUPPORTED_PADDING_MODE zurück. Die angegebenen Modi müssen vom Schlüssel autorisiert sein, andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_BLOCK_MODE oder ErrorCode::INCOMPATIBLE_PADDING_MODE zurück.

Wenn der Blockierungsmodus BlockMode::GCM ist, wird für inParams Tag::MAC_LENGTH angegeben und der angegebene Wert ist ein Vielfaches von 8, das nicht größer als 128 oder kleiner als der Wert von Tag::MIN_MAC_LENGTH in den Schlüsselautorisierungen ist. Gib für MAC-Längen größer als 128 oder nicht durch 8 teilbare Werte ErrorCode::UNSUPPORTED_MAC_LENGTH zurück. Geben Sie für Werte, die kürzer als die Mindestlänge des Schlüssels sind, ErrorCode::INVALID_MAC_LENGTH zurück.

Wenn der Blockmodus BlockMode::GCM oder BlockMode::CTR ist, muss der angegebene Padding-Modus PaddingMode::NONE sein. Für BlockMode::ECB oder BlockMode::CBC kann der Modus PaddingMode::NONE oder PaddingMode::PKCS7 sein. Wenn der Padding-Modus diese Bedingungen nicht erfüllt, gib ErrorCode::INCOMPATIBLE_PADDING_MODE zurück.

Wenn der Blockmodus BlockMode::CBC, BlockMode::CTR oder BlockMode::GCM ist, ist ein Initialisierungsvektor oder eine Nonce erforderlich. In den meisten Fällen sollten die Aufrufer keine IV oder Nonce angeben. In diesem Fall generiert die Keymaster-Implementierung eine zufällige IV oder Nonce und gibt sie mit Tag::NONCE in outParams zurück. CBC- und CTR-IVs haben eine Größe von 16 Byte. GCM-Nonces haben 12 Byte. Wenn die Schlüsselautorisierungen Tag::CALLER_NONCE enthalten, kann der Aufrufer eine IV oder einen Nonce mit Tag::NONCE in inParams angeben. Wenn ein Nonce angegeben wird, obwohl Tag::CALLER_NONCE nicht autorisiert ist, gib ErrorCode::CALLER_NONCE_PROHIBITED zurück. Wenn für Tag::CALLER_NONCE kein Nonce angegeben ist, generiere einen zufälligen IV/Nonce.

HMAC-Schlüssel

Bei HMAC-Schlüsselvorgängen wird Tag::MAC_LENGTH in inParams angegeben. Der angegebene Wert muss ein Vielfaches von 8 sein, das nicht größer als die Länge des Hashwerts und nicht kleiner als der Wert von Tag::MIN_MAC_LENGTH in den Schlüsselautorisierungen ist. Gib für MAC-Längen, die länger als die Digest-Länge sind oder kein Vielfaches von 8 sind, ErrorCode::UNSUPPORTED_MAC_LENGTH zurück. Wenn der Wert kürzer als die Mindestlänge des Schlüssels ist, wird ErrorCode::INVALID_MAC_LENGTH zurückgegeben.

Aktualisieren

Version:1, 2, 3

Stellt Daten für die Verarbeitung in einem laufenden Vorgang bereit, der mit begin gestartet wurde. Der Vorgang wird durch den Parameter operationHandle angegeben.

Um die Pufferverwaltung flexibler zu gestalten, können bei der Implementierung dieser Methode weniger Daten als bereitgestellt verbraucht werden. Der Aufrufer ist dafür verantwortlich, die restlichen Daten in nachfolgenden Aufrufen zu übergeben. Die Menge der verbrauchten Eingabe wird im Parameter inputConsumed zurückgegeben. Bei Implementierungen wird immer mindestens ein Byte verbraucht, es sei denn, der Vorgang kann keine weiteren Bytes verarbeiten. Wenn mehr als null Byte angegeben und null Byte verbraucht werden, betrachten die Aufrufer dies als Fehler und brechen den Vorgang ab.

Implementierungen können auch festlegen, wie viele Daten nach der Aktualisierung zurückgegeben werden sollen. Dies ist nur für Verschlüsselungs- und Entschlüsselungsvorgänge relevant, da bei der Signatur und Überprüfung bis zu finish keine Daten zurückgegeben werden. Gib Daten so früh wie möglich zurück, anstatt sie zu puffern.

Fehlerbehandlung

Wenn diese Methode einen anderen Fehlercode als ErrorCode::OK zurückgibt, wird der Vorgang abgebrochen und der Vorgangs-Handle ungültig. Bei jeder zukünftigen Verwendung des Alias mit dieser Methode, finish oder abort, wird ErrorCode::INVALID_OPERATION_HANDLE zurückgegeben.

Autorisierung erzwingen

Die Erzwingung der Schlüsselautorisierung erfolgt hauptsächlich in begin. Eine Ausnahme ist der Fall, wenn der Schlüssel:

• Hat mindestens eine Tag::USER_SECURE_IDs
• Hat kein Tag::AUTH_TIMEOUT

In diesem Fall ist für den Schlüssel eine Autorisierung pro Vorgang erforderlich und die Updatemethode erhält ein Tag::AUTH_TOKEN im inParams-Argument. HMAC prüft, ob das Token gültig ist und eine übereinstimmende sichere Nutzer-ID enthält, mit der Tag::USER_AUTH_TYPE des Schlüssels übereinstimmt und den Vorgangs-Handle des aktuellen Vorgangs im Feld challenge enthält. Wenn diese Bedingungen nicht erfüllt sind, gib ErrorCode::KEY_USER_NOT_AUTHENTICATED zurück.

Der Aufrufer stellt das Authentifizierungstoken für jeden Aufruf von update und finish bereit. Das Token muss in der Implementierung nur einmal validiert werden.

RSA-Schlüssel

Bei Signatur- und Überprüfungsvorgängen mit Digest::NONE kann mit dieser Methode der gesamte Block in einem einzigen Update signiert oder überprüft werden. Es kann nicht nur ein Teil des Blocks belegt werden. Wenn der Aufrufer die Daten jedoch in mehreren Aktualisierungen bereitstellt, wird dies von dieser Methode akzeptiert. Wenn der Aufrufer mehr Daten zum Signieren angibt, als verwendet werden können (die Datenlänge überschreitet die RSA-Schlüsselgröße), gib ErrorCode::INVALID_INPUT_LENGTH zurück.

ECDSA-Schlüssel

Bei Signatur- und Überprüfungsvorgängen mit Digest::NONE kann mit dieser Methode der gesamte Block in einem einzigen Update signiert oder überprüft werden. Mit dieser Methode kann nicht nur ein Teil des Blocks belegt werden.

Wenn der Aufrufer die Daten jedoch in mehreren Aktualisierungen bereitstellt, wird dies von dieser Methode akzeptiert. Wenn der Aufrufer mehr Daten zum Signieren angibt, als verwendet werden können, werden die Daten ohne Benachrichtigung abgeschnitten. (Dies unterscheidet sich von der Verarbeitung von überschüssigen Daten bei ähnlichen RSA-Vorgängen. Der Grund dafür ist die Kompatibilität mit älteren Clients.)

AES-Schlüssel

Der AES-GCM-Modus unterstützt zugehörige Authentifizierungsdaten, die über das Tag Tag::ASSOCIATED_DATA im inParams-Argument bereitgestellt werden. Die zugehörigen Daten können in wiederholten Aufrufen bereitgestellt werden (wichtig, wenn die Daten zu groß sind, um sie in einem einzigen Block zu senden), gehen aber immer den Daten voraus, die verschlüsselt oder entschlüsselt werden sollen. Ein Updateaufruf kann sowohl zugehörige Daten als auch Daten zum Verschlüsseln/Entschlüsseln empfangen. Nachfolgende Updates können jedoch keine zugehörigen Daten enthalten. Wenn der Aufrufer nach einem Aufruf, der Daten zum Verschlüsseln/Entschlüsseln enthält, zugehörige Daten für einen Update-Aufruf angibt, gib ErrorCode::INVALID_TAG zurück.

Bei der GCM-Verschlüsselung wird das Tag mit finish an den Geheimtext angehängt. Bei der Entschlüsselung sind die letzten Tag::MAC_LENGTH Byte der Daten, die dem letzten Update-Aufruf übergeben wurden, das Tag. Da bei einer bestimmten Aufrufung von update nicht bekannt ist, ob es sich um die letzte Aufrufung handelt, werden alle Daten außer der Tag-Länge verarbeitet und die möglichen Tag-Daten während finish im Puffer gespeichert.

Abschließen

Version:1, 2, 3

Beendet einen laufenden Vorgang, der mit begin gestartet wurde, und verarbeitet alle noch nicht verarbeiteten Daten, die von update-Instanzen bereitgestellt wurden.

Diese Methode wird in einem Vorgang als letztes aufgerufen, sodass alle verarbeiteten Daten zurückgegeben werden.

Unabhängig davon, ob der Vorgang erfolgreich abgeschlossen wird oder einen Fehler zurückgibt, wird er durch diese Methode beendet und der angegebene Vorgangs-Handle ungültig. Bei jeder zukünftigen Verwendung des Alias mit dieser Methode oder update oder abort wird ErrorCode::INVALID_OPERATION_HANDLE zurückgegeben.

Signaturvorgänge geben die Signatur als Ausgabe zurück. Bei Prüfvorgängen wird die Signatur im Parameter signature akzeptiert und es wird keine Ausgabe zurückgegeben.

Autorisierung erzwingen

Die Erzwingung der Schlüsselautorisierung erfolgt hauptsächlich in begin. Eine Ausnahme ist der Fall, in dem der Schlüssel beide Merkmale aufweist:

• Hat mindestens eine Tag::USER_SECURE_IDs
• Hat kein Tag::AUTH_TIMEOUT

In diesem Fall ist für den Schlüssel eine Autorisierung pro Vorgang erforderlich und die Updatemethode erhält ein Tag::AUTH_TOKEN im inParams-Argument. HMAC prüft, ob das Token gültig ist und eine übereinstimmende sichere Nutzer-ID enthält, mit dem Tag::USER_AUTH_TYPE des Schlüssels übereinstimmt und den Vorgangs-Handle des aktuellen Vorgangs im Feld challenge enthält. Wenn diese Bedingungen nicht erfüllt sind, gib ErrorCode::KEY_USER_NOT_AUTHENTICATED zurück.

Der Aufrufer stellt das Authentifizierungstoken für jeden Aufruf von update und finish bereit. Das Token muss in der Implementierung nur einmal validiert werden.

RSA-Schlüssel

Je nach Padding-Modus gelten einige zusätzliche Anforderungen:

• PaddingMode::NONE. Bei nicht ausgefüllten Signatur- und Verschlüsselungsvorgängen werden die angegebenen Daten vor der Signatur/Verschlüsselung links mit Nullen aufgefüllt, wenn sie kürzer als der Schlüssel sind. Wenn die Daten dieselbe Länge wie der Schlüssel haben, aber numerisch größer sind, geben Sie ErrorCode::INVALID_ARGUMENT zurück. Für die Überprüfung und Entschlüsselung müssen die Daten genau so lang sein wie der Schlüssel. Andernfalls wird ErrorCode::INVALID_INPUT_LENGTH. zurückgegeben.
• PaddingMode::RSA_PSS. Bei PSS-ausgeglichenen Signaturvorgängen hat das PSS-Salz die Größe des Nachrichten-Digests und wird zufällig generiert. Der mit Tag::DIGEST in inputParams auf begin angegebene Digest wird als PSS-Digest-Algorithmus und als MGF1-Digest-Algorithmus verwendet.
• PaddingMode::RSA_OAEP. Der mit Tag::DIGEST in inputParams auf begin angegebene Digest wird als OAEP-Digest-Algorithmus und SHA1 als MGF1-Digest-Algorithmus verwendet.

ECDSA-Schlüssel

Wenn die für die unummantelte Signatur oder Überprüfung angegebenen Daten zu lang sind, kürzen Sie sie.

AES-Schlüssel

Je nach Blockierungsmodus gelten einige zusätzliche Bedingungen:

• BlockMode::ECB oder BlockMode::CBC. Wenn „padding“ PaddingMode::NONE ist und die Datenlänge kein Vielfaches der AES-Blockgröße ist, geben Sie ErrorCode::INVALID_INPUT_LENGTH zurück. Wenn „Padding“ auf PaddingMode::PKCS7 festgelegt ist, fügen Sie den Daten Padding gemäß der PKCS#7-Spezifikation hinzu. Hinweis: PKCS#7 empfiehlt, einen zusätzlichen Padding-Block hinzuzufügen, wenn die Daten ein Vielfaches der Blocklänge sind.
• BlockMode::GCM. Berechnen Sie während der Verschlüsselung nach der Verarbeitung des gesamten Klartexts das Tag (Tag::MAC_LENGTH Byte) und hängen Sie es an den zurückgegebenen Geheimtext an. Verarbeiten Sie bei der Entschlüsselung die letzten Tag::MAC_LENGTH Byte als Tag. Wenn die Tag-Bestätigung fehlschlägt, gib ErrorCode::VERIFICATION_FAILED zurück.

abort

Version:1, 2, 3

Bricht den laufenden Vorgang ab. Gib nach dem Abbruchsaufruf ErrorCode::INVALID_OPERATION_HANDLE für jede nachfolgende Verwendung des bereitgestellten Vorgangs-Handles mit update, finish oder abort zurück.

get_supported_algorithms

Version:1

Liste der Algorithmen, die von der Keymaster-Hardwareimplementierung unterstützt werden. Eine Softwareimplementierung gibt eine leere Liste zurück. Eine hybride Implementierung gibt eine Liste zurück, die nur die Algorithmen enthält, die von der Hardware unterstützt werden.

Keymaster 1-Implementierungen unterstützen RSA, EC, AES und HMAC.

get_supported_block_modes

Version:1

Gibt die Liste der AES-Blockmodi zurück, die von der Keymaster-Hardwareimplementierung für einen bestimmten Algorithmus und Zweck unterstützt werden.

Für RSA, EC und HMAC, die keine Blockverschlüsselungen sind, gibt die Methode für alle gültigen Zwecke eine leere Liste zurück. Bei ungültigen Zwecken sollte die Methode ErrorCode::INVALID_PURPOSE zurückgeben.

Keymaster 1-Implementierungen unterstützen ECB, CBC, CTR und GCM für die AES-Verschlüsselung und ‑Entschlüsselung.

get_supported_padding_modes

Version:1

Gibt die Liste der von der Keymaster-Hardwareimplementierung für einen bestimmten Algorithmus und Zweck unterstützten Padding-Modi zurück.

HMAC und EC kennen kein Padding. Daher gibt die Methode für alle gültigen Zwecke eine leere Liste zurück. Bei ungültigen Zwecken sollte die Methode ErrorCode::INVALID_PURPOSE zurückgeben.

Für RSA werden bei Keymaster 1-Implementierungen folgende Optionen unterstützt:

• Unpadded-Verschlüsselung, -Entschlüsselung, -Signatur und -Überprüfung. Bei der unverschlüsselten Verschlüsselung und Signatur muss die Nachricht links mit Nullen aufgefüllt werden, wenn sie kürzer als der öffentliche Modulus ist. Bei der Entschlüsselung und Überprüfung ohne Padding muss die Eingabelänge der Größe des öffentlichen Moduls entsprechen.
• PKCS#1-Padding-Modi für Verschlüsselung und Signatur (Version 1.5)
• PSS mit einer Mindestsalzlänge von 20
• OAEP

Für AES im ECB- und CBC-Modus unterstützen Keymaster 1-Implementierungen kein Padding und PKCS#7-Padding. Die Modi CTR und GCM unterstützen nur kein Padding.

get_supported_digests

Version:1

Gibt die Liste der Hash-Modi zurück, die von der Keymaster-Hardwareimplementierung für einen bestimmten Algorithmus und Zweck unterstützt werden.

Da keine AES-Modi die Hash-Technologie unterstützen oder erfordern, gibt die Methode aus berechtigten Gründen eine leere Liste zurück.

Keymaster 1-Implementierungen können eine Teilmenge der definierten Hash-Werte implementieren. Implementierungen bieten SHA-256 und können MD5, SHA1, SHA-224, SHA-256, SHA384 und SHA512 (die gesamte Reihe der definierten Hash-Werte) bereitstellen.

get_supported_import_formats

Version:1

Gibt die Liste der Importformate zurück, die von der Keymaster-Hardwareimplementierung eines bestimmten Algorithmus unterstützt werden.

Keymaster 1-Implementierungen unterstützen das PKCS#8-Format (ohne Passwortschutz) für den Import von RSA- und EC-Schlüsselpaaren sowie den RAW-Import von AES- und HMAC-Schlüsselmaterial.

get_supported_export_formats

Version:1

Gibt die Liste der Exportformate zurück, die von der Keymaster-Hardwareimplementierung eines bestimmten Algorithmus unterstützt werden.

Keymaster1-Implementierungen unterstützen das X.509-Format für den Export von RSA- und EC-öffentlichen Schlüsseln. Der Export von privaten oder asymmetrischen Schlüsseln wird nicht unterstützt.

Verlaufsfunktionen

Keymaster 0

Die folgenden Funktionen gehören zur ursprünglichen Keymaster 0-Definition. Sie waren in der Keymaster 1-Struktur „keymaster1_device_t“ vorhanden. In Keymaster 1.0 wurden sie jedoch nicht implementiert und ihre Funktionszeigers wurden auf NULL gesetzt.

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

Keymaster 1

Die folgenden Funktionen gehören zur Keymaster 1-Definition, wurden aber in Keymaster 2 zusammen mit den oben aufgeführten Keymaster 0-Funktionen entfernt:

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

Keymaster 2

Die folgenden Funktionen gehören zur Keymaster 2-Definition, wurden aber in Keymaster 3 zusammen mit den oben aufgeführten Keymaster 1-Funktionen entfernt:

• configure