Keymaster-Funktionen

Auf dieser Seite finden Sie Details, die Implementierern von Keymaster-Hardware-Abstraktionsschichten (HALs) helfen sollen. Es werden alle Funktionen in der API und die Keymaster-Versionen beschrieben, in denen diese Funktionen verfügbar sind. Außerdem wird die Standardimplementierung beschrieben. Informationen zu Tags findest du auf der Seite Keymaster-Tags.

Allgemeine Implementierungsrichtlinien

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

Eingabezeigerparameter

Version: 1, 2

Eingabezeigerparameter, die für einen bestimmten Aufruf nicht verwendet werden, können NULL sein. Der Aufrufer muss keine Platzhalter angeben. Bei einigen Schlüsseltypen und -modi werden beispielsweise keine Werte aus dem inParams-Argument für begin verwendet. Der Aufrufer kann inParams dann auf NULL setzen 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. 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. Alle Parameter werden per Wert oder Konstantenreferenz übergeben.

API-Missbrauch

Version: 1, 2, 3

Es gibt viele Möglichkeiten, wie Anrufer Anfragen stellen können, die keinen Sinn ergeben oder dumm 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 IVs oder Nonces, die zwecklose Erzeugung von Schlüsseln (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-Schlüsselspeichers, dafür zu sorgen, dass die Aufrufe von Keymaster-Modulen sinnvoll und nützlich sind.

Funktionen

getHardwareFeatures

Version: 3

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

• isSecure ist true, wenn Schlüssel auf sicherer Hardware (TEE usw.) gespeichert werden und niemals verlassen werden.
• supportsEllipticCurve ist true, wenn die Hardware 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 nach dem Öffnen des Geräts und vor der Verwendung aufgerufen. Damit werden KM_TAG_OS_VERSION und KM_TAG_OS_PATCHLEVEL an Keymaster gesendet. Bis zum Aufruf dieser Methode 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 der Bootloader der sicheren Hardware zur Verfügung gestellt hat (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ügt dem Pool, der von der Implementierung von Keymaster 1 zum Generieren von Zufallszahlen, für Schlüssel, IVs usw. verwendet wird, die vom Anrufer bereitgestellte Entropie hinzu.

Keymaster-Implementierungen müssen die bereitgestellte Entropie sicher in ihren Pool einmischen, der auch intern generierte Entropie aus 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 ihnen in einem einzigen Aufruf mehr als 2 KiB Daten zur Verfügung gestellt werden.

generateKey

Version: 1, 2, 3

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

Erzeugt einen neuen kryptografischen Schlüssel, der zugehörige Autorisierungen angibt, die dauerhaft an den Schlüssel gebunden 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. In Bezug auf Autorisierungen, die die sichere Hardware nicht durchsetzen kann, beschränkt sich die Verpflichtung der sicheren Hardware darauf, sicherzustellen, dass die nicht durchsetzbaren Autorisierungen, 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 erforderlich, um einen RSA-Schlüssel zu generieren.

• Tag::KEY_SIZE gibt die Größe des öffentlichen Modulus in Bit 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.
• Mit Tag::RSA_PUBLIC_EXPONENT wird der Wert des öffentlichen RSA-Exponenten angegeben. 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 erforderlich, um einen RSA-Schlüssel zu generieren. 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.

• Mit Tag::PURPOSE werden zulässige Zwecke angegeben. RSA-Schlüssel müssen für 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 Hash-Werte sollten in der Liste „software enforced“ (softwaregestützt) in den zurückgegebenen Schlüsselmerkmalen 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üsseleigenschaften aufgenommen werden, wenn nicht unterstützte Digest-Algorithmen angegeben sind.

ECDSA-Schlüssel

Zum Generieren eines ECDSA-Schlüssels ist nur Tag::KEY_SIZE erforderlich. Damit 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 erforderlich, um einen AES-Schlüssel zu generieren. Wenn sie weggelassen wird, gibt die Methode ErrorCode::UNSUPPORTED_KEY_SIZE zurück. Unterstützte Werte sind 128 und 256, wobei optional 192-Bit-AES-Schlüssel unterstützt werden.

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-Blockmodus angegeben ist, geben Sie Tag::MIN_MAC_LENGTH an. Wenn sie 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 die folgenden Parameter erforderlich:

• Tag::KEY_SIZE gibt die Schlüsselgröße in Bits 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 für die Eigenschaften nicht NULL ist, gibt generateKey die Eigenschaften des neu generierten Schlüssels entsprechend in hardwareerzwungene und durch Software erzwungene Listen unterteilt zurück. 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 Eigenschaften entfernt, damit ihre Werte nicht durch Untersuchung 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 bereitgestellten Tags fügt das Trustlet Tag::ORIGIN mit dem Wert KeyOrigin::GENERATED hinzu. Wenn der Schlüssel rollback-resistent ist,

Tag::ROLLBACK_RESISTANT.

Rollback-Sperre

Rollback-Resistenz bedeutet, dass ein Schlüssel, der mit deleteKey oder deleteAllKeys gelöscht wurde, 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 das Schlüssel-Blob löscht, ist der Schlüssel entfernt. Ein Angreifer, der zuvor das Schlüsselmaterial abgerufen hat, kann es jedoch möglicherweise auf dem Gerät wiederherstellen.

Ein Schlüssel ist rollback-resistent, wenn die sichere Hardware dafür sorgt, dass gelöschte Schlüssel nicht später wiederhergestellt werden können. Dazu werden in der Regel zusätzliche Schlüsselmetadaten an einem vertrauenswürdigen 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 Wesentlichen unbegrenzt ist und der vertrauenswürdige Speicher, der für die Rollback-Widerstandsfähigkeit verwendet wird, möglicherweise in der Größe begrenzt ist, muss diese Methode erfolgreich sein, auch wenn für den neuen Schlüssel keine Rollback-Widerstandskraft bereitgestellt werden kann. In diesem Fall sollte Tag::ROLLBACK_RESISTANT nicht zu den wichtigsten Merkmalen 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 bereitgestellten Schlüssel verknüpft sind, aufgeteilt in zwei Sätze: hardwareerzwungen und durch Software erzwungen. Die Beschreibung gilt gleichermaßen für die Listen mit Schlüsselmerkmalen, 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 bei der Entscheidung, ob ein bestimmtes Tag in die Liste der Hardware- oder Softwareerzwingung aufgenommen wird, besagt Folgendes: Wenn die Bedeutung des Tags von der sicheren Hardware vollständig bestätigt wird, wird es hardwareerzwingt. 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.
• Werte für Tag::PADDING werden in der Regel in die Liste der von der Hardware unterstü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 Richtlinienverstöße 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 der Zugriff auf eine nachweislich korrekte Systemzeit erforderlich. Die meisten sicheren Hardwaregeräte haben nur Zugriff auf Zeitinformationen, die vom nicht sicheren 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. Parameter zur Schlüsseldefinition und Ausgabemerkmale werden genauso behandelt wie für generateKey, 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.
• 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 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.

Schlüssel löschen

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 der TEE nicht sicherstellen kann, dass die ID-Attestierung nach dem Aufruf dieser Methode dauerhaft deaktiviert ist, darf die ID-Attestierung überhaupt nicht implementiert werden. In diesem Fall wird bei dieser Methode nichts ausgeführt und ErrorCode::UNIMPLEMENTED zurückgegeben. Wenn die Ausweisattestierung unterstützt wird, muss diese Methode implementiert und alle zukünftigen Versuche zur Ausweisattestierung dauerhaft deaktiviert werden. Die Methode kann beliebig oft aufgerufen werden. Wenn die ID-Attestierung bereits dauerhaft deaktiviert ist, funktioniert die Methode nichts 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.

beginnen

Version: 1, 2, 3

Beginnt einen kryptografischen Vorgang mit dem angegebenen Schlüssel, dem angegebenen Zweck und den angegebenen Parametern (falls 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 „Challenge“-Token in authentifizierten Vorgängen verwendet und ist für solche Vorgänge 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 vold zur Passwortverschlüsselung übrig bleibt. Wenn im Schlüsselspeicher 15 Vorgänge ausgeführt werden (begin wurde aufgerufen, aber finish oder abort wurden nicht aufgerufen) und eine Anfrage zum Starten eines 16. Vorgangs erhält, wird für den zuletzt verwendeten Vorgang abort aufgerufen, um die Anzahl der aktiven Vorgänge auf 14 zu reduzieren. Erst dann wird begin aufgerufen, 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 Eigenschaften „hardwaregestützt“ eingeordnet 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 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 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 Verwendungen des Schlüssels seit dem Start erfasst. 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 von dieser Methode nur erzwungen, wenn der Schlüssel außerdem Tag::AUTH_TIMEOUT enthält. 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 erfüllt sein:
  • Das HMAC-Feld wird korrekt validiert.
  • Mindestens einer der Werte Tag::USER_SECURE_ID aus dem Schlüssel stimmt mit mindestens einem der Secure-ID-Werte im Token überein.
  • Der Schlüssel hat das Tag Tag::USER_AUTH_TYPE, das 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 dem Aufrufer, eine Nonce oder einen Initialisierungsvektor (IV) anzugeben. Wenn der Schlüssel dieses Tag nicht enthält, der Aufrufer aber Tag::NONCE an diese Methode übergeben 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. Falls nicht angegeben oder mehrmals angegeben, gibt die Methode ErrorCode::UNSUPPORTED_DIGEST zurück.

Für Vorgänge mit privaten Schlüsseln (KeyPurpose::DECYPT und KeyPurpose::SIGN) ist eine Autorisierung für Digest 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. Public-Key-Vorgänge (KeyPurpose::ENCRYPT und KeyPurpose::VERIFY) sind mit nicht autorisierten Digests 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 die Signatur und Überprüfung, 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 Interaktionen zwischen Padding-Modi und Digests:

• PaddingMode::NONE gibt an, dass ein „roher“ 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. Darüber hinaus muss der RSA-Schlüssel mindestens 2 + D Byte größer als die Ausgabegröße des Digests sein, wobei D die Größe des Digest in Byte ist. Andernfalls gibt die Methode ErrorCode::INCOMPATIBLE_DIGEST zurück. Die Salzgröße ist D.
• Für die PaddingMode::RSA_OAEP-Auslieferung 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 angegeben oder mehrmals angegeben ist, wird ErrorCode::UNSUPPORTED_BLOCK_MODE oder ErrorCode::UNSUPPORTED_PADDING_MODE zurückgegeben. 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. Für MAC-Längen über 128 oder ein Nicht-Vielfaches von 8 wird ErrorCode::UNSUPPORTED_MAC_LENGTH zurückgegeben. 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 Anrufer 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 einen IV oder eine 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, generieren Sie eine zufällige 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 mehr Flexibilität bei der Zwischenspeicherbehandlung zu bieten, können Implementierungen dieser Methode weniger Daten verbrauchen, als bereitgestellt wurde. Der Aufrufer ist für Schleifen verantwortlich, um bei nachfolgenden Aufrufen den Rest der Daten einzuspeisen. 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 nicht mehr akzeptieren. 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 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 Handles mit dieser Methode, finish oder abort, wird ErrorCode::INVALID_OPERATION_HANDLE zurückgegeben.

Autorisierung erzwingen

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

• ein oder mehrere Tag::USER_SECURE_IDs und
• Es ist kein Tag::AUTH_TIMEOUT vorhanden.

In diesem Fall ist für den Schlüssel eine Autorisierung pro Vorgang erforderlich und die Updatemethode erhält ein Tag::AUTH_TOKEN im Argument inParams. 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. Die Implementierung muss das Token nach Belieben nur einmal validieren.

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 verifiziert 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 verifiziert 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 bereitstellt, als verwendet werden können, werden die Daten automatisch abgeschnitten. (Dies unterscheidet sich von der Verarbeitung überschüssiger Daten, die in ä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 „verknüpfte 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. Bei einem Aktualisierungsaufruf können zum Verschlüsseln/Entschlüsseln sowohl zugehörige Daten als auch Daten empfangen werden. Nachfolgende Aktualisierungen können jedoch keine zugehörigen Daten enthalten. Wenn der Aufrufer zugehörige Daten einem Updateaufruf zur Verfügung stellt, nachdem er Daten zum Verschlüsseln/Entschlüsseln enthält, wird ErrorCode::INVALID_TAG zurückgegeben.

Bei der GCM-Verschlüsselung wird das Tag durch Finish an den Geheimtext angehängt. Während der Entschlüsselung sind die letzten Tag::MAC_LENGTH Byte der Daten, die dem letzten Aktualisierungsaufruf zur Verfügung gestellt 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(s) 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 Handles 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 Durchsetzung der Schlüsselautorisierung erfolgt hauptsächlich in begin. Die einzige Ausnahme ist, wenn der Schlüssel Folgendes enthält:

• Eine oder mehrere Tag::USER_SECURE_IDs und
• 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 Argument inParams. 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. Die Implementierung muss das Token nur einmal validieren, wenn dies gewünscht wird.

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 unter 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. PKCS#7 empfiehlt das Hinzufügen eines zusätzlichen Padding-Blocks, 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. Verarbeite bei der Entschlüsselung die letzten Tag::MAC_LENGTH Byte als Tag. Wenn die Tag-Überprüfung fehlschlägt, geben Sie ErrorCode::VERIFICATION_FAILED zurück.

abort

Version: 1, 2, 3

Bricht den laufenden Vorgang ab. Gib nach dem Abbruch 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 Hybridimplementierung 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 angegebenen 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 Implementierungen von Keymaster 1 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.
• Modi für PKCS#1 v1.5-Verschlüsselung und Signierabstände
• 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.

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

Implementierungen von Keymaster 1 können eine Teilmenge der definierten Digests 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 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 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