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 <ph type="x-smartling-placeholder"></ph> 3.0/types.hal pour Keymaster 3 et <ph type="x-smartling-placeholder"></ph> 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.

Balise::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;

Balise::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.

Balise::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é. Dans en particulier, les appels à exportKey et getKeyCharacteristics devez fournir la même valeur au paramètre clientId, et les appels commencer à fournir cette balise et les mêmes données associées dans le cadre du inParams défini. 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.

Balise::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é. Dans en particulier, les appels à exportKey et getKeyCharacteristics devez fournir la même valeur dans le paramètre clientId. les appels pour commencer doivent ce tag et les mêmes données associées inParams défini. 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, c'est-à-dire un attaquant qui peut accéder à tous les secrets du monde sécurisés, mais n'a pas accès au contenu du tag et ne peut pas déchiffrer le (sans attaquer par force brute sur le contenu du tag).

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. Ce tag est fournis pour mettre à jour et spécifie les données qui ne sont pas chiffrées/déchiffrées, mais qui sont utilisées dans le calcul 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

Utilisé pour identifier l'ensemble des applications possibles dont une a initié 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

Indique la marque de l'appareil, telle que renvoyée par Build.BRAND. sur Android. Ce champ n'est défini que pour les demandes d'attestation les 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

Indique le nom de l'appareil, tel que renvoyé par Build.DEVICE. sur Android. Ce champ n'est défini que pour les demandes d'attestation les 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_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'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_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'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_MEID

Version: 3, 4

Répétable ? Oui

Fournit les MEID de toutes les radios de l'appareil. Ce champ ne sera défini lorsque vous demandez une 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_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'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_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 si demandant une 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_SERIAL

Version: 3, 4

Répétable ? Non

Fournit 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'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::AUTH_TIMEOUT

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la durée, en secondes, pendant laquelle l'utilisation de la clé est autorisée, après l'authentification unique. Si Tag::USER_SECURE_ID est présente et que ce tag ne l'est pas, la clé doit être authentifiée (consultez le début de la section du 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 à l'aide de 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 authentification jeton pour commencer, update ou finish, pour prouver l'authentification de l'utilisateur pour une opération de clé qui nécessite (la clé comporte Tag::USER_SECURE_ID).

La valeur est un blob qui contient une structure hw_auth_token_t.

Balise::BLOB_USAGE_REQUIREMENTS

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie les conditions d'environnement système nécessaires pour la génération à utiliser.

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;

Ce tag peut être spécifié 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. C'est essentiel pour les appareils avec des disques chiffrés, où le système de fichiers peut ne pas être disponible avant que après l'utilisation d'une clé Keymaster pour déchiffrer le disque.

Balise::BLOCK_MODE

Version: 1, 2, 3, 4

Répétable ? Oui

Spécifie le ou 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 se trouve pas dans l'un des modes associés à la touche, le paramètre é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 laquelle la clé peut être utilisée. Ce tag n'est jamais envoyé au TA Keymaster, mais est ajoutée à la liste des autorisations matériellement appliquées par les TA. Toute tentative visant à utilisez une clé dont la valeur Tag::BOOT_PATCHLEVEL est différente de celle au niveau du correctif système en cours d'exécution entraîne begin(), getKeyCharacteristics() ou exportKey() pour renvoyer ErrorCode::KEY_REQUIRES_UPGRADE Voir upgradeKey() pour en savoir plus.

La valeur de la balise est un nombre entier au format AAAAMMJJ, où AAAA est le 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, 00 peut être remplacé.

À 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

Indique 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 ne concerne que les indicateurs CBC, CTR et GCM. en mode bloc. En l'absence de balise, l'implémentation doit refuser toute opération qui fournit Tag::NONCE à début 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 1er janvier 1970. Cette balise est facultative et n'est fournie qu'à titre d'information.

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 de signature et de validation. Ce tag est pertinent pour RSA, ECDSA et clés 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, indiquez un condensé dans l'argument additionalParams de commencer. Si le condensé spécifié ne figure pas dans les condensés associés à la clé, la é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 était devinée à partir de la clé spécifiée. la taille de l'image. Pour améliorer la flexibilité à l'avenir, Keymaster 2 a introduit un modèle explicite de spécifier des courbes. Les demandes de génération de clés pour le suivi avancé des conversions 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, la logique Keymaster 1 en choisissant la courbe NIST appropriée.

Si la requête ne contient que Tag::EC_CURVE, utilisez la méthode la courbe spécifiée. Dans Keymaster 3 et versions ultérieures, les courbes sont définies EcCurve Dans Keymaster 2 et les 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, renvoyez ErrorCode::INVALID_ARGUMENT

Balise::INCLUDE_UNIQUE_ID

Version: 2, 3, 4

Répétable ? Non

Ce tag est spécifié lors de la génération de la clé pour indiquer qu'une attestation pour la clé générée doit contenir un certificat à l'échelle de l'application un identifiant unique d'appareil limité dans le temps, comme spécifié par Tag::UNIQUE_ID.

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

Balise::KEY_SIZE

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la taille, en bits, de la clé, mesurée de la manière normale pour la 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.

Balise::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. C'est un multiple de 8 et à au moins égal à la valeur de Tag::MIN_MAC_LENGTH associées à la clé.

Balise::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 des redémarre. Il s'agit d'un autre mécanisme permettant de limiter le débit des clés.

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

Lorsqu'une clé associée à ce tag est utilisée dans une opération, un compteur associé à une clé doit être incrémentée pendant commencer l'appel. 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 . La mémoire Keymaster étant souvent limitée, cette table peut avoir un nombre fixe de taille maximale et les opérations Keymaster qui tentent d'utiliser des clés avec ce tag 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 des adresses MAC pouvant être demandées ou validées avec cette clé pour les clés HMAC et AES prenant en charge le mode GCM.

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

Balise::MIN_SECONDS_BETWEEN_OPS

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la durée minimale qui s'écoule entre à l'aide d'une clé. Cela peut être utilisé pour limiter le débit d'utilisation 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 le nombre de secondes comprises entre opérations.

Lorsqu'une clé associée à cette balise est utilisée dans une opération, démarrer un minuteur pendant la phase finish ou annuler l'appel. 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 pouvoir accueillir au moins 32 instances en cours d'utilisation et réutilisent 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

Balise::NO_AUTH_REQUIRED

Version: 1, 2, 3, 4

Répétable ? Non

Indique qu'aucune authentification n'est requise pour utiliser cette clé. Ce tag est s'excluent mutuellement avec Tag::USER_SECURE_ID.

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

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. Ce tag est fourni à début pendant les opérations de chiffrement et de déchiffrement. Il n'est fourni début si la clé comporte Tag::CALLER_NONCE. Si aucune valeur n'est fournie, un nonce ou un vecteur d'initialisation approprié est généré de manière aléatoire Keymaster et est renvoyé depuis le début.

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, si vous le connaissez. Cette balise n'est peut-être pas spécifiée. 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 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 dans la liste des contraintes matérielles, la clé a été générée dans du matériel sécurisé et est liée au matériel de manière permanente. 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 hors de l'appareil.

IMPORTED indique que la clé a été générée en dehors de Keymaster et importé dans Keymaster. Si dans la liste des contraintes matérielles, il s'agit d'un élément lié au matériel de manière permanente, bien que des copies en dehors du matériel sécurisé puissent exister. Si la valeur logiciel-enforce, la clé a été importée dans SoftKeymaster et n'est pas lié au matériel.

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

Balise::ORIGINATION_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 signature et à des fins de chiffrement. Passé ce délai, toute tentative d'utilisation d'une clé avec KeyGoal::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

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 nombre 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 de correctif actuel ne sont pas utilisables. Tentative d'utilisation d'une cause clé de ce type commencer, getKeyCharacteristics, ou exportKey pour renvoyer ErrorCode::KEY_REQUIRES_UPGRADE. Voir la liaison de version plus de détails.

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 nombre entier au format MMmmss, où MM est le nombre majeur numéro de version, mm est le numéro de version mineure et ss est la version de correction numéro. Par exemple, pour une clé générée sous Android version 4.0.3, la valeur est 040003.

Balise::PADDING

Version: 1, 2, 3, 4

Répétable ? Oui

Spécifie les modes de marge intérieure pouvant être utilisés avec la clé. Ce tag est pertinentes 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 Les PaddingMode::RSA_PKCS1_1_5_SIGN ne sont utilisés que pour les ARR. de signature et de validation, et spécifiez RSA PKCS#1v2 PSS et le remplissage déterministe RSA PKCS#1 v1.5, respectivement.

PaddingMode::NONE peut être utilisé avec des annonces responsives sur le Réseau de Recherche ou clés 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. qu'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.

Balise::PURPOSE

Version: 1, 2, 3, 4

Répétable ? Oui

Spécifie l'ensemble des finalités pour lesquelles 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 : peuvent être générées avec plusieurs valeurs, bien qu'une opération ait un seul objectif. 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.

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

Balise::ROLLBACK_RESISTANT

Version: 1, 2, 3, 4

Répétable ? Non

Indique que la clé est résistante aux rollbacks, ce qui signifie que lorsqu'elle est supprimée à l'aide de la commande deleteKey ou deleteAllKeys, la clé sera définitivement supprimée et inutilisable. Il est possible que les clés sans cette balise pourraient être supprimées, puis restaurées à partir de la sauvegarde.

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

Balise::ROOT_OF_TRUST

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la racine de confiance, c'est-à-dire 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.

Balise::RSA_PUBLIC_EXPONENT

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie la valeur de l'exposant public pour une paire de clés RSA. Ce tag est pertinentes uniquement pour les clés RSA et nécessaires 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 sont compatibles avec 2^16+1. D'autres valeurs raisonnables peuvent également être acceptées, 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

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 KeyUsage::VERIFY ou KeyUsage::DECRYPT fourni à Échec du début avec ErrorCode::KEY_EXPIRED.

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

Balise::USER_AUTH_TYPE

Version: 1, 2, 3, 4

Répétable ? Non

Spécifie les types d'authentificateurs d'utilisateur pouvant être utilisés pour autoriser cet accès . 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 sur 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 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;

Balise::USER_SECURE_ID

Version: 1, 2, 3, 4

Répétable ? Non

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

La valeur est un entier de 64 bits qui spécifie l'é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é. N'importe quelle valeur appeler pour begin avec une clé associée à ce tag qui ne fournit pas d'authentification unique ou fournit le jeton d'authentification sans valeur d'état de règle correspondante échoue.

Cette balise est reproductible. Si l'une des valeurs fournies correspond à une règle d'état 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

Ce tag spécifie le niveau du correctif de sécurité de l'image du fournisseur avec lequel la clé peuvent être utilisées. 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 nombre entier au format AAAAMMJJ, où AAAA est le 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 "patchlevel" jusqu'au prochain démarrage.

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