Tags d'autorisation Keymaster

Cette page fournit des informations pour aider les développeurs à implémenter des HAL Keymaster. Il couvre chaque balise du HAL, la version Keymaster de ce tag disponible. et si le tag est reproductible. Sauf indication contraire dans les descriptions des tags, tous les tags ci-dessous sont utilisés lors de la génération de la clé pour spécifier la caractéristiques.

Pour Keymaster 4, les balises sont définies platform/hardware/interfaces/keymaster/keymaster-version/types.hal, tels que 3.0/types.hal pour Keymaster 3 et 4.0/types.hal pour Keymaster 4. Pour Keymaster 2 et les versions antérieures, les tags sont définis dans platform/hardware/libhardware/include/hardware/keymaster_defs.h

Pour les fonctions, consultez la page Keymaster Functions.

Tag::ACTIVE_DATETIME

Version : 1, 2, 3, 4

Répétable ? Non

Spécifie la date et l'heure auxquelles la clé devient active. Avant toute tentative d'utilisation de la clé échoue ErrorCode::KEY_NOT_YET_VALID

La valeur est un entier de 64 bits représentant les millisecondes écoulées depuis le 1er janvier. 1970.

Tag::ALGORITHME

Version : 1, 2, 3, 4

Répétable ? Non

Spécifie l'algorithme cryptographique avec lequel la clé est utilisée.

Les valeurs possibles sont définies par l'énumération suivante :

Keymaster 3 
enum class Algorithm : uint32_t {
    RSA = 1,
    EC = 3,
    AES = 32,
    HMAC = 128,
};
Keymaster 2 et versions antérieures 
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

Répétable ? Non

Réservé pour une utilisation ultérieure.

Balise::ALLOW_WHILE_ON_BODY

Version : 2, 3, 4

Répétable ? Non

Cette balise ne s'applique qu'aux appareils Android Wear équipés de capteurs sur le corps. À À ce stade, aucun TEE ne peut fournir un accès sécurisé par rapport à un capteur présent sur l'appareil ou très sécurisés. est censée être une fonctionnalité purement appliquée par logiciel.

Balise::ALL_USERS

Version: 3, 4

Répétable ? Non

Réservé pour une utilisation ultérieure.

Tag::APPLICATION_DATA

Version : 1, 2, 3, 4

Répétable ? Non

Lorsqu'ils sont fournis à generateKey ou importKey, cette balise spécifie les données nécessaires à toutes les utilisations de la clé. En particulier, les appels à exportKey et getKeyCharacteristics doivent fournir la même valeur au paramètre clientId, et les appels à begin doivent fournir cette balise et les mêmes données associées dans l'ensemble inParams. Si les données correctes ne sont pas fournies, la fonction renvoie ErrorCode::INVALID_KEY_BLOB

Le contenu de cette balise est lié à la clé de manière cryptographique, Cela signifie qu'il ne doit pas être possible pour un adversaire d'accéder à toutes secrets du monde sécurisés, mais n'a pas accès au contenu du tag pour déchiffrer sans forcer le contenu du tag, ce que les applications peuvent éviter spécifiant un contenu dont l'entropie est suffisamment élevée.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Tag::APPLICATION_ID

Version: 1, 2, 3, 4

Répétable ? Non

Lorsqu'ils sont fournis à generateKey ou importKey, cette balise spécifie les données nécessaires à toutes les utilisations de la clé. En particulier, les appels à exportKey et getKeyCharacteristics doivent fournir la même valeur dans le paramètre clientId, et les appels à begin doivent fournir cette balise et les mêmes données associées dans l'ensemble inParams. Si les données correctes ne sont pas fournies, la fonction renvoie ErrorCode::INVALID_KEY_BLOB.

Le contenu de cette balise est lié à la clé de manière cryptographique, ce qui signifie qu'un pirate informatique qui peut accéder à tous les secrets du monde sécurisé, mais qui n'a pas accès au contenu de la balise, ne peut pas déchiffrer la clé (sans forcer le contenu de la balise).

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ASSOCIATED_DATA

Version : 1, 2, 3, 4

Répétable ? Non

Fournit des "données associées" pour le chiffrement ou le déchiffrement AES-GCM. Cette balise est fournie pour mettre à jour et spécifie les données qui ne sont pas chiffrées/déchiffrées, mais qui sont utilisées pour calculer la balise GCM.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_APPLICATION_ID

Version: 3, 4

Répétable ? Non

Permet d'identifier l'ensemble des applications possibles dont l'une a lancé une attestation de clé.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_CHALLENGE

Version: 3, 4

Répétable ? Non

Utilisé pour fournir la question d'authentification dans l'attestation.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_ID_BRAND

Version: 3, 4

Répétable ? Non

Fournit le nom de la marque de l'appareil, tel que renvoyé par Build.BRAND dans Android. Ce champ n'est défini que lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'ID (ou destroyAttestationIds() a déjà été appelé et l'appareil peut n'atteste plus de ses identifiants), toute demande d'attestation de clé incluant cette balise échoue avec l'erreur ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_ID_DEVICE

Version : 3, 4

Répétable ? Non

Fournit le nom de l'appareil, tel que renvoyé par Build.DEVICE dans Android. Ce champ n'est défini que lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'ID (ou destroyAttestationIds() a déjà été appelé et l'appareil peut n'atteste plus de ses identifiants), toute demande d'attestation de clé incluant cette balise échoue avec l'erreur ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Tag::ATTESTATION_ID_IMEI

Version: 3, 4

Répétable ? Oui

Fournit les codes IMEI de toutes les radios de l'appareil. Ce champ n'est défini lorsque vous demandez une attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'identité (ou si destroyAttestationIds() a déjà été appelé et que l'appareil ne peut plus attester de ses identités), toute requête d'attestation de clé incluant cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Tag::ATTESTATION_ID_MANUFACTURER

Version: 3, 4

Répétable ? Non

Fournit le nom du fabricant de l'appareil, tel que renvoyé par Build.MANUFACTURER sur Android. Ce champ n'est défini que si demandant une attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'identité (ou si destroyAttestationIds() a déjà été appelé et que l'appareil ne peut plus attester de ses ID), toute requête d'attestation de clé incluant cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_ID_MEID

Version: 3, 4

Répétable ? Oui

Fournit les MEID de toutes les radios de l'appareil. Ce champ n'est défini que lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'identité (ou si destroyAttestationIds() a déjà été appelé et que l'appareil ne peut plus attester de ses identités), toute requête d'attestation de clé incluant cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_ID_MODEL

Version: 3, 4

Répétable ? Non

Indique le nom de modèle de l'appareil, tel que renvoyé par Build.MODEL sur Android. Ce champ n'est défini que si demandant une attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'identité (ou si destroyAttestationIds() a déjà été appelé et que l'appareil ne peut plus attester de ses ID), toute requête d'attestation de clé incluant cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Tag::ATTESTATION_ID_PRODUCT

Version : 3, 4

Répétable ? Non

Fournit le nom de produit de l'appareil, tel que renvoyé par Build.PRODUCT sur Android. Ce champ n'est défini que lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'identité (ou si destroyAttestationIds() a déjà été appelé et que l'appareil ne peut plus attester de ses ID), toute requête d'attestation de clé incluant cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::ATTESTATION_ID_SERIAL

Version: 3, 4

Répétable ? Non

Indique le numéro de série de l'appareil. Ce champ n'est défini que si demandant une attestation des identifiants de l'appareil.

Si l'appareil n'est pas compatible avec l'attestation d'identité (ou si destroyAttestationIds() a déjà été appelé et que l'appareil ne peut plus attester de ses ID), toute requête d'attestation de clé incluant cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Balise::AUTH_TIMEOUT

Version : 1, 2, 3, 4

Répétable ? Non

Indique la durée, en secondes, pendant laquelle la clé est autorisée à être utilisée après l'authentification. Si Tag::USER_SECURE_ID est présent et que cette balise ne l'est pas, la clé doit être authentifiée pour chaque utilisation (voir begin pour en savoir plus sur le flux d'authentification par opération).

La valeur est un entier de 32 bits qui indique l'heure en secondes après une l'utilisateur spécifié dans le champ Tag::USER_SECURE_ID avec la méthode d'authentification a réussi. spécifiée par Tag::USER_AUTH_TYPE que la clé peut être utilisé.

Tag::AUTH_TOKEN

Version : 1, 2, 3, 4

Répétable ? Non

Fournit un jeton d'authentification pour débuter, mettre à jour ou terminer, afin de prouver l'authentification de l'utilisateur pour une opération de clé qui l'exige (la clé possède Tag::USER_SECURE_ID).

La valeur est un blob qui contient une structure hw_auth_token_t.

Tag::BLOB_USAGE_REQUIREMENTS

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie les conditions d'environnement système requises pour que la clé générée puisse être utilisée.

Les valeurs possibles sont définies par l'énumération suivante :

Keymaster 3 
enum class KeyBlobUsageRequirements : uint32_t {
    STANDALONE = 0,
    REQUIRES_FILE_SYSTEM = 1,
};
Keymaster 2 et versions antérieures 
typedef enum {
    KM_BLOB_STANDALONE = 0,
    KM_BLOB_REQUIRES_FILE_SYSTEM = 1,
} keymaster_key_blob_usage_requirements_t;

Cette balise peut être spécifiée lors de la génération de la clé pour exiger que la clé soit utilisable dans la condition spécifiée. Il doit être renvoyé avec la clé des caractéristiques de generateKey et getKeyCharacteristics. Si l'appelant spécifie Tag::BLOB_USAGE_REQUIREMENTS avec valeur KeyBlobUsageRequirements::STANDALONE. Le trustlet renvoie un blob de clé. qui peut être utilisé sans prise en charge de système de fichiers. Cela est essentiel pour les appareils dotés de disques chiffrés, où le système de fichiers peut ne pas être disponible avant qu'une clé Keymaster ne soit utilisée pour déchiffrer le disque.

Tag::BLOCK_MODE

Version: 1, 2, 3, 4

Répétable ? Oui

Spécifie les modes de chiffrement par bloc avec lesquels la clé peut être utilisée. Ce tag ne concerne que les clés AES.

Les valeurs possibles sont définies par l'énumération suivante :

Keymaster 3 
enum class BlockMode : uint32_t {
    ECB = 1,
    CBC = 2,
    CTR = 3,
    GCM = 32,
};
Keymaster 2 et versions antérieures 
typedef enum {
    KM_MODE_ECB = 1,
    KM_MODE_CBC = 2,
    KM_MODE_CTR = 3,
    KM_MODE_GCM = 32,
} keymaster_block_mode_t;

Ce tag est reproductible et, pour les opérations de clé AES, spécifiez un mode dans l'argument additionalParams de commencer. Si le mode spécifié ne figure pas parmi les modes associés à la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Balise::BOOT_PATCHLEVEL

Version : 4

Tag::BOOT_PATCHLEVEL spécifie le niveau du correctif de sécurité de l'image de démarrage (noyau) avec lequel la clé peut être utilisée. Ce tag n'est jamais envoyé au TA Keymaster, mais est ajouté à la liste des autorisations matériellement appliquées par les TA. Toute tentative d'utilisation d'une clé avec une valeur Tag::BOOT_PATCHLEVEL différente du niveau de correctif du système en cours d'exécution entraîne le renvoi de ErrorCode::KEY_REQUIRES_UPGRADE par begin(), getKeyCharacteristics() ou exportKey(). Pour en savoir plus, consultez upgradeKey().

La valeur de la balise est un entier au format AAAAMMJJ, où AAAA correspond à l'année à quatre chiffres de la dernière mise à jour, MM correspond au mois à deux chiffres et JJ correspond au jour à deux chiffres de la dernière mise à jour. Par exemple, pour une clé générée sur un Dernière mise à jour de l'appareil Android le 5 juin 2018, la valeur serait 20180605. Si le jour n'est pas connu, vous pouvez remplacer la valeur par 00.

À chaque démarrage, le bootloader doit fournir le niveau de correctif de l'image de démarrage à l'environnement sécurisé (le mécanisme est défini par l'implémentation).

Les règles s'appliquent au matériel.

Balise::BOOTLOADER_ONLY

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie que seul le bootloader peut utiliser la clé.

Cette balise étant booléenne, les valeurs possibles sont "true" (si la balise est présente). et "false" (si la balise n'est pas présente).

Toute tentative d'utilisation d'une clé avec Tag::BOOTLOADER_ONLY à partir de Défaillance du système Android avec ErrorCode::INVALID_KEY_BLOB.

Tag::CALLER_NONCE

Version : 1, 2, 3, 4

Répétable ? Non

Spécifie que l'appelant peut fournir un nonce pour les opérations nécessitant un nonce.

Cette balise étant booléenne, les valeurs possibles sont "true" (si la balise est présente). et "false" (si la balise n'est pas présente).

Cette balise n'est utilisée que pour les clés AES et n'est pertinente que pour les modes de blocage CBC, CTR et GCM. Si la balise n'est pas présente, les implémentations doivent refuser toute opération qui fournit Tag::NONCE pour commencer avec ErrorCode::CALLER_NONCE_PROHIBITED.

Balise::CREATION_DATETIME

Version: 1, 2, 3, 4

Répétable ? Non

Indique la date et l'heure de création de la clé, en millisecondes depuis le 1er janvier 1970. Cette balise est facultative et n'a qu'un but informatif.

Tag::DIGEST

Version : 1, 2, 3, 4

Répétable ? Oui

Spécifie les algorithmes de condensé pouvant être utilisés avec la clé pour effectuer des opérations de signature et de validation. Cette balise s'applique aux clés RSA, ECDSA et HMAC.

Les valeurs possibles sont définies par l'énumération suivante:

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 et versions antérieures 
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;

Cette balise est reproductible. Pour les opérations de signature et de validation, spécifiez un récapitulatif dans l'argument additionalParams de begin. Si le récapitulatif spécifié ne figure pas dans les récapitulatifs associés à la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_DIGEST.

Tag::EC_CURVE

Version : 2, 3, 4

Répétable ? Non

Dans Keymaster 1, la courbe utilisée pour les clés EC était devinée à partir de la taille de clé spécifiée. Pour améliorer la flexibilité à l'avenir, Keymaster 2 a introduit une méthode explicite pour spécifier des courbes. Les requêtes de génération de clés EC peuvent avoir Tag::EC_CURVE, Tag::KEY_SIZE ou les deux.

Les valeurs possibles sont définies par l'énumération suivante:

Keymaster 3 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
    P_521 = 3,
};
Keymaster 2 et versions antérieures 
enum class EcCurve : uint32_t {
    P_224 = 0,
    P_256 = 1,
    P_384 = 2,
P_521 = 3,
};

Si une requête de génération ne contient que Tag::KEY_SIZE, utilisez la logique Keymaster 1, en choisissant la courbe NIST appropriée.

Si la requête ne contient que Tag::EC_CURVE, utilisez la courbe spécifiée. Pour Keymaster 3 et versions ultérieures, les courbes sont définies dans EcCurve. Pour Keymaster 2 et versions antérieures, les courbes sont définies dans keymaster_ec_curve_t.

Si la requête contient les deux, utilisez la courbe spécifiée par Tag::EC_CURVE, puis vérifiez que la taille de clé spécifiée est approprié pour cette courbe. Sinon, renvoie ErrorCode::INVALID_ARGUMENT.

Balise::INCLUDE_UNIQUE_ID

Version: 2, 3, 4

Répétable ? Non

Cette balise est spécifiée lors de la génération de la clé pour indiquer qu'un certificat d'attestation pour la clé générée doit contenir un ID unique de l'appareil, limité dans le temps et défini par l'application, comme spécifié par Tag::UNIQUE_ID.

Cette balise est booléenne. Les valeurs possibles sont donc "true" (si la balise est présente) et "false" (si la balise n'est pas présente).

Tag::KEY_SIZE

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la taille, en bits, de la clé, mesurée de manière normale pour l'algorithme de la clé. Par exemple, pour des clés RSA, Tag::KEY_SIZE spécifie la taille du module public. Pour les clés AES, c’est la longueur du matériel de clé secrète.

Tag::MAC_LENGTH

Version : 1, 2, 3, 4

Répétable ? Non

Indique la longueur demandée d'une balise d'authentification MAC ou GCM, en bits.

La valeur est la longueur MAC en bits. Il s'agit d'un multiple de 8 et d'une valeur au moins aussi élevée que celle de Tag::MIN_MAC_LENGTH associée à la clé.

Tag::MAX_USES_PER_BOOT

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie le nombre maximal de fois qu'une clé peut être utilisée entre les redémarrages du système. Il s'agit d'un autre mécanisme permettant de limiter le débit d'utilisation des clés.

La valeur est un entier 32 bits représentant le nombre d'utilisations par démarrage.

Lorsqu'une clé avec cette balise est utilisée dans une opération, un compteur associé à la clé doit être incrémenté lors de l'appel begin. Après la clé a dépassé cette valeur, toutes les tentatives ultérieures d'utilisation de la clé échouent. avec ErrorCode::MAX_OPS_EXCEEDED, jusqu'à ce que l'appareil redémarre. Cela implique qu'un trustlet conserve une table des compteurs d'utilisation pour les clés comportant ce . Étant donné que la mémoire Keymaster est souvent limitée, cette table peut avoir une taille maximale fixe, et Keymaster peut échouer les opérations qui tentent d'utiliser des clés avec cette balise lorsque la table est pleine. La table doit contenir au moins 16 clés. Si une opération échoue parce que la table est pleine, Keymaster renvoie ErrorCode::TOO_MANY_OPERATIONS

Balise::MIN_MAC_LENGTH

Version : 1, 2, 3, 4

Répétable ? Non

Cette balise spécifie la longueur minimale du code MAC pouvant être demandée ou validée avec cette clé pour les clés HMAC et les clés AES compatibles avec le mode GCM.

Cette valeur correspond à la longueur MAC minimale, en bits. Il s'agit d'un multiple de 8. Pour les clés HMAC, la valeur est d'au moins 64. Pour les clés GCM, la valeur doit être d'au moins 96 et ne pas dépasser 128.

Tag::MIN_SECONDS_BETWEEN_OPS

Version : 1, 2, 3, 4

Répétable ? Non

Spécifie la durée minimale qui s'écoule entre les opérations autorisées à l'aide d'une clé. Cela peut être utilisé pour limiter la fréquence d'utilisation des clés dans des contextes où une utilisation illimitée pourrait permettre des attaques par force brute.

La valeur est un entier 32 bits représentant le nombre de secondes comprises entre opérations.

Lorsqu'une clé avec cette balise est utilisée dans une opération, démarrez un minuteur pendant l'appel finish (Terminer) ou abort (Abandonner). N'importe quelle valeur appeler begin qui est reçu avant le minuteur indique que l'intervalle spécifié par Le délai d'expiration de Tag::MIN_SECONDS_BETWEEN_OPS échoue avec ErrorCode::KEY_RATE_LIMIT_EXCEEDED Ce implique qu'un trustlet conserve une table des compteurs d'utilisation pour les clés comportant ce tag. La mémoire Keymaster étant souvent limitée, cette table peut avoir une valeur maximale fixe Keymaster et les opérations qui tentent d'utiliser des clés avec ce tag risquent d'échouer. lorsque la table est pleine. La table doit accueillir au moins 32 clés utilisées et réutiliser de manière agressive les emplacements de table lorsque les intervalles d'utilisation minimale des clés expirent. Si une opération échoue parce que la table est pleine, Keymaster renvoie ErrorCode::TOO_MANY_OPERATIONS

Tag::NO_AUTH_REQUIRED

Version : 1, 2, 3, 4

Répétable ? Non

Indique qu'aucune authentification n'est requise pour utiliser cette clé. Cette balise est mutuellement exclusive avec Tag::USER_SECURE_ID.

Cette balise est booléenne. Les valeurs possibles sont donc "true" (si la balise est présente) et "false" (si la balise n'est pas présente).

Tag::NONCE

Version: 1, 2, 3, 4

Répétable ? Non

Fournit ou renvoie un nonce ou un vecteur d'initialisation (IV) pour AES GCM, CBC, ou le déchiffrement ou le déchiffrement CTR. Cette balise est fournie pour démarrer pendant les opérations de chiffrement et de déchiffrement. Elle n'est fournie début si la clé comporte Tag::CALLER_NONCE. Si aucune valeur n'est fournie, un nonce ou un IV approprié est généré de manière aléatoire par Keymaster et renvoyé à partir de begin.

La valeur est un blob, un tableau d'octets de longueur arbitraire. Longueurs autorisées dépendent du mode: les nonces GCM ont une longueur de 12 octets. Le CBC et le CTR IV sont de 16 octets.

Tag::ORIGIN

Version: 1, 2, 3, 4

Répétable ? Non

Indique l'emplacement où la clé a été créée, le cas échéant. Impossible de spécifier cette balise lors de la génération ou de l'importation des clés, et doivent être ajoutées aux caractéristiques clés par le trustlet.

Keymaster 3

Les valeurs possibles sont définies dans android::hardware::keymaster::v3_0::KeyOrigin :

enum class KeyOrigin : uint32_t {
    GENERATED = 0,
    DERIVED = 1,
    IMPORTED = 2,
    UNKNOWN = 3,
};
Keymaster 2 et versions antérieures

Les valeurs possibles sont définies dans keymaster_origin_t :

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

La signification complète de la valeur dépend non seulement de la valeur, mais aussi de si il se trouve dans la liste des caractéristiques appliquées au matériel ou par logiciel.

GENERATED indique que Keymaster a généré la clé. Si elle figure dans la liste des clés appliquées par le matériel, la clé a été générée dans du matériel sécurisé et est définitivement liée au matériel. Si dans la liste appliquée par logiciel, la clé a été générée dans SoftKeymaster et n'est non lié au matériel.

DERIVED indique que la clé a été dérivée de Keymaster. Existe probablement en dehors de l'appareil.

IMPORTED indique que la clé a été générée en dehors de Keymaster et importée dans Keymaster. Si elle figure dans la liste des éléments appliqués par le matériel, elle est définitivement liée au matériel, même si des copies peuvent exister en dehors du matériel sécurisé. Si la clé figure dans la liste des applications logicielles, elle a été importée dans SoftKeymaster et n'est pas liée au matériel.

UNKNOWN ne doit apparaître que dans la liste appliquée par le matériel. Il indique que la clé est liée au matériel, mais on ne sait pas si elle a été générée à l'origine dans du matériel sécurisé ou si elle a été importée. Cela ne se produit que lorsque le matériel keymaster0 est utilisé pour émuler les services keymaster1.

Tag::ORIGINATION_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la date et l'heure auxquelles la clé expire à des fins de signature et de chiffrement. Passé ce délai, toute tentative d'utilisation d'une clé avec KeyUsage::SIGN ou KeyUsage::ENCRYPT fourni pour commencer échoue avec ErrorCode::KEY_EXPIRED.

La valeur est un entier de 64 bits représentant les millisecondes depuis 1er janvier 1970.

Balise::OS_PATCHLEVEL

Version : 2, 3, 4

Répétable ? Non

Cette balise n'est jamais envoyée au TA Keymaster, mais elle est ajoutée à la liste d'autorisation appliquée par le matériel par le TA.

La valeur de la balise est un entier au format AAAAMM, où AAAA est le année à quatre chiffres de la dernière mise à jour et MM est le mois à deux chiffres de la dernière mise à jour. Par exemple, pour une clé générée sur un appareil Android pour la dernière fois décembre 2015, la valeur est 201512.

Les clés dont le niveau de correctif est différent du niveau actuel utilisables. Tentative d'utilisation d'une cause clé de ce type commencer, getKeyCharacteristics, ou exportKey pour renvoyer ErrorCode::KEY_REQUIRES_UPGRADE. Pour en savoir plus, consultez la section Liaison de version.

Balise::OS_VERSION

Version : 2, 3, 4

Répétable ? Non

Ce tag n'est jamais envoyé au TA Keymaster, mais est ajouté au des autorisations matérielles par l’AT.

La valeur de la balise est un entier au format MMmmss, où MM correspond au numéro de version majeure, mm au numéro de version mineure et ss au numéro de version sous-mineur. Par exemple, pour une clé générée sur Android 4.0.3, la valeur est 040003.

Tag::PADDING

Version : 1, 2, 3, 4

Répétable ? Oui

Spécifie les modes de remplissage pouvant être utilisés avec la clé. Cette balise est pertinente pour les clés RSA et AES.

Les valeurs possibles sont définies par l'énumération suivante:

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 et versions antérieures 
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 et PaddingMode::RSA_PKCS1_1_5_ENCRYPT sont utilisés uniquement pour les clés de chiffrement/déchiffrement RSA et spécifiez RSA PKCS#1v2 OAEP le remplissage et le remplissage aléatoire RSA PKCS#1 v1.5, respectivement. PaddingMode::RSA_PSS et PaddingMode::RSA_PKCS1_1_5_SIGN ne sont utilisés que pour les clés de signature/validation RSA et spécifient respectivement le remplissage PSS RSA PKCS#1v2 et le remplissage déterministe RSA PKCS#1 v1.5.

PaddingMode::NONE peut être utilisé avec des clés RSA ou AES. Pour les clés AES, si PaddingMode::NONE est utilisé en mode bloc ECB ou CBC, et les données à chiffrer ou déchiffrer n'est pas un multiple de la taille du bloc AES, l'appel pour terminer échoue avec ErrorCode::INVALID_INPUT_LENGTH.

PaddingMode::PKCS7 ne peut être utilisé qu'avec des clés AES et uniquement avec les modes ECB et CBC.

Cette balise est reproductible. Un mode de remplissage doit être spécifié dans l'appel de commencer. Si le mode spécifié n'est pas autorisé pour la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_BLOCK_MODE.

Tag::PURPOSE

Version : 1, 2, 3, 4

Répétable ? Oui

Spécifie l'ensemble des objectifs pour lesquels la clé peut être utilisée.

Les valeurs possibles sont définies par l'énumération suivante :

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 et versions antérieures 
typedef enum {
    KM_PURPOSE_ENCRYPT = 0,
    KM_PURPOSE_DECRYPT = 1,
    KM_PURPOSE_SIGN = 2,
    KM_PURPOSE_VERIFY = 3,
} keymaster_purpose_t;

Cette balise est reproductible. Les clés peuvent être générées avec plusieurs valeurs, même si une opération n'a qu'un seul but. Lorsque begin s'appelle pour démarrer une opération, l'objectif de l'opération est spécifié. Si la finalité spécifiée pour l'opération n'est pas autorisée par le l'opération échoue avec une erreur ErrorCode::INCOMPATIBLE_PURPOSE.

Tag::RESET_SINCE_ID_ROTATION

Version: 3, 4

Répétable ? Non

Indique si la configuration d'usine de l'appareil a été rétablie depuis la dernière rotation des ID uniques. Utilisé pour l'attestation des clés.

Cette balise est booléenne. Les valeurs possibles sont donc "true" (si la balise est présente) et "false" (si la balise n'est pas présente).

Tag::ROLLBACK_RESISTANT

Version : 1, 2, 3, 4

Répétable ? Non

Indique que la clé est résistante au rollback, ce qui signifie que lorsqu'elle est supprimée par deleteKey ou deleteAllKeys, elle est définitivement supprimée et inutilisable. Il est possible que les clés sans cette balise peuvent être supprimées, puis restaurées à partir d'une sauvegarde.

Cette balise est booléenne. Les valeurs possibles sont donc "true" (si la balise est présente) et "false" (si la balise n'est pas présente).

Balise::ROOT_OF_TRUST

Version : 1, 2, 3, 4

Répétable ? Non

Spécifie la racine de confiance, la clé utilisée par le démarrage validé pour valider le système d'exploitation démarré (le cas échéant). Cette balise n'est jamais fournie. ou renvoyé par Keymaster dans les caractéristiques clés.

Tag::RSA_PUBLIC_EXPONENT

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la valeur de l'exposant public d'une paire de clés RSA. Ce tag est pertinent uniquement pour les clés RSA et nécessaire pour toutes les clés RSA.

La valeur est un entier non signé de 64 bits qui répond aux exigences d'un exposant public RSA. Cette valeur doit être un nombre premier. Les trustlets acceptent la valeur 2^16+1 et peuvent accepter d'autres valeurs raisonnables, en particulier la valeur 3. Si aucun exposant n'est spécifié ou si l'exposant spécifié n'est pas accepté, la génération de clés échoue avec ErrorCode::INVALID_ARGUMENT.

Tag::UNIQUE_ID

Version: 3, 4

Répétable ? Non

Permet de fournir un ID unique dans l'attestation.

La valeur est un blob, un tableau d'octets de longueur arbitraire.

Tag::USAGE_EXPIRE_DATETIME

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la date et l'heure d'expiration de la clé pour la vérification et de déchiffrement. Passé ce délai, toute tentative d'utilisation d'une clé avec KeyPurpose::VERIFY ou KeyPurpose::DECRYPT fournie pour débuter échoue avec ErrorCode::KEY_EXPIRED.

La valeur est un entier de 64 bits représentant les millisecondes écoulées depuis le 1er janvier 1970.

Balise::USER_AUTH_TYPE

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie les types d'authentificateurs utilisateur pouvant être utilisés pour autoriser cette clé. Lorsque Keymaster est invité à effectuer une opération avec une clé possédant ce un jeton d'authentification et son nom Le champ authenticator_type doit correspondre à la valeur de la balise. Par exemple, (ntoh(token.authenticator_type) & auth_type_tag_value) != 0, où ntoh est une fonction qui convertit les entiers ordonnés en réseau en entiers ordonnés par l'hôte et auth_type_tag_value est la valeur de cette balise.

La valeur est un masque de bits entier de 32 bits des valeurs de l'énumération :

Keymaster 3 
enum class HardwareAuthenticatorType : uint32_t {
    NONE = 0u, // 0
    PASSWORD = 1 << 0,
    FINGERPRINT = 1 << 1,
    ANY = UINT32_MAX,
};
Keymaster 2 et versions antérieures 
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

Répétable ? Oui

Indique qu'une clé ne peut être utilisée que par un utilisateur sécurisé spécifique l'état d'authentification. Cette balise s'exclut mutuellement avec Tag::NO_AUTH_REQUIRED.

La valeur est un entier de 64 bits spécifiant la valeur d'état de la règle d'authentification qui doit être présente dans un jeton d'authentification (fourni pour commencer par Tag::AUTH_TOKEN) pour autoriser l'utilisation de la clé. Tout appel à begin avec une clé associée à cette balise qui ne fournit pas de jeton d'authentification ou qui fournit un jeton d'authentification sans valeur d'état de règle correspondante échoue.

Cette balise est reproductible. Si l'une des valeurs fournies correspond à une valeur d'état de règle dans le jeton d'authentification, la clé est autorisée à être utilisée. Sinon, l'opération échoue avec ErrorCode::KEY_USER_NOT_AUTHENTICATED

Tag::VENDOR_PATCHLEVEL

Version : 4

Cette balise spécifie le niveau du correctif de sécurité de l'image du fournisseur avec lequel la clé peut être utilisée. Ce tag n'est jamais envoyé au TA Keymaster, mais est ajouté au des autorisations matérielles par l’AT. Toute tentative d'utilisation d'une clé avec Valeur de Tag::VENDOR_PATCHLEVEL différente de celle en cours d'exécution système Patchlevel doit provoquer begin(), getKeyCharacteristics() ou exportKey() pour renvoyer ErrorCode::KEY_REQUIRES_UPGRADE Voir upgradeKey() pour en savoir plus.

La valeur de la balise est un entier au format AAAAMMJJ, où AAAA correspond à l'année à quatre chiffres de la dernière mise à jour, MM correspond au mois à deux chiffres et JJ correspond au jour à deux chiffres de la dernière mise à jour. Par exemple, pour une clé générée sur un Dernière mise à jour de l'appareil Android le 5 juin 2018, la valeur serait 20180605.

Le HAL IKeymasterDevice doit lire le niveau de correctif actuel du fournisseur à partir du système. la propriété ro.vendor.build.security_patch et la transmettre au environnement sécurisé lors du premier chargement du HAL (le mécanisme est défini par l'implémentation). L'environnement sécurisé ne doit pas accepter un autre niveau de correctif avant le prochain démarrage.

Les règles s'appliquent au matériel.