Keymaster-Autorisierungs-Tags

Diese Seite enthält Details zur Unterstützung der Implementierer von Keymaster HALs. Es behandelt jedes Tag in der HAL, in welcher Keymaster-Version dieses Tag verfügbar ist und ob das Tag wiederholbar ist. Sofern in den Tag-Beschreibungen nicht anders angegeben, werden alle nachstehenden Tags während der Schlüsselgenerierung verwendet, um Schlüsselmerkmale anzugeben.

Für Keymaster 4 werden Tags in platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , z. B. 3.0/types.hal für Keymaster 3 und 4.0/types.hal für Keymaster 4. Für Keymaster 2 und darunter gilt: Tags sind in platform/hardware/libhardware/include/hardware/keymaster_defs.h .

Informationen zu den Funktionen finden Sie auf der Seite Keymaster-Funktionen .

Schlagwort::ACTIVE_DATETIME

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

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

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

Schlagwort::ALGORITHMUS

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

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

Mögliche Werte werden durch die folgende Aufzählung definiert:

enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};

typedef enum {
    KM_ALGORITHM_RSA = 1,
    KM_ALGORITHM_EC = 3,
    KM_ALGORITHM_AES = 32,
    KM_ALGORITHM_HMAC = 128,
} keymaster_algorithm_t;

Schlagwort::ALLE_ANWENDUNGEN

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Reserviert für zukünftige Verwendung.

Tag::ALLOW_WHILE_ON_BODY

Version : 2, 3, 4

Wiederholbar ? Nein

Dieses Tag gilt nur für Android Wear-Geräte mit On-Body-Sensoren. Zum jetzigen Zeitpunkt wird nicht erwartet, dass ein TEE einen sicheren Zugriff auf einen am Körper angebrachten Sensor bieten kann oder dass am Körper angebrachte Sensoren sehr sicher sind, daher wird erwartet, dass dies eine rein durch Software erzwungene Funktion ist.

Stichwort::ALL_USERS

Version : 3, 4

Wiederholbar ? Nein

Reserviert für zukünftige Verwendung.

Tag::ANWENDUNGSDATEN

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Wenn dieses Tag für generateKey oder importKey bereitgestellt wird, gibt es Daten an, die während aller Verwendungen des Schlüssels erforderlich sind. Insbesondere Aufrufe von exportKey und getKeyCharacteristics müssen denselben Wert für den clientId Parameter bereitstellen, und Aufrufe von begin müssen dieses Tag und dieselben zugehörigen Daten als Teil des inParams Satzes bereitstellen. Wenn die korrekten Daten nicht bereitgestellt werden, gibt die Funktion ErrorCode::INVALID_KEY_BLOB zurück.

Der Inhalt dieses Tags ist kryptografisch an den Schlüssel gebunden, was bedeutet, dass es einem 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 brutal zu erzwingen Inhalte, die Anwendungen durch die Angabe von Inhalten mit ausreichend hoher Entropie verhindern können.

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::APPLICATION_ID

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Wenn dieses Tag für generateKey oder importKey bereitgestellt wird, gibt es Daten an, die während aller Verwendungen des Schlüssels erforderlich sind. Insbesondere Aufrufe von exportKey und getKeyCharacteristics müssen denselben Wert im clientId Parameter bereitstellen, und Aufrufe von begin müssen dieses Tag und dieselben zugehörigen Daten als Teil des inParams Satzes bereitstellen. Wenn die korrekten Daten nicht bereitgestellt werden, gibt die Funktion ErrorCode::INVALID_KEY_BLOB zurück.

Der Inhalt dieses Tags ist kryptografisch an den Schlüssel gebunden, was bedeutet, dass ein Angreifer, der auf alle Geheimnisse der sicheren Welt zugreifen kann – aber keinen Zugriff auf den Tag-Inhalt hat – den Schlüssel nicht entschlüsseln kann (ohne Brute-Force-Erzwingen des Tag-Inhalts). ).

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ASSOCIATED_DATA

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Stellt "assoziierte Daten" für die AES-GCM-Verschlüsselung oder -Entschlüsselung bereit. Dieses Tag wird bereitgestellt, um Daten zu aktualisieren und anzugeben, die nicht verschlüsselt/entschlüsselt sind, aber zur Berechnung des GCM-Tags verwendet werden.

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_APPLICATION_ID

Version : 3, 4

Wiederholbar ? Nein

Wird verwendet, um den Satz möglicher Anwendungen zu identifizieren, von denen man eine Schlüsselbescheinigung initiiert hat.

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Stichwort::ATTESTATION_CHALLENGE

Version : 3, 4

Wiederholbar ? Nein

Wird verwendet, um die Beglaubigung herauszufordern.

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_BRAND

Version : 3, 4

Wiederholbar ? Nein

Stellt den Markennamen des Geräts bereit, wie er von Build.BRAND in Android zurückgegeben wird. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_DEVICE

Version : 3, 4

Wiederholbar ? Nein

Stellt den Gerätenamen des Geräts bereit, wie von Build.DEVICE in Android zurückgegeben. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_IMEI

Version : 3, 4

Wiederholbar ? Ja

Stellt die IMEIs für alle Funkgeräte auf dem Gerät bereit. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_MANUFACTURER

Version : 3, 4

Wiederholbar ? Nein

Stellt den Herstellernamen des Geräts bereit, wie von Build.MANUFACTURER in Android zurückgegeben. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_MEID

Version : 3, 4

Wiederholbar ? Ja

Stellt die MEIDs für alle Funkgeräte auf dem Gerät bereit. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_MODEL

Version : 3, 4

Wiederholbar ? Nein

Stellt den Modellnamen des Geräts bereit, wie von Build.MODEL in Android zurückgegeben. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_PRODUCT

Version : 3, 4

Wiederholbar ? Nein

Stellt den Produktnamen des Geräts bereit, wie er von Build.PRODUCT in Android zurückgegeben wird. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::ATTESTATION_ID_SERIAL

Version : 3, 4

Wiederholbar ? Nein

Liefert die Seriennummer des Geräts. Dieses Feld wird nur gesetzt, wenn eine Beglaubigung der Gerätekennungen angefordert wird.

Wenn das Gerät keine ID-Bestätigung unterstützt (oder destroyAttestationIds() zuvor aufgerufen wurde und das Gerät seine IDs nicht mehr bestätigen kann), schlägt jede Schlüsselbestätigungsanforderung, die dieses Tag enthält, mit ErrorCode::CANNOT_ATTEST_IDS .

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Tag::AUTH_TIMEOUT

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt die Zeit in Sekunden an, für die der Schlüssel nach der Authentifizierung zur Verwendung berechtigt ist. Wenn Tag::USER_SECURE_ID vorhanden ist und dieses Tag nicht, dann muss der Schlüssel für jede Verwendung authentifiziert werden (siehe Beginn für die Details des Ablaufs der Authentifizierung pro Vorgang).

Der Wert ist eine 32-Bit-Ganzzahl, die die Zeit in Sekunden angibt, nach einer erfolgreichen Authentifizierung des durch Tag::USER_SECURE_ID angegebenen Benutzers mit der durch Tag::USER_AUTH_TYPE angegebenen Authentifizierungsmethode, dass der Schlüssel verwendet werden kann.

Tag::AUTH_TOKEN

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Stellt ein Authentifizierungstoken zum Beginnen , Aktualisieren oder Beenden von bereit, um die Benutzerauthentifizierung für eine Schlüsseloperation nachzuweisen, die dies erfordert (Schlüssel hat Tag::USER_SECURE_ID ).

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

Stichwort::BLOB_USAGE_REQUIREMENTS

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt die erforderlichen Systemumgebungsbedingungen für die Verwendung des generierten Schlüssels an.

Mögliche Werte werden durch die folgende Aufzählung definiert:

enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};

typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

Dieses Tag kann während der Schlüsselgenerierung angegeben werden, um zu verlangen, dass der Schlüssel in der angegebenen Bedingung verwendbar ist. Es muss mit den Schlüsselmerkmalen von generateKey und getKeyCharacteristics zurückgegeben werden . Wenn der Aufrufer Tag::BLOB_USAGE_REQUIREMENTS mit dem Wert KeyBlobUsageRequirements::STANDALONE angibt, gibt das Trustlet ein Schlüsselblob zurück, das ohne Dateisystemunterstützung verwendet werden kann. Dies ist entscheidend für Geräte mit verschlüsselten Festplatten, bei denen das Dateisystem möglicherweise erst verfügbar ist, nachdem ein Keymaster-Schlüssel zum Entschlüsseln der Festplatte verwendet wurde.

Tag::BLOCK_MODE

Fassung : 1, 2, 3, 4

Wiederholbar ? Ja

Gibt den/die Blockverschlüsselungsmodus(s) an, mit denen der Schlüssel verwendet werden kann. Dieses Tag ist nur für AES-Schlüssel relevant.

Mögliche Werte werden durch die folgende Aufzählung definiert:

enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};

typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Dieses Tag ist wiederholbar, und für AES-Tastenoperationen geben Sie einen Modus im additionalParams -Argument von begin an . Wenn sich der angegebene Modus nicht in den Modi befindet, die dem Schlüssel zugeordnet sind, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Tag::BOOT_PATCHLEVEL

Fassung : 4

Tag::BOOT_PATCHLEVEL gibt das Boot-Image (Kernel)-Sicherheits-Patch-Level an, mit dem der Schlüssel verwendet werden kann. Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von dem TA zu der hardwareerzwungenen Autorisierungsliste hinzugefügt. Jeder Versuch, einen Schlüssel mit einem Tag::BOOT_PATCHLEVEL Wert zu verwenden, der sich vom derzeit laufenden System-Patchlevel unterscheidet, führt dazu, dass begin() , getKeyCharacteristics() oder exportKey() ErrorCode::KEY_REQUIRES_UPGRADE . Siehe upgradeKey() für Details.

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. Beispielsweise wäre der Wert für einen Schlüssel, der auf einem Android-Gerät generiert wurde und zuletzt am 5. Juni 2018 aktualisiert wurde, 20180605. Wenn der Tag nicht bekannt ist, kann 00 ersetzt werden.

Bei jedem Start muss der Bootloader die Patch-Ebene des Boot-Images für die sichere Umgebung bereitstellen (Mechanismus ist implementierungsdefiniert).

Muss durch Hardware erzwungen werden.

Tag::BOOTLOADER_ONLY

Fassung : 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 wahr (wenn das Tag vorhanden ist) und falsch (wenn das Tag nicht vorhanden ist).

Jeder Versuch, einen Schlüssel mit Tag::BOOTLOADER_ONLY vom Android-System zu verwenden, schlägt mit ErrorCode::INVALID_KEY_BLOB .

Stichwort::CALLER_NONCE

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

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

Dieses Tag ist boolesch, daher sind die möglichen Werte wahr (wenn das Tag vorhanden ist) und falsch (wenn das Tag nicht vorhanden ist).

Dieses Tag wird nur für AES-Schlüssel verwendet und ist nur für die CBC-, CTR- und GCM-Blockmodi relevant. Wenn das Tag nicht vorhanden ist, sollten Implementierungen jeden Vorgang ablehnen, der Tag::NONCE bereitstellt , um mit ErrorCode::CALLER_NONCE_PROHIBITED CALLER_NONCE_PROHIBITED zu beginnen .

Stichwort::CREATION_DATETIME

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt Datum und Uhrzeit der Schlüsselerstellung in Millisekunden seit dem 1. Januar 1970 an. Dieses Tag ist optional und dient nur zu Informationszwecken.

Schlagwort::DIGEST

Fassung : 1, 2, 3, 4

Wiederholbar ? Ja

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

Mögliche Werte werden durch die folgende Aufzählung definiert:

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,
};

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 Signier- und Verifizierungsvorgänge einen Digest im additionalParams -Argument von begin an . Wenn der angegebene Digest nicht in den mit dem Schlüssel verknüpften Digests enthalten ist, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_DIGEST .

Tag::EC_CURVE

Version : 2, 3, 4

Wiederholbar ? Nein

In Keymaster 1 wurde die für EC-Schlüssel verwendete Kurve aus der angegebenen Schlüsselgröße erraten. Um die Flexibilität in der Zukunft zu verbessern, hat Keymaster 2 eine explizite Methode zum Spezifizieren von Kurven eingeführt. Anfragen zur Generierung von EC-Schlüsseln können Tag::EC_CURVE , Tag::KEY_SIZE oder beides haben.

Mögliche Werte werden durch die folgende Aufzählung definiert:

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

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

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

Wenn die Anforderung nur Tag::EC_CURVE enthält, verwenden Sie die angegebene Kurve. Für Keymaster 3 und höher werden Kurven in EcCurve definiert. Für Keymaster 2 und früher werden Kurven in keymaster_ec_curve_t definiert.

Wenn die Anforderung beides enthält, verwenden Sie die durch Tag::EC_CURVE angegebene Kurve und überprüfen Sie, ob die angegebene Schlüsselgröße für diese Kurve geeignet ist. Wenn nicht, geben ErrorCode::INVALID_ARGUMENT .

Tag::INCLUDE_UNIQUE_ID

Version : 2, 3, 4

Wiederholbar ? Nein

Dieses Tag wird während der Schlüsselgenerierung angegeben, um anzugeben, dass ein Beglaubigungszertifikat für den generierten Schlüssel eine anwendungsbezogene und zeitgebundene gerätespezifische ID enthalten sollte, wie durch Tag::UNIQUE_ID angegeben.

Dieses Tag ist boolesch, daher sind die möglichen Werte wahr (wenn das Tag vorhanden ist) und falsch (wenn das Tag nicht vorhanden ist).

Stichwort::KEY_SIZE

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

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

Tag::MAC_LENGTH

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Stellt die angeforderte Länge eines MAC- oder GCM-Authentifizierungs-Tags in Bits bereit.

Der Wert ist die MAC-Länge in Bits. Er ist ein Vielfaches von 8 und mindestens so groß wie der dem Schlüssel zugeordnete Wert von Tag::MIN_MAC_LENGTH .

Stichwort::MAX_USES_PER_BOOT

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt an, wie oft ein Schlüssel zwischen Systemneustarts maximal verwendet werden darf. Dies ist ein weiterer Mechanismus, um die Verwendung von Schlüsseln zu begrenzen.

Der Wert ist eine 32-Bit-Ganzzahl, die die Verwendung pro Boot darstellt.

Wenn eine Taste mit diesem Tag in einer Operation verwendet wird, sollte ein der Taste zugeordneter Zähler während des Begin -Aufrufs inkrementiert werden. Nachdem der Schlüsselzähler diesen Wert überschritten hat, schlagen alle nachfolgenden Versuche, den Schlüssel zu verwenden, mit ErrorCode::MAX_OPS_EXCEEDED , bis das Gerät neu gestartet wird. Dies impliziert, dass ein Trustlet eine Tabelle von Verwendungszählern für Schlüssel mit diesem Tag führt. Da der Keymaster-Speicher oft begrenzt ist, kann diese Tabelle eine feste maximale Größe haben und Keymaster kann Operationen fehlschlagen, die versuchen, Schlüssel mit diesem Tag zu verwenden, wenn die Tabelle voll ist. Der Tisch muss mindestens 16 Tasten Platz bieten. Wenn eine Operation fehlschlägt, weil die Tabelle voll ist, gibt Keymaster ErrorCode::TOO_MANY_OPERATIONS zurück.

Stichwort::MIN_MAC_LENGTH

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

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

Dieser Wert ist die minimale MAC-Länge in Bits. Er ist ein Vielfaches von 8. Für HMAC-Schlüssel beträgt der Wert mindestens 64. Für GCM-Schlüssel beträgt der Wert mindestens 96 und höchstens 128.

Stichwort::MIN_SECONDS_BETWEEN_OPS

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt die Mindestzeit an, die zwischen zulässigen Operationen mit einem Schlüssel vergeht. Dies kann verwendet werden, um die Verwendung von Schlüsseln in Kontexten zu begrenzen, in denen eine unbegrenzte Verwendung Brute-Force-Angriffe ermöglichen kann.

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

Wenn eine Taste mit diesem Tag in einer Operation verwendet wird, starten Sie einen Timer während des Anrufs beenden oder abbrechen . Jeder Startaufruf, der empfangen wird, bevor der Timer anzeigt, dass das durch Tag::MIN_SECONDS_BETWEEN_OPS angegebene Intervall abgelaufen ist, schlägt mit ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Dies impliziert, dass ein Trustlet eine Tabelle von Verwendungszählern für Schlüssel mit diesem Tag führt. Da der Keymaster-Speicher oft begrenzt ist, kann diese Tabelle eine feste maximale Größe haben und Keymaster kann Operationen fehlschlagen, die versuchen, Schlüssel mit diesem Tag zu verwenden, wenn die Tabelle voll ist. Die Tabelle muss mindestens 32 in Gebrauch befindliche Schlüssel aufnehmen und Tabellenplätze aggressiv wiederverwenden, wenn die Mindestnutzungsintervalle für Schlüssel ablaufen. Wenn eine Operation fehlschlägt, weil die Tabelle voll ist, gibt Keymaster ErrorCode::TOO_MANY_OPERATIONS zurück.

Tag::NO_AUTH_REQUIRED

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt an, dass zur Verwendung dieses Schlüssels keine Authentifizierung erforderlich ist. Dieses Tag schließt sich gegenseitig mit Tag::USER_SECURE_ID aus .

Dieses Tag ist boolesch, daher sind die möglichen Werte wahr (wenn das Tag vorhanden ist) und falsch (wenn das Tag nicht vorhanden ist).

Schlagwort::NONCE

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Stellt eine Nonce oder einen Initialisierungsvektor (IV) für AES GCM-, CBC- oder CTR-Verschlüsselung oder -Entschlüsselung bereit oder gibt sie zurück. Dieses Tag wird bereitgestellt, um während Verschlüsselungs- und Entschlüsselungsvorgängen zu beginnen . Es ist nur vorgesehen, zu beginnen, wenn der Schlüssel Tag::CALLER_NONCE hat. Wenn nicht angegeben, wird eine entsprechende Nonce oder IV zufällig von Keymaster generiert und von Anfang an zurückgegeben.

Der Wert ist ein Blob, ein Bytearray beliebiger Länge. Zulässige Längen hängen vom Modus ab: GCM-Nonces sind 12 Bytes lang; CBC- und CTR-IVs sind 16 Bytes lang.

Schlagwort::HERKUNFT

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt an, wo der Schlüssel erstellt wurde, falls bekannt. Dieses Tag darf nicht während der Schlüsselgenerierung oder des Imports angegeben werden und muss durch das Trustlet zu den Schlüsselmerkmalen hinzugefügt werden.

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

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};

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, ob er in der hardwareerzwungenen oder softwareerzwungenen Merkmalsliste zu finden ist.

GENERATED gibt an, dass Keymaster den Schlüssel generiert hat. Wenn der Schlüssel in der hardwareerzwungenen Liste in sicherer Hardware generiert wurde und dauerhaft an die Hardware gebunden ist. Wenn der Schlüssel in der softwareerzwungenen Liste in SoftKeymaster generiert wurde und nicht an die Hardware gebunden ist.

DERIVED gibt an, dass der Schlüssel in Keymaster abgeleitet wurde. Existiert wahrscheinlich außerhalb des Geräts.

IMPORTED gibt an, dass der Schlüssel außerhalb von Keymaster generiert und in Keymaster importiert wurde. Wenn es in der hardwareerzwungenen Liste aufgeführt ist, ist es dauerhaft hardwaregebunden, obwohl Kopien außerhalb sicherer Hardware existieren können. Wenn der Schlüssel in der Software-Erzwingungsliste in SoftKeymaster importiert wurde und nicht an die Hardware gebunden ist.

UNKNOWN sollte nur in der Hardware-erzwungenen Liste erscheinen. Es zeigt an, dass der Schlüssel hardwaregebunden ist, aber es ist nicht bekannt, ob der Schlüssel ursprünglich in sicherer Hardware generiert oder importiert wurde. Dies tritt nur auf, wenn keymaster0-Hardware verwendet wird, um keymaster1-Dienste zu emulieren.

Stichwort::ORIGINATION_EXPIRE_DATETIME

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt Datum und Uhrzeit an, zu denen der Schlüssel zum Signieren und Verschlüsseln abläuft. Nach dieser Zeit schlägt jeder Versuch, einen Schlüssel mit KeyPurpose::SIGN oder KeyPurpose::ENCRYPT zu verwenden, der zu Beginn bereitgestellt wird, mit ErrorCode::KEY_EXPIRED .

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

Stichwort::OS_PATCHLEVEL

Version : 2, 3, 4

Wiederholbar ? Nein

Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von dem TA zu der hardwareerzwungenen Autorisierungsliste hinzugefügt.

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

Tasten mit einem anderen Patch-Level als dem aktuellen Patch-Level können nicht verwendet werden. Ein Versuch, einen solchen Schlüssel zu verwenden, führt dazu, dass begin , getKeyCharacteristics oder exportKey ErrorCode::KEY_REQUIRES_UPGRADE . Weitere Einzelheiten finden Sie unter Versionsbindung .

Stichwort::OS_VERSION

Version : 2, 3, 4

Wiederholbar ? Nein

Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von dem TA zu der hardwareerzwungenen Autorisierungsliste hinzugefügt.

Der Wert des Tags ist eine Ganzzahl im Format MMmmss, wobei MM die Hauptversionsnummer, mm die Nebenversionsnummer und ss die Nebenversionsnummer ist. Für einen auf Android Version 4.0.3 generierten Schlüssel wäre der Wert beispielsweise 040003.

Schlagwort::POLSTERUNG

Fassung : 1, 2, 3, 4

Wiederholbar ? Ja

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

Mögliche Werte werden durch die folgende Aufzählung definiert:

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,
};

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 RSA PKCS#1v2 OAEP-Padding bzw. RSA PKCS#1 v1.5 Randomized Padding an. PaddingMode::RSA_PSS und PaddingMode::RSA_PKCS1_1_5_SIGN werden nur für RSA-Signatur-/Verifizierungsschlüssel verwendet und geben RSA PKCS#1v2 PSS-Padding bzw. RSA PKCS#1 v1.5 deterministisches Padding an.

PaddingMode::NONE kann entweder mit RSA- oder AES-Schlüsseln verwendet werden. 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 kein Vielfaches der AES-Blockgröße in der Länge haben, schlägt der Aufruf zum Beenden mit ErrorCode::INVALID_INPUT_LENGTH .

PaddingMode::PKCS7 darf nur mit AES-Schlüsseln und nur mit ECB- und CBC-Modi verwendet werden.

Dieses Tag ist wiederholbar. Im Aufruf von begin muss ein Padding-Modus angegeben werden. Wenn der angegebene Modus für den Schlüssel nicht autorisiert ist, schlägt die Operation mit ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Schlagwort::ZWECK

Fassung : 1, 2, 3, 4

Wiederholbar ? Ja

Gibt den Satz von Zwecken an, für die der Schlüssel verwendet werden kann.

Mögliche Werte werden durch die folgende Aufzählung definiert:

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
};

typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Dieses Tag ist wiederholbar; Schlüssel können mit mehreren Werten generiert werden, obwohl eine Operation nur einen einzigen Zweck hat. Wenn die begin -Funktion aufgerufen wird, um eine Operation zu starten, wird der Zweck der Operation angegeben. Wenn der für den Vorgang angegebene Zweck nicht durch den Schlüssel autorisiert ist, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_PURPOSE .

Tag::RESET_SINCE_ID_ROTATION

Version : 3, 4

Wiederholbar ? Nein

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

Dieses Tag ist boolesch, daher sind die möglichen Werte wahr (wenn das Tag vorhanden ist) und falsch (wenn das Tag nicht vorhanden ist).

Tag::ROLLBACK_RESISTANT

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt an, dass der Schlüssel Rollback-resistent ist, was bedeutet, dass der Schlüssel beim Löschen durch deleteKey oder deleteAllKeys garantiert dauerhaft gelöscht und unbrauchbar ist. Es ist möglich, dass Schlüssel ohne dieses Tag gelöscht und dann aus der Sicherung wiederhergestellt werden.

Dieses Tag ist boolesch, daher sind die möglichen Werte wahr (wenn das Tag vorhanden ist) und falsch (wenn das Tag nicht vorhanden ist).

Stichwort::ROOT_OF_TRUST

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

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

Tag::RSA_PUBLIC_EXPONENT

Fassung : 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 64-Bit-Ganzzahl ohne Vorzeichen, die die Anforderungen eines öffentlichen RSA-Exponenten erfüllt. Dieser Wert muss eine Primzahl sein. Trustlets unterstützen den Wert 2^16+1 und möglicherweise andere sinnvolle Werte, insbesondere den Wert 3. Wenn kein Exponent angegeben ist oder der angegebene Exponent nicht unterstützt wird, schlägt die Schlüsselgenerierung mit ErrorCode::INVALID_ARGUMENT .

Tag::UNIQUE_ID

Version : 3, 4

Wiederholbar ? Nein

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

Der Wert ist ein Blob, ein Bytearray beliebiger Länge.

Stichwort::USAGE_EXPIRE_DATETIME

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt das Datum und die Uhrzeit an, zu denen der Schlüssel zu Überprüfungs- und Entschlüsselungszwecken abläuft. Nach dieser Zeit schlägt jeder Versuch, einen Schlüssel mit KeyPurpose::VERIFY oder KeyPurpose::DECRYPT zu verwenden, der zu Beginn bereitgestellt wird, mit ErrorCode::KEY_EXPIRED .

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

Tag::USER_AUTH_TYPE

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt die Arten von Benutzerauthentifikatoren an, die zum Autorisieren dieses Schlüssels verwendet werden können. Wenn Keymaster aufgefordert wird, eine Operation mit einem Schlüssel mit diesem Tag durchzuführen, erhält es ein Authentifizierungstoken, und 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 vom Netzwerk geordnete Ganzzahlen in vom Host geordnete Ganzzahlen konvertiert, und auth_type_tag_value der Wert dieses Tags ist.

Der Wert ist eine 32-Bit-Integer-Bitmaske von Werten aus der Enumeration:

enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};

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

Fassung : 1, 2, 3, 4

Wiederholbar ? Nein

Gibt an, dass ein Schlüssel nur unter einem bestimmten sicheren Benutzerauthentifizierungsstatus verwendet werden darf. Dieses Tag schließt sich gegenseitig mit Tag::NO_AUTH_REQUIRED aus .

Der Wert ist eine 64-Bit-Ganzzahl, die den Statuswert der Authentifizierungsrichtlinie angibt, der in einem Authentifizierungstoken vorhanden sein muss (bereitgestellt, um mit dem Tag::AUTH_TOKEN zu beginnen ), um die Verwendung des Schlüssels zu autorisieren. Jeder Aufruf, mit einem Schlüssel mit diesem Tag zu beginnen , der kein Authentifizierungstoken oder ein Authentifizierungstoken ohne übereinstimmenden Richtlinienstatuswert bereitstellt, schlägt fehl.

Dieses Tag ist wiederholbar. Wenn einer der bereitgestellten Werte mit einem Richtlinienstatuswert im Authentifizierungstoken übereinstimmt, wird der Schlüssel zur Verwendung autorisiert. Andernfalls schlägt die Operation mit ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Stichwort::VENDOR_PATCHLEVEL

Fassung : 4

Dieses Tag gibt die Sicherheits-Patch-Ebene des Anbieter-Images an, mit der der Schlüssel verwendet werden kann. Dieses Tag wird nie an den Keymaster-TA gesendet, sondern wird von dem TA zu der hardwareerzwungenen Autorisierungsliste hinzugefügt. Jeder Versuch, einen Schlüssel mit einem Tag::VENDOR_PATCHLEVEL Wert zu verwenden, der sich von dem derzeit laufenden System-Patchlevel unterscheidet, muss begin() , getKeyCharacteristics() oder exportKey() veranlassen, ErrorCode::KEY_REQUIRES_UPGRADE . Siehe upgradeKey() für Details.

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. Beispielsweise wäre der Wert für einen Schlüssel, der auf einem Android-Gerät generiert wurde, das zuletzt am 5. Juni 2018 aktualisiert wurde, 20180605.

Die IKeymasterDevice-HAL muss den aktuellen Anbieter-Patchlevel aus der Systemeigenschaft ro.vendor.build.security_patch und an die sichere Umgebung liefern, wenn die HAL zum ersten Mal geladen wird (der Mechanismus ist implementierungsdefiniert). Die sichere Umgebung darf erst nach dem nächsten Booten einen weiteren Patchlevel akzeptieren.

Muss durch Hardware erzwungen werden.