Keymaster-Funktionen

Auf dieser Seite finden Sie Einzelheiten zur Unterstützung von Implementierern von Keymaster Hardware Abstraction Layers (HALs). Es behandelt jede Funktion in der API und die Keymaster-Version, in der diese Funktion verfügbar ist, und beschreibt die Standardimplementierung. Informationen zu Tags finden Sie auf der Seite „Keymaster-Tags“ .

Allgemeine Umsetzungsrichtlinien

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 Aufrufer ist nicht verpflichtet, Platzhalter bereitzustellen. Beispielsweise verwenden einige Schlüsseltypen und -modi möglicherweise keine Werte aus dem inParams Argument, um zu beginnen , sodass der Aufrufer inParams möglicherweise auf NULL setzt oder einen leeren Parametersatz bereitstellt. Aufrufer können auch ungenutzte Parameter bereitstellen und 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 als Wert- oder Konstantenreferenzen übergeben.

Ausgabezeigerparameter

Version : 1, 2

Ähnlich wie Eingabezeigerparameter können nicht verwendete Ausgabezeigerparameter NULL sein. 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 als Wert- oder Konstantenreferenzen übergeben.

API-Missbrauch

Version : 1, 2, 3

Es gibt viele Möglichkeiten, wie Anrufer Anfragen stellen können, die keinen Sinn ergeben oder dumm, aber technisch gesehen 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 IVs oder Nonces, die Generierung von Schlüsseln ohne Zweck (daher nutzlos) und dergleichen sollten von Implementierungen nicht diagnostiziert 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-Keystores, sicherzustellen, dass die Aufrufe an Keymaster-Module sinnvoll und nützlich sind.

Funktionen

getHardwareFeatures

Version : 3

Die neue Methode getHardwareFeatures stellt Clients einige wichtige Merkmale der zugrunde liegenden sicheren Hardware zur Verfügung. Die Methode akzeptiert keine Argumente und gibt vier Werte zurück, allesamt boolesche Werte:

  • isSecure ist true , wenn Schlüssel in sicherer Hardware (TEE usw.) gespeichert sind und diese niemals verlassen.
  • supportsEllipticCurve ist true , wenn die Hardware die Elliptic Curve-Kryptographie mit den NIST-Kurven (P-224, P-256, P-384 und P-521) unterstützt.
  • supportsSymmetricCryptography ist true , wenn die Hardware symmetrische Kryptografie, einschließlich AES und HMAC, unterstützt.
  • supportsAttestation ist true , wenn die Hardware die Generierung von Keymaster-Bescheinigungszertifikaten für öffentliche Schlüssel unterstützt, die mit einem in einer sicheren Umgebung injizierten Schlüssel signiert sind.

Die einzigen Fehlercodes, die diese Methode möglicherweise zurückgibt, sind ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED oder einer der Fehlercodes, die auf einen Fehler bei der Kommunikation 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 ist in Keymaster 3 veraltet, da diese Informationen in Systemeigenschaftendateien verfügbar sind und Herstellerimplementierungen diese Dateien beim Start lesen.

Konfiguriert Keymaster. Diese Methode wird einmal nach dem Öffnen des Geräts und vor seiner Verwendung aufgerufen. 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 anderen zurück 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ügt vom Anrufer bereitgestellte Entropie zum Pool hinzu, der von der Keymaster 1-Implementierung zum Generieren von Zufallszahlen, für Schlüssel, IVs usw. verwendet wird.

Keymaster-Implementierungen müssen die bereitgestellte Entropie sicher in ihren Pool mischen, der auch intern generierte Entropie von einem Hardware-Zufallszahlengenerator enthalten muss. Das Mischen sollte so gehandhabt werden, dass ein Angreifer, der die vollständige Kontrolle entweder über die addRngEntropy bereitgestellten Bits oder die von der Hardware generierten Bits, aber nicht über beide, hat, keinen nicht zu vernachlässigenden 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 die von addRngEntropy bereitgestellten Daten keine Entropie enthalten. Keymaster-Implementierungen geben möglicherweise ErrorCode::INVALID_INPUT_LENGTH zurück, wenn ihnen in einem einzigen Aufruf mehr als 2 KiB an Daten übergeben werden.

generierenSchlüssel

Version : 1, 2, 3

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

Erstellt einen neuen kryptografischen Schlüssel und gibt die zugehörigen Berechtigungen an, die dauerhaft an den Schlüssel gebunden sind. Keymaster-Implementierungen machen es unmöglich, einen Schlüssel in irgendeiner Weise zu verwenden, der nicht mit den zum Zeitpunkt der Generierung angegebenen Berechtigungen übereinstimmt. In Bezug auf Berechtigungen, die die sichere Hardware nicht durchsetzen kann, beschränkt sich die Verpflichtung der sicheren Hardware darauf, sicherzustellen, dass die mit dem Schlüssel verbundenen nicht durchsetzbaren Berechtigungen nicht geändert werden können, sodass jeder Aufruf von getKeyCharacteristics den ursprünglichen Wert zurückgibt. Darüber hinaus weisen die von generateKey zurückgegebenen Merkmale Berechtigungen korrekt zwischen den durch Hardware erzwungenen und durch Software durchgesetzten Listen zu. 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 notwendig, um den Typ anzugeben.

RSA-Schlüssel

Zur Generierung eines RSA-Schlüssels sind folgende Parameter notwendig.

  • Tag::KEY_SIZE gibt die Größe des öffentlichen Moduls in Bits an. Wenn es weggelassen wird, gibt die Methode ErrorCode::UNSUPPORTED_KEY_SIZE zurück. Unterstützte Werte sind 1024, 2048, 3072 und 4096. Empfohlene Werte sind alle Schlüsselgrößen, die ein Vielfaches von 8 sind.
  • Tag::RSA_PUBLIC_EXPONENT gibt den öffentlichen RSA-Exponentenwert an. Wenn es weggelassen wird, gibt die Methode ErrorCode::INVALID_ARGUMENT zurück. Unterstützte Werte sind 3 und 65537. Empfohlene Werte sind alle Primwerte bis zu 2^64.

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

  • Tag::PURPOSE gibt zulässige 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 Digest-Algorithmen unterstützen, müssen Anfragen zur Schlüsselgenerierung akzeptieren, die nicht unterstützte Digests enthalten. Die nicht unterstützten Digests sollten in der Liste „Software-erzwungen“ in den zurückgegebenen Schlüsselmerkmalen platziert werden. Dies liegt daran, dass der Schlüssel mit diesen anderen Digests verwendet werden kann, der Digest jedoch in der Software durchgeführt wird. Anschließend wird die Hardware aufgerufen, die Operation mit Digest::NONE auszuführen.
  • Tag::PADDING gibt die Füllmodi an, die mit dem neuen Schlüssel verwendet werden können. Implementierungen, die nicht alle Digest-Algorithmen unterstützen, müssen PaddingMode::RSA_PSS und PaddingMode::RSA_OAEP in die softwareerzwungene Liste der Schlüsselmerkmale einfügen, wenn nicht unterstützte Digest-Algorithmen angegeben werden.

ECDSA-Schlüssel

Zum Generieren eines ECDSA-Schlüssels ist nur Tag::KEY_SIZE erforderlich. Es wird verwendet, um die EC-Gruppe auszuwählen. Unterstützte Werte sind 224, 256, 384 und 521, die jeweils die NIST-Kurven p-224, p-256, p-384 und p521 angeben.

Tag::DIGEST ist ebenfalls für einen nützlichen ECDSA-Schlüssel erforderlich, wird jedoch nicht für die Generierung benötigt.

AES-Schlüssel

Zur Generierung eines AES-Schlüssels ist nur Tag::KEY_SIZE erforderlich. Wenn es weggelassen wird, gibt die Methode ErrorCode::UNSUPPORTED_KEY_SIZE zurück. Unterstützte Werte sind 128 und 256, optional mit Unterstützung für 192-Bit-AES-Schlüssel.

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

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

Wenn der GCM-Blockmodus angegeben ist, geben Sie Tag::MIN_MAC_LENGTH an. Wenn es weggelassen wird, 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 folgende Parameter erforderlich:

  • Tag::KEY_SIZE gibt die Schlüsselgröße in Bits an. Werte kleiner als 64 und Werte, die kein Vielfaches von 8 sind, werden nicht unterstützt. Alle Vielfachen von 8, von 64 bis 512, werden unterstützt. Größere Werte können unterstützt werden.
  • Tag::MIN_MAC_LENGTH gibt die Mindestlänge von MACs an, die mit diesem Schlüssel generiert oder überprüft 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 wird genau ein Digest angegeben, andernfalls wird ErrorCode::UNSUPPORTED_DIGEST zurückgegeben. Wenn der Digest vom Trustlet nicht unterstützt wird, geben Sie ErrorCode::UNSUPPORTED_DIGEST zurück.

Schlüsseleigenschaften

Wenn das Argument „characteristics“ ungleich NULL ist, gibt generateKey “ die Merkmale des neu generierten Schlüssels zurück, entsprechend unterteilt in hardware-erzwungene und software-erzwungene Listen. Eine Beschreibung, welche Merkmale in welche Liste aufgenommen werden, 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, sodass ihre Werte nicht durch Untersuchen des zurückgegebenen Schlüsselblobs ermittelt werden können. Sie sind jedoch kryptografisch an den Schlüsselblob gebunden, sodass die Verwendung fehlschlägt, wenn bei der Verwendung des Schlüssels nicht die richtigen Werte bereitgestellt werden. Ebenso ist Tag::ROOT_OF_TRUST kryptografisch an den Schlüssel gebunden, darf jedoch bei der Schlüsselerstellung oder dem Schlüsselimport nicht angegeben werden und wird niemals zurückgegeben.

Zusätzlich zu den bereitgestellten Tags fügt das Trustlet auch Tag::ORIGIN mit dem Wert KeyOrigin::GENERATED hinzu. Wenn der Schlüssel rollbackresistent ist,

Tag::ROLLBACK_RESISTANT .

Rollback-Widerstand

Rollback-Resistenz bedeutet, dass ein einmal mit deleteKey oder deleteAllKeys gelöschter Schlüssel durch sichere Hardware garantiert nie wieder verwendbar ist. Implementierungen ohne Rollback-Widerstand geben generiertes oder importiertes Schlüsselmaterial normalerweise als Schlüsselblob, eine verschlüsselte und authentifizierte Form, an den Aufrufer zurück. Wenn Keystore den Schlüsselblob löscht, ist der Schlüssel verloren, aber ein Angreifer, dem es zuvor gelungen ist, das Schlüsselmaterial abzurufen, kann es möglicherweise auf dem Gerät wiederherstellen.

Ein Schlüssel ist Rollback-resistent, wenn die sichere Hardware garantiert, dass gelöschte Schlüssel später nicht wiederhergestellt werden können. Dies geschieht im Allgemeinen durch die Speicherung zusätzlicher Schlüsselmetadaten an einem vertrauenswürdigen Ort, der von einem Angreifer nicht manipuliert werden kann. Auf mobilen Geräten wird hierfür üblicherweise der Mechanismus Replay Protected Memory Blocks (RPMB) verwendet. Da die Anzahl der Schlüssel, die erstellt werden können, im Wesentlichen unbegrenzt ist und der vertrauenswürdige Speicher, der für den Rollback-Widerstand verwendet wird, in seiner Größe begrenzt sein kann, muss diese Methode auch dann erfolgreich sein, wenn für den neuen Schlüssel kein Rollback-Widerstand bereitgestellt werden kann. In diesem Fall sollte Tag::ROLLBACK_RESISTANT nicht zu den Schlüsselmerkmalen 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 dem bereitgestellten Schlüssel zugeordnet sind, aufgeteilt in zwei Sätze: hardware-erzwungen und software-erzwungen. Die Beschreibung hier gilt gleichermaßen für die Schlüsselmerkmalslisten, die von genericKey und importKey zurückgegeben werden.

Wenn Tag::APPLICATION_ID während der Schlüsselgenerierung oder des Schlüsselimports bereitgestellt wurde, wird dieser Methode im Argument clientId derselbe Wert bereitgestellt. Andernfalls gibt die Methode ErrorCode::INVALID_KEY_BLOB zurück. Wenn Tag::APPLICATION_DATA während der Generierung oder des Imports bereitgestellt wurde, wird dieser Methode im Argument appData derselbe Wert bereitgestellt.

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

Die allgemeine Regel für die Entscheidung, ob ein bestimmtes Tag in die Liste der durch Hardware oder durch Software erzwungenen Tags gehört, lautet: Wenn die Bedeutung des Tags durch sichere Hardware vollständig sichergestellt ist, ist es durch Hardware erzwungen. Andernfalls wird die Software erzwungen. Nachfolgend finden Sie eine Liste spezifischer Tags, deren korrekte Zuordnung möglicherweise unklar ist:

  • Tag::ALGORITHM , Tag::KEY_SIZE und Tag::RSA_PUBLIC_EXPONENT sind intrinsische Eigenschaften des Schlüssels. Für jeden Schlüssel, der durch Hardware gesichert ist, befinden sich diese Tags in der Liste der durch Hardware erzwungenen Schlüssel.
  • Tag::DIGEST- Werte, die von der sicheren Hardware unterstützt werden, werden in die Liste der unterstützten Hardware aufgenommen. Nicht unterstützte Digests werden in die Liste der von der Software unterstützten Dateien aufgenommen.
  • Tag::PADDING- Werte werden im Allgemeinen in die von der Hardware unterstützte Liste aufgenommen, es sei denn, es besteht die Möglichkeit, dass ein bestimmter Auffüllmodus von der Software ausgeführt werden muss. In diesem Fall werden sie in die softwareerzwungene Liste aufgenommen. Eine solche Möglichkeit besteht für RSA-Schlüssel, die PSS- oder OAEP-Auffüllen mit Digest-Algorithmen ermöglichen, die von der sicheren Hardware nicht unterstützt werden.
  • Tag::USER_SECURE_ID und Tag::USER_AUTH_TYPE werden nur dann durch Hardware erzwungen, wenn die Benutzerauthentifizierung durch Hardware erzwungen wird. Um dies zu erreichen, 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. Einzelheiten finden Sie auf der Seite „Authentifizierung“ .
  • Die Tags Tag::ACTIVE_DATETIME , Tag::ORIGINATION_EXPIRE_DATETIME und Tag::USAGE_EXPIRE_DATETIME erfordern Zugriff auf eine nachweislich korrekte Wanduhr. Die meiste sichere Hardware hat nur Zugriff auf Zeitinformationen, die vom nicht sicheren Betriebssystem bereitgestellt werden, was bedeutet, dass die Tags durch Software erzwungen werden.
  • Tag::ORIGIN ist immer in der Hardwareliste für hardwaregebundene Schlüssel. Durch sein Vorhandensein in dieser Liste bestimmen höhere Schichten, ob 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 Keymaster-Hardware. Schlüsseldefinitionsparameter und Ausgabemerkmale werden mit den folgenden Ausnahmen genauso behandelt wie für generateKey :

  • Tag::KEY_SIZE und Tag::RSA_PUBLIC_EXPONENT (nur für RSA-Schlüssel) sind in den Eingabeparametern nicht erforderlich. Wenn keine Angabe erfolgt, leitet das Trustlet die Werte aus dem bereitgestellten Schlüsselmaterial ab und fügt den Schlüsselmerkmalen entsprechende Tags und Werte hinzu. Wenn die Parameter bereitgestellt werden, validiert das Trustlet sie anhand des Schlüsselmaterials. Im Falle einer Nichtübereinstimmung gibt die Methode ErrorCode::IMPORT_PARAMETER_MISMATCH zurück.
  • Das zurückgegebene 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 Keymaster RSA- oder EC-Schlüsselpaar.

Wenn Tag::APPLICATION_ID während der Schlüsselgenerierung oder des Schlüsselimports bereitgestellt wurde, wird dieser Methode im Argument clientId derselbe Wert bereitgestellt. Andernfalls gibt die Methode ErrorCode::INVALID_KEY_BLOB zurück. Wenn Tag::APPLICATION_DATA während der Generierung oder des Imports bereitgestellt wurde, wird dieser Methode im Argument appData derselbe Wert bereitgestellt.

deleteKey

Version : 1, 2, 3

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

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

deleteAllKeys

Version : 1, 2, 3

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

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

destroyAttestationIds

Version : 3

Die Methode destroyAttestationIds() wird verwendet, um die neue (optionale, aber dringend empfohlene) ID-Bestätigungsfunktion dauerhaft zu deaktivieren. Wenn die TEE keine Möglichkeit hat, sicherzustellen, dass die ID-Bescheinigung nach dem Aufruf dieser Methode dauerhaft deaktiviert wird, darf die ID-Bescheinigung überhaupt nicht implementiert werden. In diesem Fall führt diese Methode keine Aktion aus und gibt ErrorCode::UNIMPLEMENTED zurück. Wenn die ID-Bestätigung unterstützt wird, muss diese Methode implementiert werden und alle zukünftigen ID-Bestätigungsversuche dauerhaft deaktivieren. Die Methode kann beliebig oft aufgerufen werden. Wenn der ID-Nachweis bereits dauerhaft deaktiviert ist, führt die Methode keine Aktion aus und gibt ErrorCode::OK zurück.

Die einzigen Fehlercodes, die diese Methode möglicherweise zurückgibt, sind ErrorCode::UNIMPLEMENTED (wenn die ID-Bescheinigung nicht unterstützt wird), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED oder einer der Fehlercodes, die auf einen Fehler bei der Kommunikation mit der sicheren Hardware hinweisen.

beginnen

Version : 1, 2, 3

Beginnt einen kryptografischen Vorgang unter Verwendung des angegebenen Schlüssels für den angegebenen Zweck und mit den angegebenen Parametern (sofern zutreffend) und gibt ein Vorgangshandle zurück, das mit Update und Finish verwendet wird, um den Vorgang abzuschließen. Das Operationshandle wird auch als „Challenge“-Token bei authentifizierten Vorgängen verwendet und ist für solche Vorgänge im challenge Feld des Authentifizierungstokens enthalten.

Eine Keymaster-Implementierung unterstützt mindestens 16 gleichzeitige Vorgänge. Keystore verwendet bis zu 15, womit vold einen für die Passwortverschlüsselung übrig lässt. Wenn im Keystore 15 Vorgänge ausgeführt werden ( begin wurde aufgerufen, finish oder abort wurden jedoch noch nicht aufgerufen) und eine Anforderung zum Beginn eines 16. Vorgangs eingeht, ruft er abort für den am längsten verwendeten Vorgang auf, um die Anzahl der aktiven Vorgänge zu reduzieren bis 14 vor dem Aufruf begin , um den neu angeforderten Vorgang zu starten.

Wenn Tag::APPLICATION_ID oder Tag::APPLICATION_DATA während der Schlüsselgenerierung oder des Imports angegeben wurden, enthalten Aufrufe von begin diese Tags mit den ursprünglich angegebenen Werten im inParams Argument dieser Methode.

Durchsetzung der Genehmigung

Bei dieser Methode werden die folgenden Schlüsselautorisierungen vom Trustlet erzwungen, wenn die Implementierung sie in die „hardwareerzwungenen“ Merkmale eingefügt hat und es sich bei der Operation nicht um eine Operation mit öffentlichem Schlüssel handelt. Öffentliche Schlüsseloperationen, d. h. KeyPurpose::ENCRYPT und KeyPurpose::VERIFY , mit RSA- oder EC-Schlüsseln dürfen erfolgreich sein, auch 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, die angeforderte Operation ist eine Operation mit öffentlichem Schlüssel. Wenn der angegebene Zweck nicht übereinstimmt und es sich bei der Operation nicht um eine Public-Key-Operation handelt, gibt begin ErrorCode::UNSUPPORTED_PURPOSE zurück. Public-Key-Operationen sind asymmetrische Verschlüsselungs- oder Verifizierungsoperationen.
  • 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 nach dem Tag-Wert liegen 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 nach dem Tag-Wert liegen 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 Startzeitpunkt verfolgt. Wenn die Anzahl der vorherigen Verwendungen den Tag-Wert überschreitet, gibt die Methode ErrorCode::KEY_MAX_OPS_EXCEEDED zurück.
  • Tag::USER_SECURE_ID wird von dieser Methode nur erzwungen, wenn der Schlüssel auch Tag::AUTH_TIMEOUT hat. Wenn der Schlüssel beides hat, muss diese Methode ein gültiges Tag::AUTH_TOKEN in inParams erhalten. Damit das Authentifizierungstoken gültig ist, müssen alle folgenden Bedingungen zutreffen:
    • Das HMAC-Feld wird korrekt validiert.
    • Mindestens einer der Tag::USER_SECURE_ID -Werte aus dem Schlüssel stimmt mit mindestens einem der sicheren ID-Werte im Token überein.
    • Der Schlüssel hat einen Tag::USER_AUTH_TYPE , der dem Authentifizierungstyp im Token entspricht.

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

  • Tag::CALLER_NONCE ermöglicht dem Aufrufer die Angabe eines Nonce- oder Initialisierungsvektors (IV). Wenn der Schlüssel dieses Tag nicht hat, der Aufrufer aber Tag::NONCE für diese Methode bereitgestellt hat, wird ErrorCode::CALLER_NONCE_PROHIBITED zurückgegeben.
  • Tag::BOOTLOADER_ONLY gibt an, dass nur der Bootloader den Schlüssel verwenden darf. Wenn diese Methode mit einem Nur-Bootloader-Schlüssel aufgerufen wird, nachdem die Ausführung des Bootloaders abgeschlossen ist, gibt sie ErrorCode::INVALID_KEY_BLOB zurück.

RSA-Schlüssel

Alle RSA-Tastenoperationen geben genau einen Auffüllmodus in inParams an. Wenn nicht angegeben oder mehr als einmal angegeben, gibt die Methode ErrorCode::UNSUPPORTED_PADDING_MODE zurück.

RSA-Signatur- und -Verifizierungsvorgänge erfordern einen Digest, ebenso wie RSA-Verschlüsselungs- und -Entschlüsselungsvorgänge mit OAEP-Auffüllmodus. In diesen Fällen gibt der Aufrufer genau einen Digest in inParams an. Wenn nicht angegeben oder mehr als einmal angegeben, gibt die Methode ErrorCode::UNSUPPORTED_DIGEST zurück.

Private Schlüsseloperationen ( KeyPurpose::DECYPT und KeyPurpose::SIGN ) erfordern die Autorisierung von Digest und Padding, was bedeutet, dass die Schlüsselautorisierungen die angegebenen Werte enthalten müssen. Wenn nicht, gibt die Methode je nach Fall ErrorCode::INCOMPATIBLE_DIGEST oder ErrorCode::INCOMPATIBLE_PADDING zurück. Operationen mit öffentlichen Schlüsseln ( KeyPurpose::ENCRYPT und KeyPurpose::VERIFY ) sind mit nicht autorisiertem Digest oder Padding zulässig.

Mit Ausnahme von PaddingMode::NONE sind alle RSA-Auffüllmodi nur für bestimmte Zwecke anwendbar. Insbesondere unterstützen PaddingMode::RSA_PKCS1_1_5_SIGN “ und PaddingMode::RSA_PSS nur das Signieren und Verifizieren, während PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT und PaddingMode::RSA_OAEP nur die 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 Auffüllmodi und Digests:

  • PaddingMode::NONE gibt an, dass eine „rohe“ RSA-Operation ausgeführt wird. Beim Signieren oder Verifizieren wird Digest::NONE für den Digest angegeben. Für die ungepolsterte Verschlüsselung oder Entschlüsselung ist kein Digest erforderlich.
  • Für das Auffüllen von PaddingMode::RSA_PKCS1_1_5_SIGN ist ein Digest erforderlich. Der Digest kann Digest::NONE sein. In diesem Fall kann die Keymaster-Implementierung keine ordnungsgemäße PKCS#1 v1.5-Signaturstruktur erstellen, da sie die DigestInfo-Struktur nicht hinzufügen kann. Stattdessen konstruiert die Implementierung 0x00 || 0x01 || PS || 0x00 || M , wobei M die bereitgestellte Nachricht und PS die Füllzeichenfolge ist. Die Größe des RSA-Schlüssels muss mindestens 11 Byte größer sein als die Nachricht, andernfalls gibt die Methode ErrorCode::INVALID_INPUT_LENGTH zurück.
  • Für PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT ist kein Digest erforderlich.
  • PaddingMode::RSA_PSS Auffüllen ist ein Digest erforderlich, der möglicherweise nicht Digest::NONE ist. Wenn Digest::NONE angegeben ist, gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück. Darüber hinaus muss die Größe des RSA-Schlüssels mindestens 2 + D Byte größer sein als die Ausgabegröße des Digests, wobei D die Größe des Digests in Bytes ist. Andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück. Die Salzgröße beträgt D.
  • PaddingMode::RSA_OAEP Auffüllen ist ein Digest erforderlich, der möglicherweise nicht Digest::NONE ist. Wenn Digest::NONE angegeben ist, gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück.

EC-Schlüssel

EC-Tastenoperationen geben genau einen Auffüllmodus in inParams an. Wenn nicht angegeben oder mehr als einmal angegeben, gibt die Methode ErrorCode::UNSUPPORTED_PADDING_MODE zurück.

Operationen mit privaten Schlüsseln ( KeyPurpose::SIGN ) erfordern die Autorisierung von Digest und Padding, was bedeutet, dass die Schlüsselautorisierungen die angegebenen Werte enthalten müssen. Wenn nicht, geben Sie ErrorCode::INCOMPATIBLE_DIGEST zurück. Operationen mit öffentlichen Schlüsseln ( KeyPurpose::VERIFY ) sind mit nicht autorisiertem Digest oder Padding zulässig.

AES-Schlüssel

AES-Tastenoperationen geben in inParams genau einen Blockmodus und einen Füllmodus an. Wenn einer der Werte nicht angegeben oder mehr als einmal angegeben ist, geben Sie ErrorCode::UNSUPPORTED_BLOCK_MODE oder ErrorCode::UNSUPPORTED_PADDING_MODE zurück. Die angegebenen Modi müssen durch den Schlüssel autorisiert werden, andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_BLOCK_MODE oder ErrorCode::INCOMPATIBLE_PADDING_MODE zurück.

Wenn der Blockmodus BlockMode::GCM ist, gibt inParams Tag::MAC_LENGTH an 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üsselberechtigungen ist. Für MAC-Längen größer als 128 oder Nicht-Vielfache von 8 geben Sie ErrorCode::UNSUPPORTED_MAC_LENGTH zurück. Für Werte, die kleiner als die Mindestlänge des Schlüssels sind, geben Sie ErrorCode::INVALID_MAC_LENGTH zurück.

Wenn der Blockmodus BlockMode::GCM oder BlockMode::CTR ist, muss der angegebene Auffüllmodus PaddingMode::NONE sein. Für BlockMode::ECB oder BlockMode::CBC kann der Modus PaddingMode::NONE oder PaddingMode::PKCS7 sein. Wenn der Auffüllmodus diese Bedingungen nicht erfüllt, geben Sie 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 Anrufer keine IV oder Nonce angeben. In diesem Fall generiert die Keymaster-Implementierung einen zufälligen IV oder Nonce und gibt ihn über Tag::NONCE in outParams zurück. CBC- und CTR-IVs sind 16 Bytes groß. GCM-Nonces sind 12 Bytes. Wenn die Schlüsselberechtigungen Tag::CALLER_NONCE enthalten, kann der Aufrufer einen IV/Nonce mit Tag::NONCE in inParams bereitstellen. Wenn eine Nonce bereitgestellt wird, wenn Tag::CALLER_NONCE nicht autorisiert ist, geben Sie ErrorCode::CALLER_NONCE_PROHIBITED zurück. Wenn kein Nonce bereitgestellt wird, wenn Tag::CALLER_NONCE autorisiert ist, generieren Sie einen zufälligen IV/Nonce.

HMAC-Schlüssel

HMAC-Tastenoperationen geben Tag::MAC_LENGTH in inParams an. Der angegebene Wert muss ein Vielfaches von 8 sein, das nicht größer als die Digest-Länge und nicht kleiner als der Wert von Tag::MIN_MAC_LENGTH in den Schlüsselberechtigungen ist. Für MAC-Längen, die größer als die Digest-Länge oder Nicht-Vielfache von 8 sind, geben Sie ErrorCode::UNSUPPORTED_MAC_LENGTH zurück. Für Werte, die kleiner als die Mindestlänge des Schlüssels sind, geben Sie ErrorCode::INVALID_MAC_LENGTH zurück.

aktualisieren

Version : 1, 2, 3

Stellt Daten zur Verarbeitung in einem laufenden Vorgang bereit, der mit begin gestartet wird. Der Vorgang wird durch den Parameter operationHandle angegeben.

Um mehr Flexibilität bei der Pufferbehandlung zu bieten, haben Implementierungen dieser Methode die Möglichkeit, weniger Daten zu verbrauchen als bereitgestellt. Der Aufrufer ist für die Schleife verantwortlich, um die restlichen Daten in nachfolgende Aufrufe einzuspeisen. Die Menge der verbrauchten Eingabe wird im Parameter inputConsumed zurückgegeben. Implementierungen verbrauchen immer mindestens ein Byte, es sei denn, die Operation kann kein weiteres Byte akzeptieren; Wenn mehr als null Bytes bereitgestellt werden und null Bytes verbraucht werden, betrachten Aufrufer dies als Fehler und brechen den Vorgang ab.

Implementierungen können auch entscheiden, wie viele Daten als Ergebnis der Aktualisierung zurückgegeben werden sollen. Dies ist nur für Verschlüsselungs- und Entschlüsselungsvorgänge relevant, da beim Signieren und Verifizieren bis zum Abschluss keine Daten zurückgegeben werden. Geben Sie 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 das Vorgangshandle ungültig gemacht. Jede zukünftige Verwendung des Handles mit dieser Methode, finish oder abort , gibt ErrorCode::INVALID_OPERATION_HANDLE zurück.

Durchsetzung der Genehmigung

Die Durchsetzung der Schlüsselautorisierung erfolgt hauptsächlich in begin . Die einzige Ausnahme ist der Fall, wenn der Schlüssel Folgendes enthält:

In diesem Fall erfordert der Schlüssel eine Autorisierung pro Vorgang und die Update-Methode erhält ein Tag::AUTH_TOKEN im inParams Argument. HMAC überprüft, ob das Token gültig ist und eine passende sichere Benutzer-ID enthält, mit dem Tag::USER_AUTH_TYPE des Schlüssels übereinstimmt und das Operationshandle der aktuellen Operation im Challenge-Feld enthält. Wenn diese Bedingungen nicht erfüllt sind, geben Sie ErrorCode::KEY_USER_NOT_AUTHENTICATED zurück.

Der Anrufer stellt bei jedem Anruf das Authentifizierungstoken bereit, um ihn zu aktualisieren und abzuschließen . Die Implementierung muss das Token nur einmal validieren, wenn sie dies wünscht.

RSA-Schlüssel

Für Signierungs- und Verifizierungsvorgänge mit Digest::NONE akzeptiert diese Methode, dass der gesamte Block in einer einzigen Aktualisierung signiert oder verifiziert wird. Es darf nicht nur ein Teil des Blocks verbraucht werden. Wenn sich der Aufrufer jedoch dafür entscheidet, die Daten in mehreren Aktualisierungen bereitzustellen, akzeptiert diese Methode dies. Wenn der Aufrufer mehr Daten zum Signieren bereitstellt, als verwendet werden können (die Länge der Daten überschreitet die RSA-Schlüsselgröße), wird ErrorCode::INVALID_INPUT_LENGTH zurückgegeben.

ECDSA-Schlüssel

Für Signierungs- und Verifizierungsvorgänge mit Digest::NONE akzeptiert diese Methode, dass der gesamte Block in einer einzigen Aktualisierung signiert oder verifiziert wird. Diese Methode verbraucht möglicherweise nicht nur einen Teil des Blocks.

Wenn sich der Aufrufer jedoch dafür entscheidet, die Daten in mehreren Aktualisierungen bereitzustellen, akzeptiert diese Methode dies. Wenn der Anrufer mehr Daten zum Signieren bereitstellt, als verwendet werden können, werden die Daten stillschweigend abgeschnitten. (Dies unterscheidet sich von der Handhabung überschüssiger Daten, die bei ähnlichen RSA-Vorgängen bereitgestellt werden. 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::ASSOCIATED_DATA -Tag im inParams Argument bereitgestellt werden. Die zugehörigen Daten können in wiederholten Aufrufen bereitgestellt werden (wichtig, wenn die Daten zu groß sind, um in einem einzelnen Block gesendet zu werden), gehen jedoch immer den zu verschlüsselnden oder zu entschlüsselnden Daten voraus. Ein Aktualisierungsaufruf kann sowohl zugehörige Daten als auch zu verschlüsselnde/entschlüsselnde Daten empfangen, nachfolgende Aktualisierungen enthalten jedoch möglicherweise keine zugehörigen Daten. Wenn der Aufrufer einem Aktualisierungsaufruf nach einem Aufruf, der Daten zum Verschlüsseln/Entschlüsseln enthält, zugehörige Daten bereitstellt, geben Sie ErrorCode::INVALID_TAG zurück.

Bei der GCM-Verschlüsselung wird das Tag durch Finish an den Chiffretext angehängt. Während der Entschlüsselung sind die letzten Tag::MAC_LENGTH Bytes der Daten, die beim letzten Aktualisierungsaufruf bereitgestellt wurden, das Tag. Da ein bestimmter Update- Aufruf nicht wissen kann, ob es sich um den letzten Aufruf handelt, verarbeitet er alle Daten bis auf die Tag-Länge und puffert die möglichen Tag-Daten während des Finishs .

beenden

Version : 1, 2, 3

Beendet einen laufenden Vorgang, der mit begin begonnen wurde, und verarbeitet alle noch nicht verarbeiteten Daten, die durch Aktualisierung (en) bereitgestellt werden.

Diese Methode ist die letzte, die in einem Betrieb aufgerufen wird, sodass alle verarbeiteten Daten zurückgegeben werden.

Unabhängig davon, ob es erfolgreich abgeschlossen ist oder einen Fehler zurückgibt, schließt diese Methode den Vorgang ab und macht daher den bereitgestellten Betriebsgriff ungültig. Jegliche zukünftige Verwendung des Handels mit dieser Methode oder aktualisiert oder abbrechen , gibt ErrorCode::INVALID_OPERATION_HANDLE zurück.

Signiervorgänge geben die Signatur als Ausgabe zurück. Überprüfvorgänge akzeptieren die Signatur im signature und geben keine Ausgabe zurück.

Durchsetzung der Autorisierung

Die Durchsetzung der wichtigsten Autorisierung wird hauptsächlich in Beginn durchgeführt. Die einzige Ausnahme ist der Fall, in dem der Schlüssel hat:

In diesem Fall erfordert der Schlüssel eine Autorisierung pro Operation, und die Aktualisierungsmethode empfängt ein Tag :: Auth_Token im Argument inParams . HMAC überprüft, ob das Token gültig ist und eine passende sichere Benutzer -ID enthält, mit dem Tag des Schlüssels übereinstimmt :: user_auth_type und enthält das Operationsgriff des aktuellen Vorgangs im Feld Challenge. Wenn diese Bedingungen nicht erfüllt sind, senden Sie ErrorCode::KEY_USER_NOT_AUTHENTICATED zurück.

Der Anrufer stellt den Authentifizierungs -Token für jeden Anruf zur Verfügung, um zu aktualisieren und zu beenden . Die Implementierung muss das Token nur einmal validieren, wenn es bevorzugt.

RSA -Schlüssel

Einige zusätzliche Anforderungen, abhängig vom Polstermodus:

  • PaddingMode::NONE . Bei nicht beschriebenen Unterzeichnungs- und Verschlüsselungsvorgängen, wenn die bereitgestellten Daten kürzer als der Schlüssel sind, sind die Daten vor der Unterzeichnung/Verschlüsselung auf der linken Seite Null. Wenn die Daten die gleiche Länge wie der Schlüssel sind, aber numerisch größer sind, return ErrorCode::INVALID_ARGUMENT . Zur Überprüfungs- und Entschlüsselungsvorgänge müssen die Daten genau so lange betragen wie der Schlüssel. Andernfalls return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . Für PSS-Paddged-Signaturoperationen ist das PSS-Salz die Größe des Meldungsdigests und zufällig generiert. Der mit Tag :: Digest in inputParams angegebene Digest wird als PSS -Digest -Algorithmus und als MGF1 -Digest -Algorithmus verwendet.
  • PaddingMode::RSA_OAEP . Der mit Tag :: Digest in inputParams angegebene Digest wird als OAEP -Digest -Algorithmus verwendet, und SHA1 wird als MGF1 -Digest -Algorithmus verwendet .

ECDSA KEYS

Wenn die Daten für die nicht zu lange Unterzeichnung oder Überprüfung vorgesehen sind, schneiden Sie sie ab.

AES -Schlüssel

Einige zusätzliche Bedingungen, abhängig vom Blockmodus:

  • BlockMode::ECB oder BlockMode::CBC . Wenn Padding PaddingMode::NONE ist und die Datenlänge kein Vielfaches der AES -Blockgröße ist, senden Sie ErrorCode::INVALID_INPUT_LENGTH zurück. Wenn Padding PaddingMode::PKCS7 ist, pad die Daten gemäß der PKCS#7 -Spezifikation. Beachten Sie, dass PKCS#7 empfiehlt, einen zusätzlichen Polsterblock 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 Klartextes das Tag ( tag :: mac_length Bytes) und fügen Sie es dem zurückgegebenen Ciphertext hinzu. Verarbeiten Sie während der Entschlüsselung das letzte Tag :: mac_length Bytes als Tag. Wenn die Tag -Verifizierung fehlschlägt, senden Sie ErrorCode::VERIFICATION_FAILED zurück.

abbrechen

Version : 1, 2, 3

Abbreitet den In-Progress-Betrieb. Nach dem Aufruf zum Abbruch return ErrorCode::INVALID_OPERATION_HANDLE für eine nachfolgende Verwendung des bereitgestellten Operationshandels mit Update , Finish oder Abbruch .

get_supported_algorithmen

Version 1

Gibt die Liste der Algorithmen zurück, die von der Keymaster -Hardware -Implementierung unterstützt werden. Eine Software -Implementierung gibt eine leere Liste zurück. Eine Hybrid -Implementierung gibt eine Liste zurück, die nur die Algorithmen enthält, die von 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 -Hardware -Implementierung für einen bestimmten Algorithmus und Zweck unterstützt werden.

Für RSA, EC und HMAC, die keine Blockveränderungen sind, gibt die Methode eine leere Liste für alle gültigen Zwecke zurück. Ungültige Zwecke sollten dazu führen, dass die Methode ErrorCode::INVALID_PURPOSE zurücksend macht.

Keymaster 1 Implementierungen unterstützen EZB, CBC, CTR und GCM für die AES -Verschlüsselung und -Delie.

get_supported_padding_modes

Version 1

Gibt die Liste der Polstermodi zurück, die von der Keymaster -Hardware -Implementierung für einen bestimmten Algorithmus und Zweck unterstützt werden.

HMAC und EC haben keinen Vorstellung von Polsterung, daher gibt die Methode eine leere Liste für alle gültigen Zwecke zurück. Ungültige Zwecke sollten dazu führen, dass die Methode ErrorCode::INVALID_PURPOSE zurücksend macht.

Für RSA unterstützt Keymaster 1 Implementierungen:

  • Unbekannte Verschlüsselung, Entschlüsselung, Unterzeichnung und Überprüfung. Bei einer ungepassten Verschlüsselung und Unterzeichnung müssen die Implementierungen, wenn die Nachricht kürzer als der öffentliche Modul ist, mit Nullen. Bei einer nicht beschlossenen Entschlüsselung und Überprüfung muss die Eingangslänge mit der Größe der öffentlichen Modul übereinstimmen.
  • PKCS#1 V1.5 Verschlüsselungs- und Signierstadlermodi
  • PSS mit einer minimalen Salzlänge von 20
  • OAEP

Für AES in EZB- und CBC-Modi unterstützen Keymaster 1-Implementierungen keine Polsterung und PKCs#7-Padding. CTR- und GCM -Modi unterstützen nur keine Polsterung.

get_supported_digests

Version 1

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

Keine AES -Modi unterstützen oder erfordern die Verdauung, sodass die Methode eine leere Liste für gültige Zwecke zurückgibt.

Keymaster 1 -Implementierungen können eine Teilmenge der definierten Verdauung implementieren. Implementierungen bieten SHA-256 und können MD5, SHA1, SHA-224, SHA-256, SHA384 und SHA512 (der gesamte Satz definierter Verdauung) bereitstellen.

get_supported_import_formats

Version 1

Gibt die Liste der Importformate zurück, die durch die Keymaster -Hardware -Implementierung eines bestimmten Algorithmus unterstützt werden.

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

get_supported_export_formats

Version 1

Gibt die Liste der Exportformate zurück, die durch die Keymaster -Hardware -Implementierung eines bestimmten Algorithmus unterstützt werden.

Keymaster1 -Implementierungen unterstützen das X.509 -Format zum Exportieren von RSA- und EC -Tasten. Der Export von privaten Schlüssel oder asymmetrischen Schlüssel wird nicht unterstützt.

Historische Funktionen

Keymaster 0

Die folgenden Funktionen gehören zur ursprünglichen Keymaster 0 -Definition. Sie waren in Keymaster 1 Struct Keymaster1_Device_T vorhanden. In Keymaster 1.0 wurden sie jedoch nicht implementiert und ihre Funktionszeiger 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 Definition von Keymaster 1, 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 jedoch zusammen mit den oben aufgeführten Funktionen von Keymaster 1 in Keymaster 3 entfernt.

  • configure