Balises d'autorisation Keymaster

Cette page fournit des détails pour aider les implémenteurs des HAL Keymaster. Il couvre chaque balise du HAL, la version 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 clé pour spécifier les caractéristiques des clés.

Pour Keymaster 4, les balises sont définies dans platform/hardware/interfaces/keymaster/ keymaster-version /types.hal , telles que 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, consultez la page Fonctions Keymaster .

Balise ::ACTIVE_DATETIME

Versions : 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 de 64 bits représentant les millisecondes depuis le 1er janvier 1970.

Balise::ALGORITHME

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

Versions : 1, 2, 3, 4

Répétable ? Non

Réservé pour une utilisation future.

Étiquette ::ALLOW_WHILE_ON_BODY

Versions : 2, 3, 4

Répétable ? Non

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

Balise::ALL_USERS

Versions : 3, 4

Répétable ? Non

Réservé pour une utilisation future.

Balise ::APPLICATION_DATA

Versions : 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 pour commencer 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é cryptographiquement à la clé, ce qui signifie qu'il ne doit pas être possible pour un adversaire ayant accès à tous les secrets du monde sécurisé mais n'ayant 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

Versions : 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 pour commencer 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é cryptographiquement à la clé, 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

Versions : 1, 2, 3, 4

Répétable ? Non

Fournit des « données associées » pour le cryptage ou le déchiffrement AES-GCM. Cette balise est fournie pour mettre à jour et spécifie les données qui ne sont pas crypté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

Versions : 3, 4

Répétable ? Non

Utilisé pour identifier l'ensemble des applications possibles dont on a initié une attestation de clé.

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

Étiquette ::ATTESTATION_CHALLENGE

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

Versions : 3, 4

Répétable ? Non

Fournit le nom de marque de l’appareil, tel que renvoyé par Build.BRAND dans Android. Ce champ est renseigné uniquement 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 identifiants), toute demande 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_DEVICE

Versions : 3, 4

Répétable ? Non

Fournit le nom de l'appareil, tel que renvoyé par Build.DEVICE dans Android. Ce champ est renseigné uniquement 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 identifiants), toute demande 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_IMEI

Versions : 3, 4

Répétable ? Oui

Fournit les IMEI pour toutes les radios de l'appareil. Ce champ est renseigné uniquement 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 identifiants), toute demande 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.

Étiquette ::ATTESTATION_ID_MANUFACTURER

Versions : 3, 4

Répétable ? Non

Fournit le nom du fabricant de l’appareil, tel que renvoyé par Build.MANUFACTURER dans Android. Ce champ est renseigné uniquement 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 identifiants), toute demande 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

Versions : 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 identifiants), toute demande 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

Versions : 3, 4

Répétable ? Non

Fournit le nom du modèle de l’appareil, tel que renvoyé par Build.MODEL dans Android. Ce champ est renseigné uniquement 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 identifiants), toute demande 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_PRODUCT

Versions : 3, 4

Répétable ? Non

Fournit le nom du produit de l'appareil, tel que renvoyé par Build.PRODUCT dans Android. Ce champ est renseigné uniquement 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 identifiants), toute demande 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

Versions : 3, 4

Répétable ? Non

Fournit le numéro de série de l'appareil. Ce champ est renseigné uniquement 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 identifiants), toute demande 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

Versions : 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 authentification. Si Tag::USER_SECURE_ID est présent et que cette balise ne l'est pas, alors la clé nécessite une authentification pour chaque utilisation (voir début pour les détails du flux d'authentification par opération).

La valeur est un entier de 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 lequel la clé peut être utilisée.

Balise ::AUTH_TOKEN

Versions : 1, 2, 3, 4

Répétable ? Non

Fournit un jeton d'authentification pour commencer , mettre à jour ou terminer , 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

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

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 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 avant qu'une clé Keymaster ne soit utilisée pour déchiffrer le disque.

Balise::BLOCK_MODE

Versions : 1, 2, 3, 4

Répétable ? Oui

Spécifie le(s) mode(s) de chiffrement par bloc 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 :

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;

Cette balise est répétable et pour les opérations sur les touches AES, spécifiez un mode dans l'argument additionalParams de start . 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 balise n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations renforcé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 begin() , getKeyCharacteristics() ou exportKey() vers ErrorCode::KEY_REQUIRES_UPGRADE . Voir upgradeKey() pour plus de détails.

La valeur de la balise est un entier de la forme AAAAMMJJ, où AAAA est l'année à quatre chiffres de la dernière mise à jour, MM est le mois à deux chiffres et DD est le jour à deux chiffres de la dernière mise à jour. Par exemple, pour une clé générée sur un appareil Android mis à 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.

Étiquette ::BOOTLOADER_ONLY

Versions : 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 vraies (si la balise est présente) et fausses (si la balise n'est pas présente).

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

Étiquette ::CALLER_NONCE

Versions : 1, 2, 3, 4

Répétable ? Non

Spécifie que l'appelant peut fournir un nom occasionnel pour les opérations qui n'en nécessitent pas.

Cette balise est booléenne, donc les valeurs possibles sont vraies (si la balise est présente) et fausses (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

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

Étiquette ::DIGEST

Versions : 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 concerne les 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 vérification, spécifiez un résumé dans l'argument additionalParams de start . 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

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

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 contient uniquement Tag::KEY_SIZE , revenez à la logique Keymaster 1 en choisissant la courbe NIST appropriée.

Si la requête contient uniquement 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 et vérifiez que la taille de clé spécifiée est appropriée pour cette courbe. Sinon, renvoyez ErrorCode::INVALID_ARGUMENT .

Balise ::INCLUDE_UNIQUE_ID

Versions : 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 périphérique limité dans le temps et au niveau de l'application, comme spécifié par Tag::UNIQUE_ID .

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

Balise ::KEY_SIZE

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

Versions : 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. Il s'agit d'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

Versions : 1, 2, 3, 4

Répétable ? Non

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

La valeur est un entier de 32 bits représentant les 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 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'au redémarrage de l'appareil. Cela implique qu'un trustlet conserve une table des compteurs d'utilisation pour les clés avec cette balise. La mémoire Keymaster étant souvent limitée, cette table peut avoir une taille maximale fixe et Keymaster peut échouer aux 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

Versions : 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 AES prenant en charge le mode GCM.

Cette valeur correspond à 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

Versions : 1, 2, 3, 4

Répétable ? Non

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

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

Lorsqu'une clé avec cette balise est utilisée dans une opération, démarrez un minuteur pendant l'appel de fin ou d'abandon . Tout appel à commencer reçu avant le temporisateur 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 pour les clés avec cette balise. La mémoire Keymaster étant souvent limitée, cette table peut avoir une taille maximale fixe et Keymaster peut échouer aux opérations qui tentent d'utiliser des clés avec cette balise lorsque la table est pleine. La table doit accueillir au moins 32 clés en cours d'utilisation 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 .

Balise ::NO_AUTH_REQUIRED

Versions : 1, 2, 3, 4

Répétable ? Non

Spécifie qu'aucune authentification n'est requise pour utiliser cette clé. Cette balise s'exclut mutuellement avec Tag::USER_SECURE_ID .

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

Étiquette ::NONCE

Versions : 1, 2, 3, 4

Répétable ? Non

Fournit ou renvoie un nom occasionnel ou un vecteur d'initialisation (IV) pour le chiffrement ou le déchiffrement AES GCM, CBC ou CTR. Cette balise est prévue pour démarrer 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 un 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 noms occasionnels GCM ont une longueur de 12 octets ; Les CBC et CTR IV ont une longueur de 16 octets.

Étiquette ::ORIGINE

Versions : 1, 2, 3, 4

Répétable ? Non

Spécifie l'endroit 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 clé et doit être ajoutée aux caractéristiques de la clé par le trustlet.

Maître des clés 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 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 elle figure dans la liste matérielle, la clé a été générée sur un matériel sécurisé et est liée de manière permanente au matériel. Si elle figure 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 dans 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érielle, il est définitivement lié au matériel, bien que des copies en dehors du matériel sécurisé puissent exister. Si elle figure 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é initialement générée sur un matériel sécurisé ou si elle a été importée. Cela se produit uniquement lorsque le matériel keymaster0 est utilisé pour émuler les services keymaster1.

Balise ::ORIGINATION_EXPIRE_DATETIME

Versions : 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 de 64 bits représentant les millisecondes depuis le 1er janvier 1970.

Balise::OS_PATCHLEVEL

Versions : 2, 3, 4

Répétable ? Non

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

La valeur de la balise est un entier de la forme 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 mis à jour pour la dernière fois en décembre 2015, la valeur serait 201512.

Les clés dont le niveau de patch est différent du niveau de patch actuel ne sont pas utilisables. Une tentative d'utilisation d'une telle clé entraîne le renvoi debegin , getKeyCharacteristics ou exportKey d' ErrorCode::KEY_REQUIRES_UPGRADE . Voir Liaison de version pour plus de détails.

Balise ::OS_VERSION

Versions : 2, 3, 4

Répétable ? Non

Cette balise n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations renforcé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::REMPLAGE

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

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é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 des 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 taille du bloc AES en longueur, l'appel pour terminer échoue avec ErrorCode::INVALID_INPUT_LENGTH .

PaddingMode::PKCS7 ne peut être utilisé qu'avec les 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 à commencer . Si le mode spécifié n'est pas autorisé pour la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_BLOCK_MODE .

Balise::OBJECTIF

Versions : 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 répétable ; les clés peuvent être générées avec plusieurs valeurs, bien qu'une opération ait un seul objectif. Lorsque la fonction start est appelée pour démarrer une opération, le but de l’opération est spécifié. Si le but spécifié pour l'opération n'est pas autorisé par la clé, l'opération échoue avec ErrorCode::INCOMPATIBLE_PURPOSE .

Balise ::RESET_SINCE_ID_ROTATION

Versions : 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 vraies (si la balise est présente) et fausses (si la balise n'est pas présente).

Étiquette ::ROLLBACK_RESISTANT

Versions : 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 vraies (si la balise est présente) et fausses (si la balise n'est pas présente).

Balise ::ROOT_OF_TRUST

Versions : 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). Ce tag n'est jamais fourni ni renvoyé par Keymaster dans les caractéristiques clés.

Étiquette ::RSA_PUBLIC_EXPONENT

Versions : 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 concerne uniquement les clés RSA et est nécessaire pour toutes les clés RSA.

La valeur est un entier non signé de 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

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

Versions : 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 de 64 bits représentant les millisecondes depuis le 1er janvier 1970.

Balise ::USER_AUTH_TYPE

Versions : 1, 2, 3, 4

Répétable ? Non

Spécifie les types d'authentificateurs d'utilisateurs 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 de 32 bits contenant les 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

Versions : 1, 2, 3, 4

Répétable ? Non

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

La valeur est un entier de 64 bits spécifiant la valeur de l'état de la politique 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 pour commencer avec une clé avec cette balise qui ne fournit pas de jeton d'authentification, ou qui fournit un jeton d'authentification sans valeur d'état de stratégie correspondante, échoue.

Cette balise est reproductible. 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 .

Étiquette ::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 balise n'est jamais envoyée au keymaster TA, mais est ajoutée à la liste d'autorisations renforcé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 provoquer le renvoi begin() , getKeyCharacteristics() ou exportKey() vers ErrorCode::KEY_REQUIRES_UPGRADE . Voir upgradeKey() pour plus de détails.

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

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