Balises d'autorisation Keymaster

Cette page fournit des détails pour aider les implémenteurs de Keymaster HAL. Il couvre chaque balise de la HAL, la version de Keymaster dans laquelle cette balise est disponible et si la balise est répétable. Sauf indication contraire dans les descriptions des balises, toutes les balises ci-dessous sont utilisées lors de la génération de la clé pour spécifier les caractéristiques de la clé.

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

Pour les fonctions, voir la page Fonctions Keymaster .

Balise ::ACTIVE_DATETIME

Variantes : 1, 2, 3, 4

Répétable ? Non

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

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

Balise::ALGORITHME

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

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

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

Balise :: TOUTES_APPLICATIONS

Variantes : 1, 2, 3, 4

Répétable ? Non

Réservé pour une utilisation future.

Balise ::ALLOW_WHILE_ON_BODY

Version : 2, 3, 4

Répétable ? Non

Cette balise s'applique uniquement aux appareils Android Wear dotés de capteurs intégrés. À ce stade, on ne s'attend pas à ce qu'un TEE soit en mesure de fournir un accès sécurisé à un capteur sur le corps, ou que les capteurs sur le corps soient très sécurisés, il devrait donc s'agir d'une fonctionnalité purement logicielle.

Balise ::ALL_USERS

Version : 3, 4

Répétable ? Non

Réservé pour une utilisation future.

Balise ::APPLICATION_DATA

Variantes : 1, 2, 3, 4

Répétable ? Non

Lorsqu'elle est fournie à generateKey ou importKey , cette balise spécifie les données nécessaires lors de 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 le cadre de 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'il ne doit pas être possible pour un adversaire qui a accès à tous les secrets du monde sécurisé mais n'a pas accès au contenu de la balise de déchiffrer la clé sans forcer brutalement la balise contenu, que les applications peuvent empêcher en spécifiant un contenu à entropie suffisamment élevée.

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

Balise ::APPLICATION_ID

Variantes : 1, 2, 3, 4

Répétable ? Non

Lorsqu'elle est fournie à generateKey ou importKey , cette balise spécifie les données nécessaires lors de 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 le cadre de 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 adversaire qui peut accéder à tous les secrets du monde sécurisé, mais n'a pas accès au contenu de la balise, ne peut pas déchiffrer la clé (sans forcer brutalement le contenu de la balise ).

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

Balise ::ASSOCIATED_DATA

Variantes : 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écifier des données qui ne sont pas chiffrées/déchiffrées, mais qui sont utilisées dans le calcul de 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 on a initié une attestation 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 un défi 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 marque de l'appareil, tel qu'il est renvoyé par Build.BRAND dans Android. Ce champ est défini uniquement lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut cette balise échoue avec 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 de l'appareil, tel qu'il est renvoyé par Build.DEVICE dans Android. Ce champ est défini uniquement lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS .

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

Balise ::ATTESTATION_ID_IMEI

Version : 3, 4

Répétable ? Oui

Fournit les IMEI pour toutes les radios de l'appareil. Ce champ est défini uniquement lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS .

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

Balise :: ATTESTATION_ID_MANUFACTURER

Version : 3, 4

Répétable ? Non

Fournit le nom du fabricant de l'appareil, tel qu'il est renvoyé par Build.MANUFACTURER dans Android. Ce champ est défini uniquement lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut 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 pour toutes les radios de l'appareil. Ce champ ne sera renseigné que lors d'une demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut 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

Fournit le nom du modèle de l'appareil, tel qu'il est renvoyé par Build.MODEL dans Android. Ce champ est défini uniquement lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS .

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

Balise ::ATTESTATION_ID_PRODUCT

Version : 3, 4

Répétable ? Non

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

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut 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

Fournit le numéro de série de l'appareil. Ce champ est défini uniquement lors de la demande d'attestation des identifiants de l'appareil.

Si l'appareil ne prend pas en charge l'attestation d'ID (ou si destroyAttestationIds() a été précédemment appelé et que l'appareil ne peut plus attester ses ID), toute demande d'attestation de clé qui inclut cette balise échoue avec ErrorCode::CANNOT_ATTEST_IDS .

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

Balise ::AUTH_TIMEOUT

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie la durée en secondes pendant laquelle la clé est autorisée à être utilisée, après authentification. Si Tag::USER_SECURE_ID est présent et que ce tag ne l'est pas, alors la clé doit être authentifiée pour chaque utilisation (voir begin pour les détails du flux d'authentification par opération).

La valeur est un entier 32 bits spécifiant le temps en secondes après une authentification réussie de l'utilisateur spécifié par Tag::USER_SECURE_ID avec la méthode d'authentification spécifiée par Tag::USER_AUTH_TYPE pendant laquelle la clé peut être utilisée.

Balise ::AUTH_TOKEN

Variantes : 1, 2, 3, 4

Répétable ? Non

Fournit un jeton d'authentification pour begin , update ou finish , afin de prouver l'authentification de l'utilisateur pour une opération de clé qui l'exige (la clé a Tag::USER_SECURE_ID ).

La valeur est un blob qui contient une structure hw_auth_token_t .

Balise ::BLOB_USAGE_REQUIREMENTS

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie les conditions d'environnement système nécessaires pour que la clé générée soit utilisée.

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

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

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

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 les caractéristiques clés de generateKey et getKeyCharacteristics . Si l'appelant spécifie Tag::BLOB_USAGE_REQUIREMENTS avec la valeur KeyBlobUsageRequirements::STANDALONE le trustlet renvoie un blob de clé qui peut être utilisé sans prise en charge du système de fichiers. Ceci est essentiel pour les appareils dotés de disques chiffrés, où le système de fichiers peut ne pas être disponible tant qu'une clé Keymaster n'a pas été utilisée pour déchiffrer le disque.

Balise::BLOCK_MODE

Variantes : 1, 2, 3, 4

Répétable ? Oui

Spécifie le ou les modes de chiffrement par blocs avec lesquels la clé peut être utilisée. Cette balise ne concerne que les clés AES.

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

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

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

Cette balise est répétable et, pour les opérations sur les touches AES, spécifiez un mode dans l'argument additionalParams de begin . Si le mode spécifié n'est pas dans 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 de correctif de sécurité de l'image de démarrage (noyau) avec lequel la clé peut être utilisée. Cette étiquette n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations imposées par le matériel par le 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 retour begin() , getKeyCharacteristics() ou exportKey() ErrorCode::KEY_REQUIRES_UPGRADE . Voir upgradeKey() pour plus de détails.

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

Lors de chaque démarrage, le chargeur de démarrage 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).

Doit être appliqué par le matériel.

Balise ::BOOTLOADER_ONLY

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie que seul le chargeur de démarrage peut utiliser la clé.

Cette balise est booléenne, donc 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 depuis le système Android échoue avec ErrorCode::INVALID_KEY_BLOB .

Balise::CALLER_NONCE

Variantes : 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 est booléenne, donc les valeurs possibles sont true (si la balise est présente) et false (si la balise n'est pas présente).

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

Balise :: CREATION_DATETIME

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie la date et l'heure de création de la clé, en millisecondes depuis le 1er janvier 1970. Cette balise est facultative et informative uniquement.

Balise :: DIGEST

Variantes : 1, 2, 3, 4

Répétable ? Oui

Spécifie les algorithmes de résumé qui peuvent être utilisés avec la clé pour effectuer des opérations de signature et de vérification. Cette balise est pertinente pour les clés RSA, ECDSA et HMAC.

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

enum class Digest : uint32_t {
    NONE = 0,
    MD5 = 1,
    SHA1 = 2,
    SHA_2_224 = 3,
    SHA_2_256 = 4,
    SHA_2_384 = 5,
    SHA_2_512 = 6,
};

typedef enum {
    KM_DIGEST_NONE = 0,
    KM_DIGEST_MD5 = 1,
    KM_DIGEST_SHA1 = 2,
    KM_DIGEST_SHA_2_224 = 3,
    KM_DIGEST_SHA_2_256 = 4,
    KM_DIGEST_SHA_2_384 = 5,
    KM_DIGEST_SHA_2_512 = 6,
}
keymaster_digest_t;

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

Balise::EC_CURVE

Version : 2, 3, 4

Répétable ? Non

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

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

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

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

Si une requête de génération ne contient que Tag::KEY_SIZE , revenez à 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 demande contient les deux, utilisez la courbe spécifiée par Tag::EC_CURVE et validez que la taille de clé spécifiée est appropriée pour cette courbe. Si ce n'est pas le cas, renvoyez 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 clé pour indiquer qu'un certificat d'attestation pour la clé générée doit contenir un ID unique d'appareil limité à l'application et limité dans le temps, comme spécifié par Tag::UNIQUE_ID .

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

Balise ::KEY_SIZE

Variantes : 1, 2, 3, 4

Répétable ? Non

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

Balise ::MAC_LENGTH

Variantes : 1, 2, 3, 4

Répétable ? Non

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

La valeur est la longueur MAC en bits. C'est un multiple de 8 et au moins aussi grand que la valeur de Tag::MIN_MAC_LENGTH associée à la clé.

Balise ::MAX_USES_PER_BOOT

Variantes : 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 pour limiter l'utilisation des clés.

La valeur est un entier 32 bits représentant les utilisations par démarrage.

Lorsqu'une clé avec cette étiquette est utilisée dans une opération, un compteur associé à une clé doit être incrémenté pendant l'appel de début . Une fois que le compteur de 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 soit redémarré. Cela implique qu'un trustlet conserve une table des compteurs d'utilisation des clés avec cette balise. Étant donné que la mémoire Keymaster est souvent limitée, cette table peut avoir une taille maximale fixe et Keymaster peut faire échouer les opérations qui tentent d'utiliser des clés avec cette balise lorsque la table est pleine. La table doit accueillir 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

Variantes : 1, 2, 3, 4

Répétable ? Non

Cette balise spécifie la longueur minimale de MAC qui peut être demandée ou vérifiée avec cette clé pour les clés HMAC et les clés AES prenant en charge le mode GCM.

Cette valeur est la longueur MAC minimale, en bits. C'est un multiple de 8. Pour les clés HMAC, la valeur est d'au moins 64. Pour les clés GCM, la valeur est d'au moins 96 et pas plus de 128.

Balise ::MIN_SECONDS_BETWEEN_OPS

Variantes : 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 les utilisations des clés dans des contextes où une utilisation illimitée peut permettre des attaques par force brute.

La valeur est un entier 32 bits représentant les secondes entre les opérations autorisées.

Lorsqu'une touche avec cette étiquette est utilisée dans une opération, démarre une minuterie pendant l'appel de fin ou d'abandon . Tout appel à commencer reçu avant le minuteur indique que l'intervalle spécifié par Tag::MIN_SECONDS_BETWEEN_OPS s'est écoulé échoue avec ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Cela implique qu'un trustlet conserve une table des compteurs d'utilisation des clés avec cette balise. Étant donné que la mémoire Keymaster est souvent limitée, cette table peut avoir une taille maximale fixe et Keymaster peut faire é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 32 clés en cours d'utilisation et réutiliser agressivement 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 .

Balise ::NO_AUTH_REQUIRED

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie 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, donc les valeurs possibles sont true (si la balise est présente) et false (si la balise n'est pas présente).

Tag::NONCE

Variantes : 1, 2, 3, 4

Répétable ? Non

Fournit ou renvoie un nonce ou un vecteur d'initialisation (IV) pour le chiffrement ou le déchiffrement AES GCM, CBC ou CTR. Cette balise est fournie pour commencer lors des opérations de chiffrement et de déchiffrement. Il n'est fourni pour commencer que si la clé a Tag::CALLER_NONCE . S'il n'est pas fourni, un nonce ou IV approprié sera généré aléatoirement par Keymaster et renvoyé depuis le début.

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

Balise::ORIGINE

Variantes : 1, 2, 3, 4

Répétable ? Non

Indique où la clé a été créée, si elle est connue. Cette balise ne peut pas être spécifiée lors de la génération ou de l'importation de la clé et doit être ajoutée aux caractéristiques de la clé par le trustlet.

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

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 du fait qu'elle se trouve dans la liste des caractéristiques appliquées par le matériel ou par le logiciel.

GENERATED indique que Keymaster a généré la clé. Si dans la liste matérielle appliquée, la clé a été générée dans un 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 pas liée au matériel.

DERIVED indique que la clé a été dérivée à l'intérieur de Keymaster. Existe probablement hors appareil.

IMPORTED indique que la clé a été générée en dehors de Keymaster et importée dans Keymaster. S'il figure dans la liste matériellement appliquée, il est définitivement lié au matériel, bien que des copies en dehors du matériel sécurisé puissent exister. Si dans la liste des applications logicielles, la clé a été importée dans SoftKeymaster et n'est pas liée au matériel.

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

Balise ::ORIGINATION_EXPIRE_DATETIME

Variantes : 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 KeyPurpose::SIGN ou KeyPurpose::ENCRYPT fournie pour commencer échoue avec ErrorCode::KEY_EXPIRED .

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

Balise ::OS_PATCHLEVEL

Version : 2, 3, 4

Répétable ? Non

Cette étiquette n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations imposées par le matériel par le TA.

La valeur de la balise est un entier au format AAAAMM, où AAAA est l'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 mise à jour pour la dernière fois en décembre 2015, la valeur serait 201512.

Les touches qui ont un niveau de patch différent du niveau de patch actuel ne sont pas utilisables. Une tentative d'utilisation d'une telle clé fait que begin , getKeyCharacteristics ou exportKey renvoie ErrorCode::KEY_REQUIRES_UPGRADE . Voir Liaison de version pour plus de détails.

Balise ::OS_VERSION

Version : 2, 3, 4

Répétable ? Non

Cette étiquette n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations imposées par le matériel par le TA.

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

Balise :: REMBOURRAGE

Variantes : 1, 2, 3, 4

Répétable ? Oui

Spécifie les modes de remplissage qui peuvent être utilisés avec la clé. Cette balise concerne les clés RSA et AES.

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

enum class PaddingMode : uint32_t {
    NONE = 1,
    RSA_OAEP = 2,
    RSA_PSS = 3,
    RSA_PKCS1_1_5_ENCRYPT = 4,
    RSA_PKCS1_1_5_SIGN = 5,
    PKCS7 = 64,
};

typedef enum {
    KM_PAD_NONE = 1,
    KM_PAD_RSA_OAEP = 2,
    KM_PAD_RSA_PSS = 3,
    KM_PAD_RSA_PKCS1_1_5_ENCRYPT = 4,
    KM_PAD_RSA_PKCS1_1_5_SIGN = 5,
    KM_PAD_PKCS7 = 64,
} keymaster_padding_t;

PaddingMode::RSA_OAEP et PaddingMode::RSA_PKCS1_1_5_ENCRYPT sont utilisés uniquement pour les clés de chiffrement/déchiffrement RSA et spécifient respectivement le remplissage RSA PKCS#1v2 OAEP et le remplissage aléatoire RSA PKCS#1 v1.5. PaddingMode::RSA_PSS et PaddingMode::RSA_PKCS1_1_5_SIGN sont utilisés uniquement pour les clés de signature/vérification 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 les clés RSA ou AES. Pour les clés AES, si PaddingMode::NONE est utilisé avec le mode bloc ECB ou CBC et que les données à chiffrer ou à déchiffrer ne sont pas un multiple de la longueur du bloc AES, l'appel à 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 répétable. Un mode de remplissage doit être spécifié dans l'appel à begin . Si le mode spécifié n'est pas autorisé pour la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Balise :: BUT

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

enum class KeyPurpose : uint32_t {
    ENCRYPT = 0,
    DECRYPT = 1,
    SIGN = 2,
    VERIFY = 3,
    DERIVE_KEY = 4,  // since 3.0
    WRAP_KEY = 5,    // since 3.0
};

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

Cette balise est répétable ; les clés peuvent être générées avec plusieurs valeurs, bien qu'une opération ait un seul but. Lorsque la fonction begin est appelée pour démarrer une opération, le but de l'opération est spécifié. Si le but spécifié à l'opération n'est pas autorisé par la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_PURPOSE .

Balise ::RESET_SINCE_ID_ROTATION

Version : 3, 4

Répétable ? Non

Spécifie si l'appareil a été réinitialisé aux paramètres d'usine depuis la dernière rotation d'ID unique. Utilisé pour l'attestation de clé.

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

Balise :: ROLLBACK_RESISTANT

Variantes : 1, 2, 3, 4

Répétable ? Non

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

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

Balise :: ROOT_OF_TRUST

Variantes : 1, 2, 3, 4

Répétable ? Non

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

Balise ::RSA_PUBLIC_EXPONENT

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie la valeur de l'exposant public pour une paire de clés RSA. Cette balise ne concerne que les clés RSA et est nécessaire pour toutes les clés RSA.

La valeur est un entier non signé 64 bits qui satisfait aux exigences d'un exposant public RSA. Cette valeur doit être un nombre premier. Les trustlets prennent en charge la valeur 2^16+1 et peuvent prendre en charge 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 pris en charge, la génération de clé échoue avec ErrorCode::INVALID_ARGUMENT .

Balise :: UNIQUE_ID

Version : 3, 4

Répétable ? Non

Utilisé pour fournir un identifiant unique dans l'attestation.

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

Balise ::USAGE_EXPIRE_DATETIME

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie la date et l'heure auxquelles la clé expire à des fins de 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 commencer échoue avec ErrorCode::KEY_EXPIRED .

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

Balise ::USER_AUTH_TYPE

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie les types d'authentificateurs d'utilisateur qui peuvent être utilisés pour autoriser cette clé. Lorsque Keymaster est invité à effectuer une opération avec une clé avec cette balise, il reçoit un jeton d'authentification et le champ authenticator_type du jeton 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 par le 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 32 bits de valeurs de l'énumération :

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

typedef enum {
    HW_AUTH_NONE = 0,
    HW_AUTH_PASSWORD = 1 << 0,
    HW_AUTH_FINGERPRINT = 1 << 1,
    // Additional entries should be powers of 2.
    HW_AUTH_ANY = UINT32_MAX,
} hw_authenticator_type_t;

Balise ::USER_SECURE_ID

Variantes : 1, 2, 3, 4

Répétable ? Non

Spécifie qu'une clé ne peut être utilisée que dans un état d'authentification d'utilisateur sécurisé particulier. Cette balise est mutuellement exclusive avec Tag::NO_AUTH_REQUIRED .

La valeur est un entier 64 bits spécifiant la valeur d'état de la politique d'authentification qui doit être présente dans un jeton d'authentification (fourni pour commencer par le Tag::AUTH_TOKEN ) pour autoriser l'utilisation de la clé. Tout appel commençant par une clé avec cette balise qui ne fournit pas de jeton d'authentification, ou fournit un jeton d'authentification sans valeur d'état de stratégie correspondante, échoue.

Cette balise est répétable. Si l'une des valeurs fournies correspond à une valeur d'état de stratégie dans le jeton d'authentification, l'utilisation de la clé est autorisée. Sinon, l'opération échoue avec ErrorCode::KEY_USER_NOT_AUTHENTICATED .

Balise ::VENDOR_PATCHLEVEL

Version : 4

Cette balise spécifie le niveau de correctif de sécurité de l'image du fournisseur avec lequel la clé peut être utilisée. Cette étiquette n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations imposées par le matériel par le TA. Toute tentative d'utilisation d'une clé avec une valeur Tag::VENDOR_PATCHLEVEL différente du niveau de correctif du système en cours d'exécution doit entraîner le retour begin() , getKeyCharacteristics() ou exportKey() ErrorCode::KEY_REQUIRES_UPGRADE . Voir upgradeKey() pour plus de détails.

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

Le IKeymasterDevice HAL doit lire le niveau de correctif du fournisseur actuel à partir de la propriété système ro.vendor.build.security_patch et le livrer à l'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.

Doit être appliqué par le matériel.