Keymaster-Autorisierungs-Tags

Diese Seite enthält Details zur Unterstützung der Implementierung von Keymaster-HALs. Es deckt jedes Tag im HAL ab, 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 unten aufgeführten 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 definiert, z. B. 3.0/types.hal für Keymaster 3 und 4.0/types.hal für Keymaster 4. Für Keymaster 2 und niedriger: Tags werden in platform/hardware/libhardware/include/hardware/keymaster_defs.h definiert.

Informationen zu den Funktionen finden Sie auf der Seite „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 Zeitpunkt schlägt jeder Versuch, den Schlüssel zu verwenden, mit ErrorCode::KEY_NOT_YET_VALID fehl.

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

Tag::ALGORITHMUS

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 früher
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 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 davon ausgegangen, dass ein TEE einen sicheren Zugriff auf einen On-Body-Sensor ermöglichen kann oder dass On-Body-Sensoren sehr sicher sind, sodass davon ausgegangen wird, dass es sich hierbei um eine rein softwaregesteuerte 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 dieses Tag für „generateKey“ oder „importKey“ bereitgestellt wird, gibt es Daten an, die bei allen Verwendungen des Schlüssels erforderlich sind. Insbesondere müssen Aufrufe von exportKey und getKeyCharacteristics denselben Wert für den Parameter clientId bereitstellen, und Aufrufe von begin müssen dieses Tag und dieselben zugehörigen Daten als Teil des inParams Sets bereitstellen. Wenn nicht die richtigen Daten 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, aber keinen Zugriff auf den Tag-Inhalt hat, nicht möglich sein darf, den Schlüssel zu entschlüsseln, ohne das 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 Array von Bytes beliebiger Länge.

Tag::APPLICATION_ID

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Wenn dieses Tag für „generateKey“ oder „importKey“ bereitgestellt wird, gibt es Daten an, die bei allen Verwendungen des Schlüssels erforderlich sind. Insbesondere müssen Aufrufe von exportKey und getKeyCharacteristics denselben Wert im Parameter clientId bereitstellen, und Aufrufe von begin müssen dieses Tag und dieselben zugehörigen Daten als Teil des inParams Sets bereitstellen. Wenn nicht die richtigen Daten 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 den Tag-Inhalt brutal zu erzwingen). ).

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ASSOCIATED_DATA

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Stellt „zugehörige Daten“ für die AES-GCM-Verschlüsselung oder -Entschlüsselung bereit. Dieses Tag wird zur Aktualisierung bereitgestellt und gibt Daten an, die nicht verschlüsselt/entschlüsselt werden, aber zur Berechnung des GCM-Tags verwendet werden.

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ATTESTATION_APPLICATION_ID

Version : 3, 4

Wiederholbar ? NEIN

Wird verwendet, um den Satz möglicher Anwendungen zu identifizieren, für die eine Schlüsselbescheinigung initiiert wurde.

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ATTESTATION_CHALLENGE

Version : 3, 4

Wiederholbar ? NEIN

Wird verwendet, um eine Bescheinigung anzufechten.

Der Wert ist ein Blob, ein Array von Bytes 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 Bescheinigung der Gerätekennungen angefordert wird.

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

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ATTESTATION_ID_DEVICE

Version : 3, 4

Wiederholbar ? NEIN

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

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

Der Wert ist ein Blob, ein Array von Bytes 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 Bescheinigung der Gerätekennungen angefordert wird.

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

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ATTESTATION_ID_MANUFACTURER

Version : 3, 4

Wiederholbar ? NEIN

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

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

Der Wert ist ein Blob, ein Array von Bytes 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 Bescheinigung der Gerätekennungen angefordert wird.

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

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ATTESTATION_ID_MODEL

Version : 3, 4

Wiederholbar ? NEIN

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

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

Der Wert ist ein Blob, ein Array von Bytes 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 Bescheinigung der Gerätekennungen angefordert wird.

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

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::ATTESTATION_ID_SERIAL

Version : 3, 4

Wiederholbar ? NEIN

Gibt die Seriennummer des Geräts an. Dieses Feld wird nur gesetzt, wenn eine Bescheinigung der Gerätekennungen angefordert wird.

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

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::AUTH_TIMEOUT

Version : 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, muss der Schlüssel bei jeder Verwendung authentifiziert werden (siehe Beginn für Einzelheiten zum Ablauf der Authentifizierung pro Vorgang).

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

Tag::AUTH_TOKEN

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Stellt ein Authentifizierungstoken zum Begin , Update oder Finish bereit, um die Benutzerauthentifizierung für einen Schlüsselvorgang zu beweisen, 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 die Verwendung des generierten Schlüssels an.

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 früher
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 unter der angegebenen Bedingung verwendbar ist. Es muss mit den Schlüsselmerkmalen von genericKey und getKeyCharacteristics zurückgegeben werden. Wenn der Aufrufer Tag::BLOB_USAGE_REQUIREMENTS mit dem Wert KeyBlobUsageRequirements::STANDALONE angibt, gibt das Trustlet einen Schlüsselblob zurück, der ohne Dateisystemunterstützung verwendet werden kann. Dies ist von entscheidender Bedeutung 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

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 früher
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 im Argument additionalParams von begin einen Modus an. Wenn sich der angegebene Modus nicht in den mit dem Schlüssel verknüpften Modi befindet, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_BLOCK_MODE fehl.

Tag::BOOT_PATCHLEVEL

Version : 4

Tag::BOOT_PATCHLEVEL gibt die Sicherheitspatchstufe des Boot-Images (Kernels) an, mit der der Schlüssel verwendet werden darf. Dieses Tag wird nie an den Keymaster-TA gesendet, sondern vom TA zur Hardware-erzwungenen Autorisierungsliste hinzugefügt. Jeder Versuch, einen Schlüssel mit einem anderen Tag::BOOT_PATCHLEVEL Wert als dem aktuell ausgeführten System-Patchlevel zu verwenden begin() , getKeyCharacteristics() oder exportKey() ErrorCode::KEY_REQUIRES_UPGRADE zurückgibt. Weitere Informationen finden Sie unter upgradeKey() .

Der Wert des Tags ist eine Ganzzahl der Form 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 beispielsweise auf einem Android-Gerät generiert wurde, das zuletzt am 5. Juni 2018 aktualisiert wurde, wäre der Wert 20180605. Wenn der Tag nicht bekannt ist, kann er durch 00 ersetzt werden.

Bei jedem Start muss der Bootloader der sicheren Umgebung die Patch-Ebene des Start-Images bereitstellen (Mechanismus ist durch die Implementierung definiert).

Muss durch Hardware 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 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 fehl.

Tag::CALLER_NONCE

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt an, dass der Aufrufer eine Nonce für Nonce-erfordernde Vorgänge bereitstellen 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).

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 jeden Vorgang ablehnen, der Tag::NONCE bereitstellt, um mit ErrorCode::CALLER_NONCE_PROHIBITED zu beginnen .

Tag::CREATION_DATETIME

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

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

Tag::DIGEST

Version : 1, 2, 3, 4

Wiederholbar ? Ja

Gibt die Digest-Algorithmen an, die mit dem Schlüssel zum Durchführen von Signierungs- und Verifizierungsvorgängen verwendet werden können. Dieses Tag ist für RSA-, ECDSA- und HMAC-Schlüssel relevant.

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 früher
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 Signierungs- und Verifizierungsvorgänge einen Digest im Argument additionalParams von begin an. Wenn der angegebene Digest nicht in den Digests enthalten ist, die dem Schlüssel zugeordnet sind, 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-Tasten verwendete Kurve anhand der angegebenen Schlüsselgröße erraten. Um die Flexibilität in Zukunft zu verbessern, hat Keymaster 2 eine explizite Möglichkeit zur Angabe von Kurven eingeführt. Anforderungen zur EC-Schlüsselgenerierung können Tag::EC_CURVE , Tag::KEY_SIZE oder beides haben.

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 früher
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, greifen Sie auf die Keymaster 1-Logik zurück und wählen Sie die entsprechende NIST-Kurve aus.

Wenn die Anfrage 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 Sie ErrorCode::INVALID_ARGUMENT zurück.

Tag::INCLUDE_UNIQUE_ID

Version : 2, 3, 4

Wiederholbar ? NEIN

Dieses Tag wird während der Schlüsselgenerierung angegeben, um anzugeben, dass ein Nachweiszertifikat für den generierten Schlüssel eine anwendungsbezogene und zeitlich begrenzte, 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).

Tag::KEY_SIZE

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

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

Tag::MAC_LENGTH

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

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

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

Tag::MAX_USES_PER_BOOT

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

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

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

Wenn ein Schlüssel mit diesem Tag in einer Operation verwendet wird, sollte während des Begin- Aufrufs ein mit dem Schlüssel verknüpfter Zähler erhöht werden. Nachdem der Schlüsselzähler diesen Wert überschritten hat, schlagen alle nachfolgenden Versuche, den Schlüssel zu verwenden, mit ErrorCode::MAX_OPS_EXCEEDED fehl, bis das Gerät neu gestartet wird. Dies bedeutet, dass ein Trustlet eine Tabelle mit Nutzungszählern für Schlüssel mit diesem Tag führt. Da der Speicher von Keymaster oft begrenzt ist, kann diese Tabelle eine feste maximale Größe haben und Keymaster kann bei Vorgängen, die versuchen, Schlüssel mit diesem Tag zu verwenden, fehlschlagen, wenn die Tabelle voll ist. Der Tisch muss mindestens 16 Schlüssel aufnehmen können. Wenn ein Vorgang fehlschlägt, weil die Tabelle voll ist, gibt Keymaster ErrorCode::TOO_MANY_OPERATIONS zurück.

Tag::MIN_MAC_LENGTH

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Dieses Tag gibt die minimale MAC-Länge an, die mit diesem Schlüssel für HMAC-Schlüssel und AES-Schlüssel, die den GCM-Modus unterstützen, angefordert oder überprüft 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 nicht mehr als 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt die Mindestzeit an, die zwischen zulässigen Vorgängen mit einer Taste vergeht. Dies kann verwendet werden, um die Verwendungsrate von Schlüsseln in Kontexten zu begrenzen, in denen eine unbegrenzte Verwendung Brute-Force-Angriffe ermöglichen könnte.

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

Wenn ein Schlüssel mit diesem Tag in einem Vorgang verwendet wird, wird während des Abschluss- oder Abbruchanrufs ein Timer gestartet. Jeder Aufruf von begin , der vor dem Timer empfangen wird, zeigt an, dass das durch Tag::MIN_SECONDS_BETWEEN_OPS angegebene Intervall abgelaufen ist, schlägt mit ErrorCode::KEY_RATE_LIMIT_EXCEEDED fehl. Dies bedeutet, dass ein Trustlet eine Tabelle mit Nutzungszählern für Schlüssel mit diesem Tag führt. Da der Speicher von Keymaster oft begrenzt ist, kann diese Tabelle eine feste maximale Größe haben und Keymaster kann bei Vorgängen, die versuchen, Schlüssel mit diesem Tag zu verwenden, fehlschlagen, wenn die Tabelle voll ist. Die Tabelle muss mindestens 32 verwendete Schlüssel aufnehmen und Tabellenslots nach Ablauf der Mindestnutzungsintervalle der Schlüssel konsequent wiederverwenden. Wenn ein Vorgang fehlschlägt, weil die Tabelle voll ist, gibt Keymaster ErrorCode::TOO_MANY_OPERATIONS zurück.

Tag::NO_AUTH_REQUIRED

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt an, dass für die Verwendung dieses Schlüssels keine Authentifizierung erforderlich ist. Dieses Tag und Tag::USER_SECURE_ID schließen sich gegenseitig 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).

Tag::NONCE

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Stellt einen Nonce oder Initialisierungsvektor (IV) für die AES-GCM-, CBC- oder CTR-Verschlüsselung oder -Entschlüsselung bereit oder gibt sie zurück. Dieses Tag wird bereitgestellt, um bei 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 von Keymaster zufällig eine entsprechende Nonce oder IV generiert und von Beginn an zurückgegeben.

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

Tag::ORIGIN

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

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

Schlüsselmeister 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üher

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 vollständige Bedeutung des Werts hängt nicht nur vom Wert ab, sondern auch davon, ob er in der Liste der durch Hardware oder durch Software erzwungenen Merkmale gefunden wird.

GENERATED zeigt an, dass Keymaster den Schlüssel generiert hat. Wenn in der Liste „Hardware erzwungen“ aufgeführt ist, wurde der Schlüssel in sicherer Hardware generiert und ist dauerhaft an die Hardware gebunden. Wenn in der Liste der durch Software erzwungenen Schlüssel aufgeführt ist, wurde der Schlüssel in SoftKeymaster generiert und ist nicht an die Hardware gebunden.

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

IMPORTED gibt an, dass der Schlüssel außerhalb von Keymaster generiert und in Keymaster importiert wurde. Wenn es in der Hardware-erzwungenen Liste aufgeführt ist, ist es dauerhaft an die Hardware gebunden, es können jedoch Kopien außerhalb der sicheren Hardware vorhanden sein. Wenn der Schlüssel in der Software-Erzwingungsliste aufgeführt ist, wurde er in SoftKeymaster importiert und ist nicht an die Hardware gebunden.

UNKNOWN sollte nur in der Hardware-erzwungenen Liste erscheinen. Dies weist darauf hin, dass der Schlüssel an die Hardware gebunden ist. Es ist jedoch nicht bekannt, ob der Schlüssel ursprünglich in sicherer Hardware generiert oder importiert wurde. Dies tritt nur auf, wenn keymaster0-Hardware zum Emulieren von keymaster1-Diensten verwendet wird.

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 Signierungs- und Verschlüsselungszwecke abläuft. Nach dieser Zeit schlägt jeder Versuch, einen Schlüssel mit KeyPurpose::SIGN oder KeyPurpose::ENCRYPT zu Beginn zu verwenden, mit ErrorCode::KEY_EXPIRED fehl.

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

Tag::OS_PATCHLEVEL

Version : 2, 3, 4

Wiederholbar ? NEIN

Dieses Tag wird niemals an den Keymaster-TA gesendet, sondern vom TA zur Hardware-erzwungenen Autorisierungsliste hinzugefügt.

Der Wert des Tags ist eine Ganzzahl der Form 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, deren Patch-Level von dem aktuellen Patch-Level abweicht, 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 zurückgeben. Weitere Informationen finden Sie unter Versionsbindung .

Tag::OS_VERSION

Version : 2, 3, 4

Wiederholbar ? NEIN

Dieses Tag wird nie an den Keymaster-TA gesendet, sondern vom TA zur Hardware-erzwungenen Autorisierungsliste hinzugefügt.

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

Etikett::POLSTERUNG

Version : 1, 2, 3, 4

Wiederholbar ? Ja

Gibt die Füllmodi an, die mit der Taste 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:

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üher
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-Auffüllung bzw. RSA PKCS#1 v1.5 deterministische Auffüllung 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 sind, schlägt der Aufruf zum Beenden mit ErrorCode::INVALID_INPUT_LENGTH fehl.

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 Auffüllmodus angegeben werden. Wenn der angegebene Modus für den Schlüssel nicht autorisiert ist, schlägt der Vorgang mit ErrorCode::INCOMPATIBLE_BLOCK_MODE fehl.

Schlagwort::ZWECK

Version : 1, 2, 3, 4

Wiederholbar ? Ja

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

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 früher
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 einen einzigen Zweck hat. Wenn die Funktion begin 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 fehl.

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 zur Schlüsselbescheinigung 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

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt an, dass der Schlüssel rollbackresistent ist. Das 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).

Tag::ROOT_OF_TRUST

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt den Root of Trust an, den Schlüssel, der beim verifizierten Start verwendet wird, um das gestartete Betriebssystem zu validieren (falls vorhanden). Dieses Tag wird Keymaster in den Schlüsselmerkmalen niemals zur Verfügung gestellt oder von ihm 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 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 unterstützen 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 fehl.

Tag::UNIQUE_ID

Version : 3, 4

Wiederholbar ? NEIN

Wird zur Bereitstellung einer eindeutigen ID im Nachweis verwendet.

Der Wert ist ein Blob, ein Array von Bytes beliebiger Länge.

Tag::USAGE_EXPIRE_DATETIME

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt das Datum und die Uhrzeit an, zu der 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 Beginn zu verwenden, mit ErrorCode::KEY_EXPIRED fehl.

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

Tag::USER_AUTH_TYPE

Version : 1, 2, 3, 4

Wiederholbar ? NEIN

Gibt die Arten von Benutzerauthentifizierern an, die zur Autorisierung dieses Schlüssels verwendet werden können. Wenn Keymaster aufgefordert wird, eine Operation mit einem Schlüssel mit diesem Tag durchzuführen, erhält er 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 umwandelt, und auth_type_tag_value der Wert dieses Tags ist.

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

Keymaster 3
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 und früher
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 ? NEIN

Gibt an, dass ein Schlüssel nur unter einem bestimmten sicheren Benutzerauthentifizierungsstatus verwendet werden darf. Dieses Tag und Tag::NO_AUTH_REQUIRED schließen sich gegenseitig 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, der mit einem Schlüssel mit diesem Tag beginnt , der kein Authentifizierungstoken bereitstellt oder ein Authentifizierungstoken ohne passenden 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 der Vorgang mit ErrorCode::KEY_USER_NOT_AUTHENTICATED fehl.

Tag::VENDOR_PATCHLEVEL

Version : 4

Dieses Tag gibt die Image-Sicherheitspatchstufe des Herstellers an, mit der der Schlüssel verwendet werden kann. Dieses Tag wird nie an den Keymaster-TA gesendet, sondern vom TA zur Hardware-erzwungenen Autorisierungsliste hinzugefügt. Jeder Versuch, einen Schlüssel mit einem anderen Tag::VENDOR_PATCHLEVEL -Wert als dem aktuell ausgeführten System-Patchlevel zu verwenden, muss dazu führen, dass begin() , getKeyCharacteristics() oder exportKey() ErrorCode::KEY_REQUIRES_UPGRADE zurückgibt. Weitere Informationen finden Sie unter upgradeKey() .

Der Wert des Tags ist eine Ganzzahl der Form 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 auf einem Android-Gerät generiert wurde und zuletzt am 5. Juni 2018 aktualisiert wurde, wäre der Wert beispielsweise 20180605.

Die IKeymasterDevice-HAL muss den Patchlevel des aktuellen Anbieters aus der Systemeigenschaft ro.vendor.build.security_patch lesen und ihn beim ersten Laden der HAL an die sichere Umgebung übermitteln (Mechanismus ist durch die Implementierung definiert). Die sichere Umgebung darf erst nach dem nächsten Start einen anderen Patchlevel akzeptieren.

Muss durch Hardware erzwungen werden.