Cette page fournit des informations pour aider les développeurs à implémenter des HAL Keymaster. Il couvre chaque balise du HAL, la version Keymaster de ce tag disponible. et si le tag est reproductible. Sauf indication contraire dans les descriptions des tags, tous les tags ci-dessous sont utilisés lors de la génération de la clé pour spécifier la caractéristiques.
Pour Keymaster 4, les balises sont définies
platform/hardware/interfaces/keymaster/keymaster-version/types.hal,
tels que
3.0/types.hal pour Keymaster 3 et
<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 du 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é de 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 3Les 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
KeyUsage::SIGN ou
KeyUsage::ENCRYPT fourni
pour commencer échoue
avec ErrorCode::KEY_EXPIRED.
La valeur est un entier de 64 bits représentant les millisecondes depuis 1er janvier 1970.
Balise::OS_PATCHLEVEL
Version: 2, 3, 4
Répétable ? Non
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 le TA.
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 marge intérieure 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 l'objectif spécifié pour l'opération n'est pas autorisé 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 peuvent être supprimées, puis restaurées à partir d'une 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 correspondant aux 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 ? Oui
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.