Keymaster-Funktionen

Diese Seite enthält Details zur Unterstützung von Implementierern von Keymaster Hardware Abstraction Layers (HALs). Es behandelt jede Funktion in der API und in welcher Keymaster-Version diese Funktion verfügbar ist und beschreibt die Standardimplementierung. Für Tags siehe die Keymaster-Tags -Seite.

Allgemeine Umsetzungsrichtlinien

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

Zeigerparameter eingeben

Fassung : 1, 2

Eingabezeigerparameter, die für einen bestimmten Aufruf nicht verwendet werden, können NULL sein. Der Aufrufer muss keine Platzhalter bereitstellen. Beispielsweise verwenden einige Schlüsseltypen und -modi möglicherweise keine Werte aus dem Argument inParams für begin , 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 .

Ab Keymaster 3 gibt es keine Zeigerparameter. Alle Parameter werden als Wert oder konstante Referenzen übergeben.

Zeigerparameter ausgeben

Fassung : 1, 2

Ähnlich wie Eingabezeigerparameter können unbenutzte Ausgabezeigerparameter NULL sein. Wenn eine Methode Daten in einem als NULL ermittelten Ausgabeparameter zurückgeben muss, sollte sie ErrorCode::OUTPUT_PARAMETER_NULL .

Ab Keymaster 3 gibt es keine Zeigerparameter. Alle Parameter werden als Wert oder konstante Referenzen ü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 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 nicht von Implementierungen diagnostiziert werden. Fehlende erforderliche Parameter, Angabe ungültiger erforderlicher Parameter und ähnliche Fehler müssen diagnostiziert werden.

Es liegt in der Verantwortung von Apps, dem Framework und dem Android-Keystore sicherzustellen, dass die Aufrufe von Keymaster-Modulen sinnvoll und nützlich sind.

Funktionen

getHardwareFeatures

Fassung : 3

Die neue getHardwareFeatures Methode stellt Clients einige wichtige Merkmale der zugrunde liegenden sicheren Hardware zur Verfügung. Die Methode akzeptiert keine Argumente und gibt vier Werte zurück, alle 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 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 unterstützt, einschließlich AES und HMAC.
  • supportsAttestation ist true wenn die Hardware die Generierung von Keymaster Public Key-Bestätigungszertifikaten unterstützt, die mit einem in einer sicheren Umgebung eingefügten Schlüssel signiert sind.

Die einzigen Fehlercodes, die diese Methode zurückgeben kann, 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

Fassung : 2

Diese Funktion wurde in Keymaster 2 eingeführt und in Keymaster 3 veraltet, da diese Informationen in Systemeigenschaftendateien verfügbar sind und Herstellerimplementierungen diese Dateien während des Starts lesen.

Konfiguriert Keymaster. Diese Methode wird einmal aufgerufen, nachdem das Gerät geöffnet und bevor es verwendet wird. Es wird verwendet, um Keymaster KM_TAG_OS_VERSION und KM_TAG_OS_PATCHLEVEL bereitzustellen. Bis diese Methode aufgerufen wird, geben alle anderen Methoden KM_ERROR_KEYMASTER_NOT_CONFIGURED zurück. Die von dieser Methode bereitgestellten Werte werden von Keymaster nur einmal pro Boot akzeptiert. Nachfolgende Aufrufe geben KM_ERROR_OK zurück, tun aber nichts.

Wenn sich die Keymaster-Implementierung in sicherer Hardware befindet und die bereitgestellten OS-Versions- und Patch-Level-Werte nicht mit den Werten übereinstimmen, die der Bootloader für die sichere Hardware bereitgestellt hat (oder wenn der Bootloader keine Werte bereitgestellt hat), gibt diese Methode KM_ERROR_INVALID_ARGUMENT und alle 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 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 über entweder die von addRngEntropy Bits oder die von der Hardware generierten Bits hat, aber nicht beide, 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 können ErrorCode::INVALID_INPUT_LENGTH wenn ihnen mehr als 2 KiB Daten in einem einzigen Aufruf übergeben werden.

Schlüssel generieren

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 unter Angabe zugehöriger Berechtigungen, die dauerhaft an den Schlüssel gebunden sind. Keymaster-Implementierungen machen es unmöglich, einen Schlüssel in irgendeiner Weise zu verwenden, die nicht mit den zum Zeitpunkt der Generierung angegebenen Berechtigungen übereinstimmt. In Bezug auf Autorisierungen, die die sichere Hardware nicht durchsetzen kann, beschränkt sich die Verpflichtung der sicheren Hardware darauf sicherzustellen, dass die dem Schlüssel zugeordneten nicht durchsetzbaren Autorisierungen nicht modifiziert 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 hardware- und software-erzwungenen Listen zu. Weitere Einzelheiten finden Sie unter getKeyCharacteristics .

Die Parameter, die für generateKey bereitgestellt werden, hängen von der Art des generierten Schlüssels ab. Dieser Abschnitt fasst die erforderlichen und optionalen Tags für jeden Schlüsseltyp zusammen. Tag::ALGORITHMUS ist immer notwendig, um den Typ anzugeben.

RSA-Schlüssel

Die folgenden Parameter sind notwendig, um einen RSA-Schlüssel zu generieren.

  • Tag::KEY_SIZE gibt die Größe des öffentlichen Moduls in Bits an. Wenn weggelassen, 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 weggelassen, 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 erforderlich, um einen RSA-Schlüssel zu generieren, aber das Erstellen eines RSA-Schlüssels ohne sie erzeugt einen unbrauchbaren Schlüssel. Die generateKey -Funktion gibt jedoch keinen Fehler zurück, wenn diese Parameter weggelassen werden.

  • Tag::PURPOSE gibt zulässige Zwecke an. Alle Zwecke müssen für RSA-Schlüssel 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 Schlüsselgenerierungsanforderungen akzeptieren, die nicht unterstützte Digests enthalten. Die nicht unterstützten Digests sollten in den zurückgegebenen Schlüsselmerkmalen in die Liste „softwareerzwungen“ aufgenommen werden. Dies liegt daran, dass der Schlüssel mit diesen anderen Digests verwendet werden kann, aber das Digest in der Software durchgeführt wird. Dann wird Hardware aufgerufen, um die Operation mit Digest::NONE durchzuführen.
  • Tag::PADDING gibt die Padding-Modi 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

Nur Tag::KEY_SIZE ist notwendig, um einen ECDSA-Schlüssel zu generieren. Es dient zur Auswahl der EC-Gruppe. Unterstützte Werte sind 224, 256, 384 und 521, die die NIST-Kurven p-224, p-256, p-384 bzw. p521 angeben.

Tag::DIGEST ist auch für einen brauchbaren ECDSA-Schlüssel notwendig, wird aber nicht zur Generierung benötigt.

AES-Schlüssel

Nur Tag::KEY_SIZE ist notwendig, um einen AES-Schlüssel zu generieren. Wenn weggelassen, gibt die Methode ErrorCode::UNSUPPORTED_KEY_SIZE zurück. Unterstützte Werte sind 128 und 256, mit optionaler Unterstützung für 192-Bit-AES-Schlüssel.

Die folgenden Parameter sind besonders relevant für AES-Schlüssel, 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 Padding-Modi an, die verwendet werden können. Dies ist nur für ECB- und CBC-Modi relevant.

Wenn der GCM-Blockmodus angegeben ist, geben Sie das Tag::MIN_MAC_LENGTH an . Wenn 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

Die folgenden Parameter sind für die HMAC-Schlüsselgenerierung 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 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 ist genau ein Digest angegeben, ansonsten ErrorCode::UNSUPPORTED_DIGEST . Wenn der Digest vom Trustlet nicht unterstützt wird, geben ErrorCode::UNSUPPORTED_DIGEST .

Schlüsseleigenschaften

Wenn das Merkmals-Argument nicht NULL ist, gibt generateKey die Merkmale des neu generierten Schlüssels zurück, die entsprechend in hardwareerzwungene und softwareerzwungene Listen unterteilt sind. Unter getKeyCharacteristics finden Sie eine Beschreibung, welche Merkmale in welche Liste aufgenommen werden. Die zurückgegebenen Merkmale umfassen alle Parameter, die für die Schlüsselgenerierung angegeben wurden, außer 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 es nicht möglich ist, ihre Werte durch Untersuchen des zurückgegebenen Schlüssel-Blobs zu finden. Sie sind jedoch kryptografisch an das Schlüssel-Blob gebunden, sodass die Verwendung fehlschlägt, wenn bei der Verwendung des Schlüssels nicht die richtigen Werte bereitgestellt werden. In ähnlicher Weise ist Tag::ROOT_OF_TRUST kryptografisch an den Schlüssel gebunden, kann jedoch während der Schlüsselerstellung oder des Imports nicht angegeben werden und wird nie zurückgegeben.

Zusätzlich zu den bereitgestellten Tags fügt das Trustlet auch Tag::ORIGIN mit dem Wert KeyOrigin::GENERATED , und wenn der Schlüssel Rollback-resistent 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 typischerweise generiertes oder importiertes Schlüsselmaterial als Schlüssel-Blob, eine verschlüsselte und authentifizierte Form, an den Aufrufer zurück. Wenn der Schlüsselspeicher das Schlüssel-Blob löscht, ist der Schlüssel weg, 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 das Speichern zusätzlicher Schlüsselmetadaten an einem vertrauenswürdigen Ort, der von einem Angreifer nicht manipuliert werden kann. Auf Mobilgeräten werden dafür in der Regel 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 Rollback-Widerstand verwendet wird, möglicherweise in der Größe begrenzt ist, muss diese Methode erfolgreich sein, selbst wenn Rollback-Widerstand für den neuen Schlüssel nicht 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 und in Keymaster 3 umbenannt.

Gibt Parameter und Autorisierungen zurück, die dem bereitgestellten Schlüssel zugeordnet sind, unterteilt in zwei Gruppen: hardwareerzwungen und softwareerzwungen. Die Beschreibung hier gilt gleichermaßen für die Schlüsselmerkmalslisten, die von generateKey und importKey zurückgegeben werden.

Wenn Tag::APPLICATION_ID während der Schlüsselgenerierung oder des Imports bereitgestellt wurde, wird dieser Methode im clientId Argument 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 derselbe Wert im appData Argument bereitgestellt.

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

Die allgemeine Regel für die Entscheidung, ob ein bestimmtes Tag in die hardwareerzwungene oder softwareerzwungene Liste gehört, lautet: Wenn die Bedeutung des Tags durch sichere Hardware vollständig gewährleistet ist, ist es hardwareerzwungen. Andernfalls wird es durch Software erzwungen. Nachfolgend finden Sie eine Liste bestimmter 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 hardwareerzwungenen Liste.
  • Tag::DIGEST- Werte, die von der sicheren Hardware unterstützt werden, werden in die Hardware-unterstützte Liste aufgenommen. Nicht unterstützte Digests werden in die Software-unterstützte Liste aufgenommen.
  • Tag::PADDING -Werte gehen im Allgemeinen in die Hardware-unterstützte Liste, es sei denn, es besteht die Möglichkeit, dass ein bestimmter Padding-Modus möglicherweise durch Software ausgeführt werden muss. In diesem Fall werden sie in die softwareerzwungene Liste aufgenommen. Eine solche Möglichkeit ergibt sich für RSA-Schlüssel, 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 durch Hardware erzwungen, wenn die Benutzerauthentifizierung durch Hardware erzwungen wird. Um dies zu erreichen, müssen das Keymaster-Trustlet und das relevante Authentifizierungstrustlet beide sicher sein und einen geheimen HMAC-Schlüssel teilen, der zum Signieren und Validieren von Authentifizierungstoken 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 steht bei hardwaregebundenen Schlüsseln immer in der Hardwareliste. Sein Vorhandensein in dieser Liste ist die Art und Weise, wie höhere Schichten feststellen, dass ein Schlüssel hardwareunterstützt ist.

importKey

Version : 1, 2, 3

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

Importiert Schlüsselmaterial in die Keymaster-Hardware. Schlüsseldefinitionsparameter und Ausgabemerkmale werden genauso behandelt wie bei generateKey , mit folgenden Ausnahmen:

  • Tag::KEY_SIZE und Tag::RSA_PUBLIC_EXPONENT (nur für RSA-Schlüssel) sind in den Eingabeparametern nicht erforderlich. Falls nicht bereitgestellt, leitet das Trustlet die Werte aus dem bereitgestellten Schlüsselmaterial ab und fügt den Schlüsselmerkmalen geeignete Tags und Werte hinzu. Wenn die Parameter bereitgestellt werden, validiert das Trustlet sie gegen das Schlüsselmaterial. 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 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 Imports bereitgestellt wurde, wird dieser Methode im clientId Argument 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 derselbe Wert im appData Argument bereitgestellt.

Schlüssel löschen

Version : 1, 2, 3

Diese Funktion wurde in Keymaster 1 als delete_key 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 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

Fassung : 3

Die Methode destroyAttestationIds() wird verwendet, um die neue (optionale, aber dringend empfohlene) ID-Beglaubigungsfunktion dauerhaft zu deaktivieren. Wenn das TEE keine Möglichkeit hat, sicherzustellen, dass die ID-Bestätigung nach dem Aufruf dieser Methode dauerhaft deaktiviert ist, darf die ID-Bestätigung überhaupt nicht implementiert werden. In diesem Fall tut diese Methode nichts 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 nichts aus und gibt ErrorCode::OK zurück.

Die einzigen Fehlercodes, die diese Methode zurückgeben kann, sind ErrorCode::UNIMPLEMENTED (wenn der ID-Nachweis 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.

Start

Version : 1, 2, 3

Startet einen kryptografischen Vorgang unter Verwendung des angegebenen Schlüssels für den angegebenen Zweck 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 Operations-Handle wird auch als "Challenge"-Token bei authentifizierten Operationen verwendet und ist für solche Operationen im challenge -Feld des Authentifizierungstokens enthalten.

Eine Keymaster-Implementierung unterstützt mindestens 16 gleichzeitige Operationen. Keystore verwendet bis zu 15, sodass vold einen für die Passwortverschlüsselung übrig lässt. Wenn Keystore 15 Operationen in Bearbeitung hat ( begin wurde aufgerufen, aber finish oder abort wurden noch nicht aufgerufen) und es eine Anforderung erhält, eine 16. zu beginnen, ruft es abort für die am längsten verwendete Operation auf, um die Anzahl der aktiven Operationen zu reduzieren bis 14 vor dem begin , um die neu angeforderte Operation zu starten.

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

Berechtigungsdurchsetzung

Während dieses Verfahrens werden die folgenden Schlüsselautorisierungen durch das Trustlet erzwungen, wenn die Implementierung sie in die "hardware-erzwungenen" Eigenschaften platziert hat und wenn die Operation keine Operation mit öffentlichem Schlüssel ist. Operationen mit öffentlichen Schlüsseln, d. h. KeyPurpose::ENCRYPT und KeyPurpose::VERIFY , mit RSA- oder EC-Schlüsseln dürfen erfolgreich sein, selbst 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 Public-Key-Operation. Wenn der angegebene Zweck nicht übereinstimmt und die Operation keine Public-Key-Operation ist, gibt begin ErrorCode::UNSUPPORTED_PURPOSE . 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 Tagwert 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 Zeitgeber verglichen, der die letzte Verwendung des Schlüssels anzeigt. Wenn die letzte Nutzungszeit plus Tag-Wert kleiner als die aktuelle Zeit ist, gibt die Methode ErrorCode::KEY_RATE_LIMIT_EXCEEDED zurück. In der Tag-Beschreibung finden Sie wichtige Implementierungsdetails.
  • 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 . Damit das Authentifizierungstoken gültig ist, müssen alle folgenden Punkte 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 ein Tag::USER_AUTH_TYPE , das 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 erlaubt dem Aufrufer, einen Nonce oder Initialisierungsvektor (IV) anzugeben. Wenn der Schlüssel dieses Tag nicht hat, aber der Aufrufer 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 der Bootloader die Ausführung beendet hat, gibt sie ErrorCode::INVALID_KEY_BLOB zurück.

RSA-Schlüssel

Alle RSA-Schlüsseloperationen geben genau einen Padding-Modus in inParams an. Wenn nicht angegeben oder mehr als einmal angegeben, gibt die Methode ErrorCode::UNSUPPORTED_PADDING_MODE zurück.

RSA-Signatur- und -Verifizierungsoperationen benötigen einen Digest, ebenso wie RSA-Verschlüsselungs- und -Entschlüsselungsoperationen mit dem OAEP-Padding-Modus. Für diese Fälle 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.

Operationen mit privaten Schlüsseln ( 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 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-Padding-Modi nur für bestimmte Zwecke anwendbar. Insbesondere unterstützen PaddingMode::RSA_PKCS1_1_5_SIGN und PaddingMode::RSA_PSS nur Signieren und Verifizieren, 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 Interaktionen zwischen Padding-Modi und Digests:

  • PaddingMode::NONE gibt an, dass eine "rohe" RSA-Operation durchgeführt wird. Beim Signieren oder Verifizieren wird Digest::NONE für den Digest angegeben. Für die nicht aufgefüllte Verschlüsselung oder Entschlüsselung ist kein Digest erforderlich.
  • PaddingMode::RSA_PKCS1_1_5_SIGN Padding erfordert einen Digest. Der Digest kann Digest::NONE sein, in diesem Fall kann die Keymaster-Implementierung keine richtige 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 Bytes größer sein als die Nachricht, ansonsten gibt die Methode ErrorCode::INVALID_INPUT_LENGTH zurück.
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT Padding erfordert keinen Digest.
  • PaddingMode::RSA_PSS Padding erfordert einen Digest, der möglicherweise nicht Digest::NONE ist. 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 sein als die Ausgabegröße des Digest, wobei D die Größe des Digest in Byte ist. Andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück. Die Salzgröße ist D.
  • PaddingMode::RSA_OAEP Padding erfordert einen Digest, 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 Padding-Modus 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 ErrorCode::INCOMPATIBLE_DIGEST . Operationen mit öffentlichen Schlüsseln ( KeyPurpose::VERIFY ) sind mit nicht autorisiertem Digest oder Padding zulässig.

AES-Schlüssel

AES-Tastenoperationen spezifizieren genau einen Blockmodus und einen Paddingmodus in inParams . Wenn einer der Werte nicht angegeben oder mehr als einmal angegeben ist, wird ErrorCode::UNSUPPORTED_BLOCK_MODE oder ErrorCode::UNSUPPORTED_PADDING_MODE . Die angegebenen Modi müssen durch den Schlüssel autorisiert werden, ansonsten gibt die Methode ErrorCode::INCOMPATIBLE_BLOCK_MODE oder ErrorCode::INCOMPATIBLE_PADDING_MODE .

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. Geben Sie für MAC-Längen größer als 128 oder Nicht-Vielfache von 8 ErrorCode::UNSUPPORTED_MAC_LENGTH . Geben Sie für Werte kleiner als die Mindestlänge des Schlüssels ErrorCode::INVALID_MAC_LENGTH .

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 . Wenn der Auffüllmodus diese Bedingungen nicht erfüllt, geben ErrorCode::INCOMPATIBLE_PADDING_MODE .

Wenn der Blockmodus BlockMode::CBC , BlockMode::CTR oder BlockMode::GCM ist, wird ein Initialisierungsvektor oder eine Nonce benötigt. 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 . CBC- und CTR-IVs sind 16 Bytes groß. GCM-Nonces sind 12 Bytes. Wenn die Schlüsselberechtigungen Tag::CALLER_NONCE enthalten, kann der Aufrufer eine IV/Nonce mit Tag::NONCE in inParams . Wenn ein Nonce bereitgestellt wird, wenn Tag::CALLER_NONCE nicht autorisiert ist, wird ErrorCode::CALLER_NONCE_PROHIBITED . Wenn keine Nonce bereitgestellt wird, wenn Tag::CALLER_NONCE autorisiert ist, generieren Sie eine zufällige 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 oder kleiner als der Wert von Tag::MIN_MAC_LENGTH in den Schlüsselberechtigungen ist. Geben Sie für MAC-Längen größer als die Digest-Länge oder Nicht-Vielfache von 8 ErrorCode::UNSUPPORTED_MAC_LENGTH . Geben Sie für Werte kleiner als die Mindestlänge des Schlüssels ErrorCode::INVALID_MAC_LENGTH .

aktualisieren

Version : 1, 2, 3

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

Um mehr Flexibilität für die Pufferbehandlung bereitzustellen, haben Implementierungen dieses Verfahrens die Option, weniger Daten zu verbrauchen, als bereitgestellt wurden. Der Aufrufer ist für die Schleife verantwortlich, um den Rest der Daten in nachfolgenden Aufrufen einzuspeisen. Die verbrauchte Eingabemenge wird im inputConsumed Parameter zurückgegeben. Implementierungen verbrauchen immer mindestens ein Byte, es sei denn, die Operation kann kein weiteres akzeptieren; Wenn mehr als null Bytes bereitgestellt und null Bytes verbraucht werden, betrachten Aufrufer dies als Fehler und brechen die Operation ab.

Implementierungen können auch wählen, wie viele Daten als Ergebnis der Aktualisierung zurückgegeben werden sollen. Dies ist nur für Verschlüsselungs- und Entschlüsselungsvorgänge relevant, da das Signieren und Verifizieren keine Daten zurückgibt, bis finish . 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 , 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.

Berechtigungsdurchsetzung

Die Erzwingung der Schlüsselautorisierung wird hauptsächlich in begin durchgeführt. Die einzige Ausnahme ist der Fall, in dem der Schlüssel Folgendes hat:

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

Der Aufrufer stellt das Authentifizierungstoken für jeden Aufruf bereit, um ihn zu aktualisieren und abzuschließen . Die Implementierung muss das Token nur einmal validieren, wenn sie dies vorzieht.

RSA-Schlüssel

Für Signier- und Verifizierungsvorgänge mit Digest::NONE akzeptiert diese Methode den gesamten zu signierenden oder zu verifizierenden Block in einer einzigen Aktualisierung. 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), geben ErrorCode::INVALID_INPUT_LENGTH .

ECDSA-Schlüssel

Für Signier- und Verifizierungsvorgänge mit Digest::NONE akzeptiert diese Methode den gesamten zu signierenden oder zu verifizierenden Block in einer einzigen Aktualisierung. Dieses Verfahren darf nicht nur einen Teil des Blocks verbrauchen.

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, werden die Daten stillschweigend abgeschnitten. (Dies unterscheidet sich von der Handhabung überschüssiger Daten, die in ähnlichen RSA-Vorgängen bereitgestellt werden. Der Grund dafür ist die Kompatibilität mit Legacy-Clients.)

AES-Schlüssel

Der AES-GCM-Modus unterstützt „assoziierte 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 sie in einem einzelnen Block zu senden), gehen jedoch immer den zu verschlüsselnden oder zu entschlüsselnden Daten voraus. Ein Aktualisierungsaufruf kann sowohl zugeordnete Daten als auch Daten zum Verschlüsseln/Entschlüsseln empfangen, aber nachfolgende Aktualisierungen enthalten möglicherweise keine zugeordneten Daten. Wenn der Aufrufer nach einem Aufruf, der Daten zum Verschlüsseln/Entschlüsseln enthält, zugeordnete Daten für einen Aktualisierungsaufruf bereitstellt, wird ErrorCode::INVALID_TAG .

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 dem letzten Aktualisierungsaufruf bereitgestellt wurden, das Tag. Da ein gegebener Update -Aufruf nicht wissen kann, ob es der letzte Aufruf ist, verarbeitet er alles außer der Tag-Länge und puffert die möglichen Tag-Daten während finish .

Fertig

Version : 1, 2, 3

Beendet eine laufende Operation, die mit begin gestartet wurde, und verarbeitet alle noch nicht verarbeiteten Daten, die von update (s) bereitgestellt werden.

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

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

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

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

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure