Keymaster-Autorisierungs-Tags

Auf dieser Seite finden Sie Details, die Implementierern von Keymaster HALs helfen sollen. Sie enthält Informationen zu jedem Tag in der HAL, in welcher Keymaster-Version das Tag verfügbar ist und ob es wiederholbar ist. Außer wie in den Tag-Beschreibungen angegeben, werden alle folgenden Tags bei der Schlüsselgenerierung verwendet, um Schlüsselmerkmale anzugeben.

Für Keymaster 4 werden Tags in platform/hardware/interfaces/keymaster/keymaster-version/types.hal, zum Beispiel 3.0/types.hal für Keymaster 3 und 4.0/types.hal für Keymaster 4. Für Keymaster 2 und niedriger werden Tags in platform/hardware/libhardware/include/hardware/keymaster_defs.h

Informationen zu Funktionen finden Sie in der Keymaster-Funktionen.

Tag::ACTIVE_DATETIME

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt das Datum und die Uhrzeit an, zu der der Schlüssel aktiv wird. Vor diesem Datum schlägt jeder Versuch, den Schlüssel zu verwenden, mit ErrorCode::KEY_NOT_YET_VALID fehl.

Der Wert ist eine 64-Bit-Ganzzahl, die die Millisekunden seit dem 1. Januar 1970 angibt.

Tag::ALGORITHM

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt den kryptografischen Algorithmus an, mit dem der Schlüssel verwendet wird.

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 und älter 
typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Tag::ALL_APPLICATIONS

Version: 1, 2, 3, 4

Wiederholbar? Nein

Reserviert für zukünftige Verwendungen.

Tag::ALLOW_WHILE_ON_BODY

Version: 2, 3, 4

Wiederholbar? Nein

Dieses Tag gilt nur für Android Wear-Geräte mit Tragesensoren. Bei Es ist nicht zu erwarten, dass TEE einen sicheren Zugang oder dass die Tragesensoren sehr sicher sind. wird erwartet, dass es sich dabei um eine rein softwarebasierte Funktion handelt.

Tag::ALL_USERS

Version: 3, 4

Wiederholbar? Nein

Reserviert für zukünftige Verwendung.

Tag::APPLICATION_DATA

Version: 1, 2, 3, 4

Wiederholbar? Nein

Wenn bereitgestellt für generateKey oder importKey, Dieses Tag gibt Daten an, die bei jeder Verwendung des Schlüssels erforderlich sind. Insbesondere müssen Aufrufe von exportKey und getKeyCharacteristics denselben Wert für den Parameter clientId angeben. Aufrufe von begin müssen dieses Tag und dieselben zugehörigen Daten als Teil des inParams-Sets angeben. Wenn die richtigen Daten nicht angegeben werden, gibt die Funktion ErrorCode::INVALID_KEY_BLOB zurück.

Der Inhalt dieses Tags ist kryptografisch an den Schlüssel gebunden. Das bedeutet, dass es für einen Angreifer, der Zugriff auf alle Geheimnisse der sicheren Welt hat, aber keinen Zugriff auf den Tag-Inhalt hat, nicht möglich sein darf, den Schlüssel zu entschlüsseln, ohne den Tag-Inhalt per Brute-Force-Methode zu knacken. Dies kann durch die Angabe von Inhalten mit ausreichend hoher Entropie verhindert werden.

Der Wert ist ein Blob, ein Byte-Array beliebiger Länge.

Tag::APPLICATION_ID

Version: 1, 2, 3, 4

Wiederholbar? Nein

Wenn dieses Tag für generateKey oder importKey angegeben wird, werden damit Daten angegeben, die bei jeder Verwendung des Schlüssels erforderlich sind. In insbesondere Aufrufe an exportKey und getKeyCharacteristics müssen im Parameter clientId denselben Wert angeben und müssen für beginnen dieses Tag und die gleichen zugehörigen Daten als Teil des inParams festgelegt. Wenn die richtigen Daten nicht angegeben werden, gibt die Funktion ErrorCode::INVALID_KEY_BLOB zurück.

Der Inhalt dieses Tags ist kryptografisch an den Schlüssel gebunden, also ein Angreifer, der Zugang zu allen sicheren Geheimnissen der Welt hat. keinen Zugriff auf den Tag-Inhalt – die Funktion kann nicht entschlüsselt werden. key (ohne Brute-Force-Regelung auf den Tag-Inhalt) zu kopieren.

Der Wert ist ein Blob, ein Byte-Array beliebiger Länge.

Tag::ASSOCIATED_DATA

Version: 1, 2, 3, 4

Wiederholbar? Nein

Stellt „zugeordnete Daten“ für die AES-GCM-Verschlüsselung oder -Entschlüsselung bereit. Dieses Tag ist zum Aktualisieren und gibt Daten an, die nicht verschlüsselt/entschlüsselt werden, aber in der Datenverarbeitung verwendet werden. das GCM-Tag verwenden.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_APPLICATION_ID

Version: 3, 4

Wiederholbar? Nein

Wird verwendet, um die möglichen Apps von welcher zu ermitteln hat eine Schlüsselattestierung initiiert.

Der Wert ist ein Blob, ein Byte-Array beliebiger Länge.

Tag::ATTESTATION_CHALLENGE

Version: 3, 4

Wiederholbar? Nein

Wird verwendet, um eine Identitätsbestätigung durchzuführen.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_ID_BRAND

Version: 3, 4

Wiederholbar? Nein

Der Markenname des Geräts, wie von Build.BRAND unter Android zurückgegeben. Dieses Feld wird nur festgelegt, wenn die Attestierung der Geräte-IDs angefordert wird.

Wenn das Gerät die ID-Attestierung nicht unterstützt (oder destroyAttestationIds() wurde bereits angerufen und das Gerät kann seine IDs nicht mehr attestiert), werden alle Schlüsselattestierungsanfragen, die Dieses Tag schlägt mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_ID_DEVICE

Version: 3, 4

Wiederholbar? Nein

Gibt den von Build.DEVICE zurückgegebenen Gerätenamen an in Android. Dieses Feld wird nur festgelegt, wenn die Attestierung der Geräte-IDs angefordert wird.

Wenn das Gerät die ID-Attestierung nicht unterstützt (oder destroyAttestationIds() wurde bereits angerufen und das Gerät kann seine IDs nicht mehr attestiert), werden alle Schlüsselattestierungsanfragen, die Dieses Tag schlägt mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_ID_IMEI

Version: 3, 4

Wiederholbar? Ja

Gibt die IMEIs für alle Funkschnittstellen auf dem Gerät an. Dieses Feld wird nur wenn Sie die Bestätigung der Gerätekennungen anfordern.

Wenn das Gerät die Identitätsattestierung nicht unterstützt (oder destroyAttestationIds() bereits aufgerufen wurde und das Gerät seine IDs nicht mehr attestieren kann), schlägt jede Schlüsselattestierungsanfrage mit diesem Tag mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_ID_MANUFACTURER

Version: 3, 4

Wiederholbar? Nein

Gibt den Herstellernamen des Geräts an, wie er vom Build.MANUFACTURER für Android. Dieses Feld wird nur festgelegt, wenn die Attestierung der Geräte-IDs angefordert wird.

Wenn das Gerät die ID-Attestierung nicht unterstützt (oder destroyAttestationIds() wurde bereits angerufen und das Gerät kann seine IDs nicht mehr attestiert), werden alle Schlüsselattestierungsanfragen, die Dieses Tag schlägt mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_ID_MEID

Version: 3, 4

Wiederholbar? Ja

Stellt die MEIDs für alle Funkschnittstellen auf dem Gerät bereit. Dieses Feld wird nur wenn Sie die Bestätigung der Gerätekennungen anfordern.

Wenn das Gerät die Identitätsattestierung nicht unterstützt (oder destroyAttestationIds() bereits aufgerufen wurde und das Gerät seine IDs nicht mehr attestieren kann), schlägt jede Schlüsselattestierungsanfrage mit diesem Tag mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::ATTESTATION_ID_MODEL

Version: 3, 4

Wiederholbar? Nein

Der Modellname des Geräts, wie von Build.MODEL in Android zurückgegeben. Dieses Feld wird nur festgelegt, und fordert die Bestätigung der Gerätekennungen an.

Wenn das Gerät die ID-Attestierung nicht unterstützt (oder destroyAttestationIds() wurde bereits angerufen und das Gerät kann seine IDs nicht mehr attestiert), werden alle Schlüsselattestierungsanfragen, die Dieses Tag schlägt mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array beliebiger Länge.

Tag::ATTESTATION_ID_PRODUCT

Version: 3, 4

Wiederholbar? Nein

Der Produktname des Geräts, wie von Build.PRODUCT unter Android zurückgegeben. Dieses Feld wird nur festgelegt, und fordert die Bestätigung der Gerätekennungen an.

Wenn das Gerät die ID-Attestierung nicht unterstützt (oder destroyAttestationIds() wurde bereits angerufen und das Gerät kann seine IDs nicht mehr attestiert), werden alle Schlüsselattestierungsanfragen, die Dieses Tag schlägt mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array beliebiger Länge.

Tag::ATTESTATION_ID_SERIAL

Version: 3, 4

Wiederholbar? Nein

Gibt die Seriennummer des Geräts an. Dieses Feld wird nur festgelegt, wenn die Attestierung der Geräte-IDs angefordert wird.

Wenn das Gerät die ID-Attestierung nicht unterstützt (oder destroyAttestationIds() wurde bereits angerufen und das Gerät kann seine IDs nicht mehr attestiert), werden alle Schlüsselattestierungsanfragen, die Dieses Tag schlägt mit ErrorCode::CANNOT_ATTEST_IDS fehl.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge.

Tag::AUTH_TIMEOUT

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die Zeit in Sekunden an, in der der Schlüssel zur Verwendung autorisiert ist, nach dem Authentifizierung. Wenn Tag::USER_SECURE_ID vorhanden ist und dieses Tag nicht, muss der Schlüssel bei jeder Verwendung authentifiziert werden. Details zum Ablauf der Authentifizierung pro Vorgang findest du unter begin.

Der Wert ist eine 32-Bit-Ganzzahl, die die Zeit in Sekunden nach einem erfolgreiche Authentifizierung des mit Tag::USER_SECURE_ID angegebenen Nutzers mit der Authentifizierungsmethode durch Tag::USER_AUTH_TYPE angegeben, dass der Schlüssel verwendet.

Tag::AUTH_TOKEN

Version: 1, 2, 3, 4

Wiederholbar? Nein

Stellt ein Authentifizierungstoken bereit, um anzufangen, zu aktualisieren oder abzuschließen und die Nutzerauthentifizierung für einen wichtigen Vorgang nachzuweisen, der dies erfordert (Schlüssel hat Tag::USER_SECURE_ID).

Der Wert ist ein Blob, der eine hw_auth_token_t-Struktur enthält.

Tag::BLOB_USAGE_REQUIREMENTS

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die erforderlichen Systemumgebungsbedingungen für den generierten Schlüssel, der verwendet werden soll.

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 und älter 
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

Dieses Tag kann bei der Schlüsselgenerierung angegeben werden, um zu erzwingen, dass der Schlüssel unter der angegebenen Bedingung verwendet werden kann. Er muss mit den Schlüsselmerkmalen aus generateKey und getKeyCharacteristics zurückgegeben werden. Wenn der Aufrufer Tag::BLOB_USAGE_REQUIREMENTS mit dem Wert KeyBlobUsageRequirements::STANDALONE angibt, gibt das Trustlet einen Schlüssel-Blob zurück, der ohne Dateisystemunterstützung verwendet werden kann. Das ist wichtig für Geräte, mit verschlüsselten Laufwerken, bei denen das Dateisystem möglicherweise erst nachdem das Laufwerk mit einem Keymaster-Schlüssel entschlüsselt wurde.

Tag::BLOCK_MODE

Version: 1, 2, 3, 4

Wiederholbar? Ja

Gibt die Blockverschlüsselungsmodi an, mit denen der Schlüssel verwendet werden kann. Dieses Tag ist nur für AES-Schlüssel relevant.

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 und frühere Versionen 
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Dieses Tag kann wiederholt werden. Geben Sie für AES-Schlüsselvorgänge einen Modus im additionalParams-Argument von begin an. Wenn der angegebene Modus nicht den mit dem Schlüssel verknüpften Modi entspricht, wird der schlägt mit ErrorCode::INCOMPATIBLE_BLOCK_MODE fehl.

Tag::BOOT_PATCHLEVEL

Version: 4

Mit Tag::BOOT_PATCHLEVEL wird die Sicherheitspatchebene des Boot-Images (Kernel) angegeben, mit der der Schlüssel verwendet werden kann. Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von diesem der hardwaregestützten Autorisierungsliste hinzugefügt. Wenn Sie versuchen, einen Schlüssel mit einem Tag::BOOT_PATCHLEVEL-Wert zu verwenden, der sich von der aktuell ausgeführten System-Patchebene unterscheidet, wird für begin(), getKeyCharacteristics() oder exportKey() der Wert ErrorCode::KEY_REQUIRES_UPGRADE zurückgegeben. Weitere Informationen finden Sie unter upgradeKey().

Der Wert des Tags ist eine Ganzzahl im Format JJJJMMTT, wobei JJJJ der Wert für das vierstellige Jahr der letzten Aktualisierung, MM der zweistellige Monat und TT der zweistelliger Tag der letzten Aktualisierung. Für einen Schlüssel, der für eine Android-Gerät zuletzt am 5. Juni 2018 aktualisiert, lautet der Wert „20180605“. Wenn der Tag nicht bekannt ist, kann „00“ verwendet werden.

Bei jedem Start muss der Bootloader der sicheren Umgebung die Patchebene des Boot-Images zur Verfügung stellen (der Mechanismus ist implementierungsspezifisch).

Muss hardwareseitig erzwungen werden.

Tag::BOOTLOADER_ONLY

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, dass nur der Bootloader den Schlüssel verwenden kann.

Dieses Tag ist boolesch, daher sind die möglichen Werte "true" (falls das Tag vorhanden ist) und false (wenn das Tag nicht vorhanden ist).

Jeder Versuch, einen Schlüssel mit Tag::BOOTLOADER_ONLY aus dem Android-System schlägt mit ErrorCode::INVALID_KEY_BLOB fehl.

Tag::CALLER_NONCE

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, dass der Aufrufer für Vorgänge, die ein Nonce erfordern, ein Nonce angeben kann.

Dieses Tag ist boolescher Natur. Die möglichen Werte sind „true“ (wahr, wenn das Tag vorhanden ist) und „false“ (falsch, wenn das Tag nicht vorhanden ist).

Dieses Tag wird nur für AES-Schlüssel verwendet und ist nur für die Blockmodi CBC, CTR und GCM relevant. Wenn das Tag nicht vorhanden ist, sollten Implementierungen alle Vorgänge ablehnen, bei denen Tag::NONCE mit ErrorCode::CALLER_NONCE_PROHIBITED beginnt.

Tag::CREATION_DATETIME

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt das Datum und die Uhrzeit an, zu der der Schlüssel erstellt wurde, in Millisekunden seit 1. Januar 1970. Dieses Tag ist optional und dient nur zu Informationszwecken.

Tag::DIGEST

Version: 1, 2, 3, 4

Wiederholbar? Ja

Gibt die Hash-Algorithmen an, die mit dem Schlüssel für Signatur- und Überprüfungsvorgänge verwendet werden können. Dieses Tag ist für RSA, ECDSA und HMAC-Schlüssel

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};
Keymaster 2 und älter 
typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

Dieses Tag ist wiederholbar. Geben Sie für Signatur- und Verifizierungsvorgänge Folgendes an: einen Digest im Argument additionalParams von starten. Wenn der angegebene Hashwert nicht zu den mit dem Schlüssel verknüpften Hashwerten gehört, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_DIGEST fehl.

Tag::EC_CURVE

Version: 2, 3, 4

Wiederholbar? Nein

In Keymaster 1 wurde die für EC-Schlüssel verwendete Kurve anhand der angegebenen Schlüsselgröße erraten. Um die Flexibilität in Zukunft zu verbessern, wurde in Keymaster 2 eine explizite Möglichkeit zur Angabe von Kurven eingeführt. Anfragen zur EC-Schlüsselgenerierung können Tag::EC_CURVE, Tag::KEY_SIZE oder beides enthalten.

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 und älter 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

Wenn eine Generierungsanfrage nur Tag::KEY_SIZE enthält, greife auf die Keymaster 1-Logik zurück und wähle die entsprechende NIST-Kurve aus.

Wenn die Anfrage nur Tag::EC_CURVE enthält, verwenden Sie die angegebene Kurve. Ab Keymaster 3 werden Kurven in EcCurve Bei Keymaster 2 und niedriger werden Kurven in keymaster_ec_curve_t definiert.

Wenn die Anfrage beide enthält, verwende die mit Tag::EC_CURVE angegebene Kurve und überprüfe, ob die angegebene Schlüsselgröße für diese Kurve geeignet ist. Andernfalls wird ErrorCode::INVALID_ARGUMENT zurückgegeben.

Tag::INCLUDE_UNIQUE_ID

Version: 2, 3, 4

Wiederholbar? Nein

Dieses Tag wird während der Schlüsselgenerierung angegeben, um anzugeben, dass eine Attestierung muss das Zertifikat für den generierten Schlüssel zeitgebundene eindeutige Geräte-ID, wie durch Tag::UNIQUE_ID

Dieses Tag ist boolescher Natur. Die möglichen Werte sind „true“ (wahr, wenn das Tag vorhanden ist) und „false“ (falsch, wenn das Tag nicht vorhanden ist).

Tag::KEY_SIZE

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die Größe des Schlüssels in Bit an und wird auf normale Weise für den Algorithmus des Schlüssels. Bei RSA-Schlüsseln gibt Tag::KEY_SIZE beispielsweise die Größe des öffentlichen Moduls an. Bei AES-Schlüsseln wird die Länge des geheimen Schlüsselmaterials.

Tag::MAC_LENGTH

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die angeforderte Länge eines MAC- oder GCM-Authentifizierungs-Tags in Bit an.

Der Wert ist die MAC-Länge in Bit. Es ist ein Vielfaches von 8, mindestens so groß wie der Wert von Tag::MIN_MAC_LENGTH die mit dem Schlüssel verknüpft sind.

Tag::MAX_USES_PER_BOOT

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, wie oft ein Schlüssel zwischen Systemneustarts maximal verwendet werden kann. Dies ist ein weiterer Mechanismus zur Begrenzung der Schlüsselnutzung.

Der Wert ist eine 32-Bit-Ganzzahl, die die Nutzungen pro Start angibt.

Wenn ein Schlüssel mit diesem Tag in einem Vorgang verwendet wird, kann ein mit einem Schlüssel verknüpfter Zähler sollte während des begin-Anruf starten. Nach dem Schlüssel Zähler diesen Wert überschritten hat, schlagen alle nachfolgenden Versuche, den Schlüssel zu verwenden, fehl. mit ErrorCode::MAX_OPS_EXCEEDED, bis das Gerät neu gestartet wird. Das bedeutet, dass ein Trustlet eine Tabelle mit Nutzungszählern für Schlüssel mit diesem Tag führt. Da der Arbeitsspeicher von Keymaster oft begrenzt ist, kann diese Tabelle eine feste maximale Größe haben. Keymaster kann dann bei Vorgängen, bei denen versucht wird, Schlüssel mit diesem Tag zu verwenden, fehlschlagen, wenn die Tabelle voll ist. Die Tabelle muss mindestens 16 Schlüssel aufnehmen. Wenn ein Vorgang fehlschlägt, weil die Tabelle voll ist, gibt Keymaster Folgendes zurück: ErrorCode::TOO_MANY_OPERATIONS

Tag::MIN_MAC_LENGTH

Version: 1, 2, 3, 4

Wiederholbar? Nein

Dieses Tag gibt die Mindestlänge der MAC-Adresse an, die angefordert werden kann, oder mit diesem Schlüssel für HMAC-Schlüssel und AES-Schlüssel bestätigt werden, die den GCM-Modus unterstützen.

Dieser Wert ist die Mindestlänge der MAC-Adresse in Bits. Es ist ein Vielfaches von 8. Bei HMAC-Schlüsseln ist der Wert mindestens 64. Bei GCM-Schlüsseln muss der Wert mindestens 96 und darf maximal 128 sein.

Tag::MIN_SECONDS_BETWEEN_OPS

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die Mindestdauer an, die zwischen zulässigen Vorgängen mit einem Schlüssel vergehen muss. Kann verwendet werden, um die Ratenbegrenzung für die Verwendung von Schlüsseln in Kontexten zu begrenzen bei denen unbeschränkte Nutzung Brute-Force-Angriffe ermöglicht.

Der Wert ist eine 32-Bit-Ganzzahl, die die Zeit in Sekunden zwischen zulässigen Vorgängen angibt.

Wenn ein Schlüssel mit diesem Tag in einem Vorgang verwendet wird, starten Sie einen Timer während des Aufrufs von finish oder abort. Beliebig begin-Aufruf, der ein die vor dem Timer empfangen wurden, zeigt an, dass das durch Tag::MIN_SECONDS_BETWEEN_OPS ist verstrichen, scheitert mit ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Das bedeutet, dass ein Trustlet eine Tabelle mit Nutzungszählern für Schlüssel mit diesem Tag führt. Da der Keymaster-Arbeitsspeicher häufig begrenzt ist, kann diese Tabelle ein festes maximales "size" und "Keymaster" können Vorgänge fehlschlagen, bei denen versucht wird, Schlüssel mit diesem Tag zu verwenden. wenn die Tabelle voll ist. Die Tabelle muss mindestens 32 verwendete Schlüssel aufnehmen und Tabellenslots aggressiv wiederverwenden, wenn die Mindestnutzungsintervalle der Schlüssel ablaufen. Wenn ein Vorgang fehlschlägt, weil die Tabelle voll ist, gibt Keymaster Folgendes zurück: ErrorCode::TOO_MANY_OPERATIONS

Tag::NO_AUTH_REQUIRED

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, dass zur Verwendung dieses Schlüssels keine Authentifizierung erforderlich ist. Dieses Tag ist mit Tag::USER_SECURE_ID nicht kompatibel.

Dieses Tag ist ein boolescher Wert, daher sind die möglichen Werte „true“ (falls das Tag vorhanden ist) und false (wenn das Tag nicht vorhanden ist).

Tag::NONCE

Version: 1, 2, 3, 4

Wiederholbar? Nein

Liefert oder gibt eine Nonce oder einen Initialisierungsvektor (IV) für AES GCM, CBC, oder CTR-Verschlüsselung oder -entschlüsselung. Dieses Tag wird bereitgestellt, um Anfang von Verschlüsselungs- und Entschlüsselungsvorgängen zu markieren. Sie wird nur an den Anfang gestellt, wenn der Schlüssel Tag::CALLER_NONCE enthält. Falls nicht angegeben, eine entsprechende Nonce oder IV Keymaster und vom Start zurückgegeben.

Der Wert ist ein Blob, ein Byte-Array mit beliebiger Länge. Die zulässigen Längen hängen vom Modus ab: GCM-Nonces haben eine Länge von 12 Byte, CBC- und CTR-IVs eine Länge von 16 Byte.

Tag::ORIGIN

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, wo der Schlüssel erstellt wurde, falls bekannt. Dieses Tag kann nicht bei der Schlüsselgenerierung oder dem Import angegeben werden, sondern muss den Schlüsselmerkmalen vom Trustlet hinzugefügt werden.

Keymaster 3

Die möglichen Werte sind in android::hardware::keymaster::v3_0::KeyOrigin definiert:

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 und frühere Versionen

Die möglichen Werte sind in keymaster_origin_t definiert:

typedef enum {
    KM_ORIGIN_GENERATED = 0,
    KM_ORIGIN_IMPORTED = 2,
    KM_ORIGIN_UNKNOWN = 3,
} keymaster_key_origin_t

Die volle Bedeutung des Werts hängt nicht nur vom Wert ab, sondern auch davon, sie in der Liste der hardwareerzwungenen oder softwareerzwungenen Eigenschaften aufgeführt sind.

GENERATED gibt an, dass der Schlüssel von Keymaster generiert wurde. Wenn der Schlüssel in der Liste der hardwareerzwungenen Schlüssel aufgeführt ist, wurde er auf sicherer Hardware generiert und ist dauerhaft an die Hardware gebunden. Wenn in der durch Software erzwungenen Liste enthält, wurde der Schlüssel in SoftKeymaster generiert und wird nicht hardwaregebunden.

DERIVED gibt an, dass der Schlüssel innerhalb von Keymaster abgeleitet wurde. Befindet sich wahrscheinlich außerhalb des Geräts.

IMPORTED gibt an, dass der Schlüssel außerhalb von generiert wurde. von Keymaster und importiert Keymaster. Wenn sie in der Liste der hardwareerzwungenen Einstellungen aufgeführt ist, ist sie dauerhaft hardwaregebunden, obwohl Kopien außerhalb der sicheren Hardware vorhanden sein können. Wenn im Feld Software erzwingt, wurde der Schlüssel in SoftKeymaster importiert und ist Hardware gebunden.

UNKNOWN sollte nur in der Liste der hardwareerzwungenen Elemente angezeigt werden. Es gibt an, dass der Schlüssel an die Hardware gebunden ist, aber nicht bekannt ist, ob der Schlüssel ursprünglich in sicherer Hardware generiert oder importiert wurde. Dies tritt nur auf, wenn die Keymaster0-Hardware verwendet wird, um Keymaster1-Dienste zu emulieren.

Tag::ORIGINATION_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt das Datum und die Uhrzeit an, zu der der Schlüssel für Signatur- und Verschlüsselungzwecke abläuft. Danach werden alle Versuche, einen Schlüssel mit Keypurpose::SIGN oder KeyZweck::VERSCHLÜSSELN bereitgestellt Starten fehlgeschlagen mit ErrorCode::KEY_EXPIRED.

Der Wert ist eine 64-Bit-Ganzzahl, die die Millisekunden seit dem 1. Januar 1970 angibt.

Tag::OS_PATCHLEVEL

Version: 2, 3, 4

Wiederholbar? Nein

Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von diesem der hardwaregestützten Autorisierungsliste hinzugefügt.

Der Wert des Tags ist eine Ganzzahl im Format JJJJMM, wobei JJJJ für den Wert das vierstellige Jahr der letzten Aktualisierung und MM der zweistellige Monat der letzten Aktualisierung aktualisieren. Für einen Schlüssel, der auf einem Android-Gerät generiert wurde, das zuletzt aktualisiert wurde, Dezember 2015 würde der Wert 201512 lauten.

Schlüssel, deren Patch-Level von der aktuellen Patch-Ebene abweicht, nutzungsfreundlich sind. Der Versuch, einen solchen Schlüssel zu verwenden, begin, getKeyCharacteristics oder exportKey um ErrorCode::KEY_REQUIRES_UPGRADE zurückzugeben. Weitere Informationen finden Sie unter Versionsbindung für weitere Informationen Details.

Tag::OS_VERSION

Version: 2, 3, 4

Wiederholbar? Nein

Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von diesem zur hardwaregestützten Autorisierungsliste hinzugefügt.

Der Wert des Tags ist eine Ganzzahl im Format MMmmss, wobei MM der wichtigste Wert ist. Versionsnummer, mm die Nebenversionsnummer und ss die Sub-Minor-Version Nummer. Bei einem Schlüssel, der mit Android-Version 4.0.3 generiert wurde, wäre der Wert beispielsweise 040003.

Tag::PADDING

Version: 1, 2, 3, 4

Wiederholbar? Ja

Gibt die Padding-Modi an, die mit dem Schlüssel verwendet werden können. Dieses Tag ist die für RSA- und AES-Schlüssel relevant sind.

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};
Keymaster 2 und frühere Versionen 
typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP und PaddingMode::RSA_PKCS1_1_5_ENCRYPT werden nur für RSA-Verschlüsselungs-/Entschlüsselungsschlüssel verwendet und geben jeweils RSA PKCS#1v2 OAEP-Padding und RSA PKCS#1 v1.5-Zufalls-Padding an. PaddingMode::RSA_PSS und PaddingMode::RSA_PKCS1_1_5_SIGN werden nur für RSA-Signatur-/Bestätigungsschlüssel verwendet und geben jeweils RSA PKCS#1v2 PSS-Padding und RSA PKCS#1 v1.5 deterministisches Padding an.

PaddingMode::NONE kann mit RSA oder AES-Schlüssel. Wenn für AES-Schlüssel PaddingMode::NONE mit dem Blockmodus ECB oder CBC verwendet wird und die zu verschlüsselnden oder zu entschlüsselnden Daten nicht ein Vielfaches der AES-Blockgröße sind, schlägt der Aufruf von „finish“ mit ErrorCode::INVALID_INPUT_LENGTH fehl.

PaddingMode::PKCS7 kann nur mit AES-Schlüsseln verwendet werden. nur im ECB- und CBC-Modus.

Dieses Tag kann wiederholt werden. Im Aufruf von muss ein Padding-Modus angegeben werden. begin zurück. Wenn der angegebene Modus für den Schlüssel nicht autorisiert ist, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_BLOCK_MODE fehl.

Tag::ZWECK

Version: 1, 2, 3, 4

Wiederholbar? Ja

Gibt die Zwecke an, für die der Schlüssel verwendet werden kann.

Die möglichen Werte sind in der folgenden Aufzählung definiert:

Keymaster 3 
enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};
Keymaster 2 und frühere Versionen 
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Dieses Tag kann wiederholt werden. Schlüssel können mit mehreren Werten generiert werden, auch wenn ein Vorgang nur einen Zweck hat. Wenn die Funktion begin zum Starten eines Vorgangs aufgerufen wird, wird der Zweck des Vorgangs angegeben. Wenn der für den Vorgang angegebene Zweck nicht vom Schlüssel autorisiert ist, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_PURPOSE fehl.

Tag::RESET_SINCE_ID_ROTATION

Version: 3, 4

Wiederholbar? Nein

Gibt an, ob das Gerät auf die Werkseinstellungen zurückgesetzt wurde seit der letzten Rotation der eindeutigen ID. Wird für die Schlüsselattestierung verwendet.

Dieses Tag ist boolescher Natur. Die möglichen Werte sind „true“ (wahr, wenn das Tag vorhanden ist) und „false“ (falsch, wenn das Tag nicht vorhanden ist).

Tag::ROLLBACK_RESISTANT

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, dass der Schlüssel Rollback-resistent ist, was bedeutet, dass, wenn er gelöscht wird, durch deleteKey oder deleteAllKeys ist der Schlüssel garantiert dauerhaft gelöscht und unbrauchbar. Schlüssel ohne dieses Tag können gelöscht und dann aus der Sicherung wiederhergestellt werden.

Dieses Tag ist boolescher Natur. Die möglichen Werte sind „true“ (wahr, wenn das Tag vorhanden ist) und „false“ (falsch, wenn das Tag nicht vorhanden ist).

Tag::ROOT_OF_TRUST

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt den Root of Trust an, den Schlüssel, der vom verifizierten Boot verwendet wird, um das gestartete Betriebssystem (falls vorhanden) zu validieren. Dieses Tag wird in den Hauptmerkmalen niemals an Keymaster gesendet oder von Keymaster zurückgegeben.

Tag::RSA_PUBLIC_EXPONENT

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt den Wert des öffentlichen Exponenten für ein RSA-Schlüsselpaar an. Dieses Tag ist nur für RSA-Schlüssel relevant und für alle RSA-Schlüssel erforderlich.

Der Wert ist eine vorzeichenlose 64-Bit-Ganzzahl, die die Anforderungen eines Öffentlicher RSA-Exponent. Dieser Wert muss eine Primzahl sein. Trustlets unterstützen die Wert 2^16+1 und können andere sinnvolle Werte unterstützen, insbesondere den Wert 3. Wenn kein Exponent angegeben ist oder der angegebene Exponent nicht unterstützt wird, Schlüsselgenerierung schlägt mit ErrorCode::INVALID_ARGUMENT fehl.

Tag::UNIQUE_ID

Version: 3, 4

Wiederholbar? Nein

Wird verwendet, um eine eindeutige ID in der Attestierung bereitzustellen.

Der Wert ist ein Blob, ein Byte-Array beliebiger Länge.

Tag::USAGE_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt Datum und Uhrzeit an, zu der der Schlüssel zur Überprüfung abläuft der Datenentschlüsselung. Danach werden alle Versuche, einen Schlüssel mit Keypurpose::VERIFY oder KeyZweck::DECRYPT bereitgestellt an Start schlägt fehl mit ErrorCode::KEY_EXPIRED.

Der Wert ist eine 64-Bit-Ganzzahl, die die Millisekunden seit 1. Januar 1970.

Tag::USER_AUTH_TYPE

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die Typen von Nutzerauthentifizierungsgeräten an, mit denen dies autorisiert werden kann . Wenn Keymaster aufgefordert wird, einen Vorgang mit einem Schlüssel mit diesem Tag auszuführen, erhält er ein Authentifizierungstoken. Das Feld authenticator_type des Tokens muss mit dem Wert im Tag übereinstimmen. Beispiel: (ntoh(token.authenticator_type) & auth_type_tag_value) != 0, wobei ntoh eine Funktion ist, die wandelt netzwerkgeordnete Ganzzahlen in vom Host geordnete Ganzzahlen um auth_type_tag_value ist der Wert dieses Tags.

Der Wert ist eine 32-Bit-Ganzzahl-Bitmaske von Werten aus der Aufzählung:

Keymaster 3 
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 und frühere Versionen 
typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

Tag: USER_SECURE_ID

Version: 1, 2, 3, 4

Wiederholbar? Ja

Gibt an, dass ein Schlüssel nur unter einem bestimmten sicheren Nutzer verwendet werden kann Authentifizierungsstatus. Dieses Tag ist mit Tag::NO_AUTH_REQUIRED nicht kompatibel.

Der Wert ist eine 64-Bit-Ganzzahl, die den Status der Authentifizierungsrichtlinie angibt Wert, der in einem Authentifizierungstoken vorhanden sein muss (wird für beginnen mit Tag::AUTH_TOKEN), um die Verwendung des Schlüssels zu autorisieren. Beliebig begin anrufen mit einem Schlüssel mit diesem Tag, der keinen Authentifizierungstoken oder stellt ein Authentifizierungstoken ohne übereinstimmenden Richtlinienstatuswert schlägt fehl.

Dieses Tag ist wiederholbar. Wenn einer der angegebenen Werte mit einem Richtlinienstatuswert im Authentifizierungstoken übereinstimmt, ist der Schlüssel für die Verwendung autorisiert. Andernfalls schlägt der Vorgang mit folgender Fehlermeldung fehl: ErrorCode::KEY_USER_NOT_AUTHENTICATED

Tag::VENDOR_PATCHLEVEL

Version: 4

Dieses Tag gibt das Sicherheitspatch-Level des Anbieter-Images an, verwendet werden kann. Dieses Tag wird nie an den Keymaster TA gesendet, sondern zum Liste der hardwareerzwungenen Autorisierungen vom TA. Jeder Versuch, einen Schlüssel mit einer Der Tag::VENDOR_PATCHLEVEL-Wert unterscheidet sich vom aktuell ausgeführten Wert. System-Patchlevel muss begin(), getKeyCharacteristics() oder exportKey() für die Rückgabe ErrorCode::KEY_REQUIRES_UPGRADE Weitere Informationen: upgradeKey() .

Der Wert des Tags ist eine Ganzzahl im Format JJJJMMTT, wobei JJJJ das vierstellige Jahr der letzten Aktualisierung, MM der zweistellige Monat und TT der zweistellige Tag der letzten Aktualisierung ist. Für einen Schlüssel, der für eine Android-Gerät zuletzt am 5. Juni 2018 aktualisiert, lautet der Wert „20180605“.

Die IKeymasterDevice HAL muss die aktuelle Patchebene des Anbieters aus der Systemeigenschaft ro.vendor.build.security_patch lesen und an die sichere Umgebung weitergeben, wenn die HAL zum ersten Mal geladen wird (der Mechanismus ist implementierungsspezifisch). Die sichere Umgebung darf erst nach dem nächsten Start ein anderes Patchlevel akzeptieren.

Muss hardwareerzwungen werden.