Keymaster-Autorisierungs-Tags

Diese Seite enthält Details zur Implementierung von Keymaster HALs. Es behandelt jedes Tag im HAL, in welcher Keymaster-Version dieses Tag verfügbar ist. und ob das Tag wiederholbar ist. Sofern in den Tag-Beschreibungen nicht anders angegeben, Alle folgenden Tags werden bei der Schlüsselgenerierung verwendet, um den Schlüssel anzugeben Eigenschaften.

Für Keymaster 4 werden Tags in platform/hardware/interfaces/keymaster/keymaster-version/types.hal, zum Beispiel <ph type="x-smartling-placeholder"></ph> 3.0/types.hal für Keymaster 3 und <ph type="x-smartling-placeholder"></ph> 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 Datum und Uhrzeit an, zu denen der Schlüssel aktiv wird. Vorher jeden Versuch, den Schlüssel zu verwenden, ErrorCode::KEY_NOT_YET_VALID

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

Tag::ALGORITHM

Version: 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:

Keymaster 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 und niedriger 
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 wird voraussichtlich kein TEE 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 Verwendungen.

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. In insbesondere Aufrufe an exportKey und getKeyCharacteristics müssen denselben Wert für den Parameter clientId bereitstellen und ruft müssen zum Start dieses Tag und die gleichen zugehörigen Daten als Teil des inParams festgelegt. Wenn nicht die richtigen Daten angegeben werden, gibt die Funktion ErrorCode::INVALID_KEY_BLOB

Der Inhalt dieses Tags ist kryptografisch an den Schlüssel gebunden, Das heißt, es darf für einen Angreifer, der Zugang zu allen sichere Weltgeheimnisse, hat aber keinen Zugriff auf den Tag-Inhalt zur Entschlüsselung der ohne Brute-Force-Angriffe zu erzwingen. Anwendungen können dies verhindern, indem der Inhalt mit ausreichend hoher Entropie spezifiziert wird.

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

Tag::APPLICATION_ID

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. 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 nicht die richtigen Daten angegeben werden, gibt 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 hat – 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 mit beliebiger Länge.

Tag::ASSOCIATED_DATA

Version: 1, 2, 3, 4

Wiederholbar? Nein

Liefert „verknüpfte Daten“ zur AES-GCM-Verschlüsselung oder -Entschlüsselung. Dieses Tag ist zum Aktualisieren und gibt Daten an, die nicht verschlüsselt/entschlüsselt, 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 Gruppe möglicher Anwendungen von welcher zu identifizieren hat eine Schlüsselattestierung initiiert.

Der Wert ist ein Blob, ein Byte-Array mit 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

Stellt den Markennamen des Geräts bereit, wie von Build.BRAND zurückgegeben in Android. Dieses Feld wird nur festgelegt, wenn eine Bestätigung der Gerätekennungen.

Wenn das Gerät keine ID-Attestierung 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 eine Bestätigung der Gerätekennungen.

Wenn das Gerät keine ID-Attestierung 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 keine ID-Attestierung 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_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, und fordert die Bestätigung der Gerätekennungen an.

Wenn das Gerät keine ID-Attestierung 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 keine ID-Attestierung 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_MODEL

Version: 3, 4

Wiederholbar? Nein

Stellt den Modellnamen des Geräts bereit, wie er von Build.MODEL für Android. Dieses Feld wird nur festgelegt, und fordert die Bestätigung der Gerätekennungen an.

Wenn das Gerät keine ID-Attestierung 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_PRODUCT

Version: 3, 4

Wiederholbar? Nein

Stellt den Produktnamen des Geräts bereit, wie er von Build.PRODUCT für Android. Dieses Feld wird nur festgelegt, und fordert die Bestätigung der Gerätekennungen an.

Wenn das Gerät keine ID-Attestierung 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_SERIAL

Version: 3, 4

Wiederholbar? Nein

Gibt die Seriennummer des Geräts an. Dieses Feld wird nur festgelegt, und fordert die Bestätigung der Gerätekennungen an.

Wenn das Gerät keine ID-Attestierung 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, aber dieses Tag nicht, muss der Schlüssel für jede (siehe Start für die Details zur Authentifizierung pro Vorgang).

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

Liefert eine Authentifizierung Token beginnen, Aktualisieren oder Finish um die Nutzerauthentifizierung für einen Schlüsselvorgang nachzuweisen, der eine (Schlüssel hat Tag::USER_SECURE_ID).

Der Wert ist ein Blob, das 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 das generierte Schlüssel, der verwendet werden soll.

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

Keymaster 3 
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 und niedriger 
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 verwendet werden kann. Sie muss mit dem Schlüssel zurückgegeben werden Merkmale von generateKey und getKeyCharacteristics verwendet. Wenn der Aufrufer Tag::BLOB_USAGE_REQUIREMENTS mit Wert KeyBlobUsageRequirements::STANDALONE: Das Trustlet gibt ein Schlüssel-BLOB zurück die auch ohne Dateisystemunterstützung verwendet werden können. 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.

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

Keymaster 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 und niedriger 
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. Geben Sie für AES-Schlüsselvorgänge einen Modus in das Argument additionalParams von starten. Wenn der angegebene Modus nicht in den Modi enthalten ist, die mit dem Schlüssel verknüpft sind, wird der schlägt mit ErrorCode::INCOMPATIBLE_BLOCK_MODE fehl.

Tag::BOOT_PATCHLEVEL

Version: 4

Tag::BOOT_PATCHLEVEL gibt die Ebene des Boot-Images (Kernel) an mit dem der Schlüssel verwendet werden kann. Dieses Tag wird nie an den Keymaster TA gesendet, wird vom TA der Liste der hardwareerzwungenen Autorisierungen hinzugefügt. Jeder Versuch, Verwenden Sie einen Schlüssel mit einem Tag::BOOT_PATCHLEVEL-Wert, der sich vom derzeit ausgeführte System-Patchebene verursacht 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 der Wert 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 ersetzt werden.

Bei jedem Start muss der Bootloader die Patchebene des Boot-Images bereitstellen. in der sicheren Umgebung bereitstellen (der Mechanismus wird durch die Implementierung definiert).

Muss hardwareerzwungen 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 ein boolescher Wert, 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 eine Nonce für nonce-erforderliche Vorgänge angeben kann.

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).

Dieses Tag wird nur für AES-Schlüssel verwendet und ist nur für CBC, CTR und GCM relevant. Blockmodi. Wenn das Tag nicht vorhanden ist, sollten Implementierungen alle Vorgang, bei dem Tag::NONCE für beginnen mit ErrorCode::CALLER_NONCE_PROHIBITED.

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 Digest-Algorithmen an, die mit dem auszuführenden Schlüssel verwendet werden können Signatur- und Verifizierungsvorgänge. Dieses Tag ist für RSA, ECDSA und HMAC-Schlüssel

Mögliche Werte werden durch die folgende 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 niedriger 
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 Digest nicht in den mit dem Schlüssel verknüpften Digests enthalten ist, wird der schlägt 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 des angegebenen Schlüssels erraten. Größe. Um die Flexibilität in Zukunft zu verbessern, führte Keymaster 2 eine explizite Kurven zu definieren. Anfragen zur Generierung von EC-Schlüsseln können Tag::EC_CURVE, Tag::KEY_SIZE oder beides.

Mögliche Werte werden durch die folgende 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 niedriger 
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, auf die Logik von Keymaster 1 zurückgreifen und dabei die entsprechende NIST-Kurve auswählen.

Wenn die Anfrage nur Tag::EC_CURVE enthält, verwenden Sie den Parameter angegebene Kurve. Ab Keymaster 3 werden Kurven in EcCurve Für Keymaster 2 und frühere Versionen sind Kurven definiert. in „keymaster_ec_curve_t“.

Enthält die Anfrage beides, verwenden Sie die durch Tag::EC_CURVE. Prüfen Sie dann, ob die angegebene Schlüsselgröße gleich für diese Kurve geeignet. Falls nicht, geben Sie 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 eine Attestierung muss das Zertifikat für den generierten Schlüssel zeitgebundene eindeutige Geräte-ID, wie durch Tag::UNIQUE_ID enthalten.

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::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 des Algorithmus des Schlüssels. Bei RSA-Schlüsseln gibt Tag::KEY_SIZE beispielsweise Folgendes an: und die Größe des öffentlichen Modulus. 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 maximal zwischen Systemen und neu gestartet. Dies ist ein weiterer Mechanismus zur Ratenbegrenzung für die Schlüsselnutzung.

Der Wert ist eine 32-Bit-Ganzzahl, die die Nutzung pro Start darstellt.

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. Dies impliziert, dass ein Trustlet eine Tabelle mit Nutzungszählern für Schlüssel führt, die Tag. Da der Keymaster-Arbeitsspeicher häufig begrenzt ist, kann diese Tabelle einen festen und Keymaster kann bei Vorgängen, bei denen versucht wird, Schlüssel mit wenn die Tabelle voll ist. Die Tabelle muss mindestens 16 Schlüssel enthalten. 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 minimale MAC-Länge in Bit. Es ist ein Vielfaches von 8. Für HMAC-Schlüssels verwendet wird, ist der Wert mindestens 64. Bei GCM-Schlüsseln beträgt der Wert mindestens 96. und nicht mehr als 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die Mindestzeitspanne an, die zwischen den zulässigen Operationen mit einem Schlüssel. 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 Sekunden zwischen zulässigen Geschäftsabläufe.

Wenn ein Schlüssel mit diesem Tag in einem Vorgang verwendet wird, einen Timer starten während der Fertigstellung oder Anruf 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. Dieses impliziert, 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 Nutzer enthalten, die in Gebrauch sind. Schlüssel verwenden und Tabellenslots offensiv wiederverwenden, wenn die Mindestnutzungsintervalle für 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 die sich gegenseitig ausschließen mit Tag::USER_SECURE_ID.

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 einen Nonce- oder Initialisierungsvektor (IV) für AES GCM, CBC, oder CTR-Verschlüsselung oder -entschlüsselung. Dieses Tag wird für beginnen Verschlüsselungs- und Entschlüsselungsvorgängen. Sie ist nur für beginnen Der Schlüssel enthält Tag::CALLER_NONCE. 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. Zulässige Länge hängen vom Modus ab: GCM-Nonces sind 12 Byte lang. CBC und CTR IVs sind 16 Bytes erhalten.

Tag::ORIGIN

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt an, wo der Schlüssel erstellt wurde, falls bekannt. Dieses Tag darf nicht angegeben werden beim Generieren oder Importieren von Schlüsseln. Sie müssen den Schlüsselmerkmalen hinzugefügt werden. aus dem Trustlet.

Keymaster 3

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

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

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 Keymaster den Schlüssel generiert hat. In der Liste der hardwareerzwungenen URLs Der Schlüssel wurde auf sicherer Hardware generiert und ist dauerhaft hardwaregebunden. 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. Ist sie in der Liste der hardwareerzwungenen, 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 hardwaregebunden, aber es ist nicht bekannt, ob der Schlüssel ursprünglich in sichere Hardware haben oder importiert wurde. Dies tritt nur auf, wenn die Keymaster0-Hardware die Keymaster1-Dienste emulieren.

Tag::ORIGINATION_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt Datum und Uhrzeit für den Ablauf des Schlüssels zum Signieren und Verschlüsselungszwecke verwendet werden. 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 1. Januar 1970.

Tag::OS_PATCHLEVEL

Version: 2, 3, 4

Wiederholbar? Nein

Dieses Tag wird nie an den Keymaster TA gesendet, sondern zum Liste der hardwareerzwungenen Autorisierungen vom TA.

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 dem aktuellen Patch-Level 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 zum Liste der hardwareerzwungenen Autorisierungen vom TA.

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. Für einen Schlüssel, der unter Android Version 4.0.3 generiert wurde, lautet beispielsweise der Wert wäre 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.

Mögliche Werte werden durch die folgende 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 niedriger 
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 verwendet. Nur für RSA-Verschlüsselungs-/-Entschlüsselungsschlüssel und Angabe von RSA PKCS#1v2 OAEP Padding und RSA PKCS#1 v1.5 zufälliges Padding. PaddingMode::RSA_PSS und PaddingMode::RSA_PKCS1_1_5_SIGN werden nur für RSA verwendet Signatur-/Bestätigungsschlüssel an und geben Sie RSA PKCS#1v2 PSS an. Padding und RSA PKCS#1 v1.5 deterministisches Padding.

PaddingMode::NONE kann mit RSA oder AES-Schlüssel. Für AES-Schlüssel, wenn PaddingMode::NONE verwendet wird im Blockmodus ECB oder CBC und die zu verschlüsselnden oder zu entschlüsselnden Daten kein Vielfaches der Länge der AES-Blockgröße ist, wird der Abschlussaufruf schlägt mit ErrorCode::INVALID_INPUT_LENGTH fehl.

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

Dieses Tag ist wiederholbar. 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 fehl mit ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::ZWECK

Version: 1, 2, 3, 4

Wiederholbar? Ja

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

Mögliche Werte werden durch die folgende 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 niedriger 
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. können Schlüssel mit mehreren Werten generiert werden, obwohl ein Vorgang nur einem Zweck dient. Wenn der Parameter begin wird aufgerufen zum Starten eines Vorgangs wird der Zweck des Vorgangs angegeben. Wenn der für den Vorgang angegebene Zweck nicht vom Schlüssel enthält, 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 ein boolescher Wert, daher sind die möglichen Werte „true“ (falls das Tag vorhanden ist) und false (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. Es ist möglich, Schlüssel ohne dieses Tag können gelöscht und dann aus dem Back-up wiederhergestellt werden.

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::ROOT_OF_TRUST

Version: 1, 2, 3, 4

Wiederholbar? Nein

Gibt die Vertrauensbasis an, den Schlüssel, der vom verifizierten Bootmodus für ob das Betriebssystem gestartet wurde (falls vorhanden). Dieses Tag wird nie bereitgestellt in den Schlüsselmerkmalen an den Keymaster zurückgegeben oder vom Keymaster zurückgegeben werden.

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 die nur für RSA-Schlüssel relevant und für alle RSA-Schlüssel erforderlich sind.

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 kann 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 mit 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 Arten von Nutzerauthentifizierungssystemen an, die zur Autorisierung verwendet werden können . Wenn Keymaster aufgefordert wird, eine Operation mit einem Schlüssel durchzuführen, -Tag enthält, empfängt er ein Authentifizierungs-Token und die Das Feld authenticator_type 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 niedriger 
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 darf Authentifizierungsstatus. Dieses Tag schließt sich gegenseitig aus mit Tag::NO_AUTH_REQUIRED.

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 kein Authentifizierungstoken oder stellt ein Authentifizierungstoken ohne übereinstimmenden Richtlinienstatuswert schlägt fehl.

Dieses Tag ist wiederholbar. Wenn einer der angegebenen Werte mit einer Richtlinie übereinstimmt state-Wert im Authentifizierungstoken auf, ist der Schlüssel zur 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, mit dem der Schlüssel verwendet werden können. 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 der Wert 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“.

Der HAL von IKeymasterDevice muss die aktuelle Anbieter-Patchebene vom System auslesen. ro.vendor.build.security_patch und übergeben sie an den wenn die HAL zum ersten Mal geladen wird (Mechanismus ist Implementierung). Die sichere Umgebung darf keine anderen Patchlevel verfügbar sind.

Muss hardwareerzwungen werden.