Documentation de référence sur la struct keymaster2_device

Arrête une opération de chiffrement commencée avec begin() , libérant toutes les ressources internes et invalidant operation_handle .

Définition à la ligne 415 du fichier keymaster2.h .

Ajoute de l'entropie au générateur de nombres aléatoires utilisé par Keymaster. L'entropie ajoutée via cette méthode ne sera jamais la seule source d'entropie utilisée. La fonction de mélange doit être sécurisée, c'est-à-dire que si le générateur de nombres aléatoires est initialisé (à partir de n'importe quelle source) avec des données que l'attaquant ne peut pas prédire (ou contrôler), la sortie du générateur de nombres aléatoires est indiscernable de la distribution aléatoire. Par conséquent, si l'entropie de n'importe quelle source est bonne, la sortie sera bonne.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	de données	Données aléatoires à mélanger.
[in]	data_length	Longueur de data .

Définition à la ligne  74 du fichier keymaster2.h .

Génère une chaîne de certificats X.509 signée attestant de la présence de key_to_attest dans Keymaster (À FAIRE(swillden): décrire plus en détail le contenu du certificat). Le certificat contiendra une extension avec l'OID 1.3.6.1.4.1.11129.2.1.17 et la valeur définie dans <TODO:swillden – insert link here>, qui contient la description de la clé.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	key_to_attest	Clé Keymaster pour laquelle le certificat d'attestation sera généré.
[in]	attest_params	Paramètres définissant la méthode d'attestation. Pour le moment, le seul paramètre est KM_TAG_ALGORITHM, qui doit être KM_ALGORITHM_EC ou KM_ALGORITHM_RSA. Cette valeur permet de sélectionner la clé d'attestation provisionnée qui sera utilisée pour signer le certificat.
[out]	cert_chain	Tableau de certificats X.509 encodés DER. Le premier est le certificat pour key_to_attest . Les entrées restantes seront enchaînées à la racine. L'appelant s'approprie la chaîne et doit la libérer avec keymaster_free_cert_chain.

Définition à la ligne  239 du fichier keymaster2.h .

Démarre une opération de cryptographie à l'aide de la clé spécifiée. Si tout va bien, begin() renvoie KM_ERROR_OK et crée un handle d'opération qui doit être transmis aux appels ultérieurs de update() , finish() ou abort() .

Il est essentiel que chaque appel à begin() soit associé à un appel ultérieur à finish() ou abort() , afin de permettre à l'implémentation de Keymaster de nettoyer tout état d'opération interne. Si vous ne le faites pas, vous risquez de provoquer une fuite d'espace d'état interne ou d'autres ressources internes, et begin() peut finir par renvoyer KM_ERROR_TOO_MANY_OPERATIONS lorsqu'il n'a plus d'espace pour les opérations. Tout résultat autre que KM_ERROR_OK de begin() , update() ou finish() met implicitement fin à l'opération. Dans ce cas, abort() n'a pas besoin d'être appelé (et renvoie KM_ERROR_INVALID_OPERATION_HANDLE s'il est appelé).

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	objectif	But de l'opération, parmi les valeurs KM_PURPOSE_ENCRYPT, KM_PURPOSE_DECRYPT, KM_PURPOSE_SIGN ou KM_PURPOSE_VERIFY. Notez que pour les modes AEAD, le chiffrement et le déchiffrement impliquent respectivement la signature et la validation, mais doivent être spécifiés comme KM_PURPOSE_ENCRYPT et KM_PURPOSE_DECRYPT.
[in]	touche	Clé à utiliser pour l'opération. key doit avoir un objectif compatible avec purpose et toutes ses exigences d'utilisation doivent être satisfaites, sinon begin() renverra un code d'erreur approprié.
[in]	in_params	Paramètres supplémentaires pour l'opération. Il est généralement utilisé pour fournir des données d'authentification, avec KM_TAG_AUTH_TOKEN. Si KM_TAG_APPLICATION_ID ou KM_TAG_APPLICATION_DATA ont été fournis lors de la génération, ils doivent être fournis ici, sinon l'opération échouera avec KM_ERROR_INVALID_KEY_BLOB. Pour les opérations qui nécessitent un nonce ou un IV, sur les clés générées avec KM_TAG_CALLER_NONCE, in_params peut contenir une balise KM_TAG_NONCE.
[out]	out_params	Paramètres de sortie. Permet de renvoyer des données supplémentaires à partir de l'initialisation de l'opération, en particulier pour renvoyer l'IV ou le nonce à partir d'opérations qui génèrent un IV ou un nonce. L'appelant s'approprie le tableau des paramètres de sortie et doit le libérer avec keymaster_free_param_set() . out_params peut être défini sur NULL si aucun paramètre de sortie n'est attendu. Si out_params est NULL et que des paramètres de sortie sont générés, begin() renvoie KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	operation_handle	Le gestionnaire d'opération nouvellement créé qui doit être transmis à update() , finish() ou abort() . Si operation_handle est NULL, begin() renvoie KM_ERROR_OUTPUT_PARAMETER_NULL.

Définition à la ligne  332 du fichier keymaster2.h .

Méthodes courantes de l'appareil Keymaster. Cet élément doit être le premier membre de keymaster_device, car les utilisateurs de cette structure castent un hw_device_t en pointeur keymaster_device dans les contextes où il est connu que hw_device_t fait référence à un keymaster_device.

Définition à la ligne  35 du fichier keymaster2.h .

Configure Keymaster. Cette méthode doit être appelée une fois après l'ouverture de l'appareil et avant son utilisation. Il permet de fournir KM_TAG_OS_VERSION et KM_TAG_OS_PATCHLEVEL à Keymaster. Tant que cette méthode n'est pas appelée, toutes les autres méthodes renvoient KM_ERROR_KEYMASTER_NOT_CONFIGURED. Les valeurs fournies par cette méthode ne sont acceptées par Keymaster qu'une seule fois par démarrage. Les appels suivants renvoient KM_ERROR_OK, mais ne font rien.

Si l'implémentation de Keymaster se trouve dans du matériel sécurisé et que les valeurs de version de l'OS et du niveau de correctif fournies ne correspondent pas à celles fournies au matériel sécurisé par le bootloader (ou si le bootloader n'a pas fourni de valeurs), cette méthode renvoie KM_ERROR_INVALID_ARGUMENT, et toutes les autres méthodes continuent de renvoyer KM_ERROR_KEYMASTER_NOT_CONFIGURED.

Définition à la ligne  58 du fichier keymaster2.h .

Définition à la ligne 37 du fichier keymaster2.h .

Supprime toutes les clés du keystore matériel. Utilisé lorsque le keystore est réinitialisé complètement. Après avoir appelé cette fonction, il sera impossible d'utiliser des blobs de clé générés ou importés précédemment pour toute opération.

Cette fonction est facultative et doit être définie sur NULL si elle n'est pas implémentée.

Paramètres

[in]

dev

Structure de l'appareil Keymaster

Définition à la ligne 288 du fichier keymaster2.h .

Supprime la clé ou la paire de clés associée au blob de clé. Après avoir appelé cette fonction, il sera impossible d'utiliser la clé pour d'autres opérations. Peut être appliqué aux clés provenant de racines de confiance étrangères (clés non utilisables avec la racine de confiance actuelle).

Cette fonction est facultative et doit être définie sur NULL si elle n'est pas implémentée.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	touche	Clé à supprimer.

Définition à la ligne  276 du fichier keymaster2.h .

Exporte une clé publique ou symétrique, et renvoie un tableau d'octets au format spécifié.

Notez que l'exportation de clés symétriques n'est autorisée que si la clé a été créée avec KM_TAG_EXPORTABLE et uniquement si toutes les exigences d'utilisation de la clé (authentification, par exemple) sont remplies.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	export_format	Format à utiliser pour exporter la clé.
[in]	key_to_export	Clé à exporter.
[in]	client_id	Blob de l'ID client, qui doit correspondre au blob fourni dans KM_TAG_APPLICATION_ID lors de la génération de la clé (le cas échéant).
[in]	app_data	Blob de données d'application, qui doit correspondre au blob fourni dans KM_TAG_APPLICATION_DATA lors de la génération de clé (le cas échéant).
[out]	export_data	Matériel de clé exporté. L'appelant en devient propriétaire.

Définition à la ligne  213 du fichier keymaster2.h .

Finalise une opération de chiffrement commencée avec begin() et invalide operation_handle .

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	operation_handle	Le gestionnaire d'opération renvoyé par begin() . Cet identifiant sera invalidé.
[in]	in_params	Paramètres supplémentaires pour l'opération. Pour les modes AEAD, il permet de spécifier KM_TAG_ADDITIONAL_DATA, mais uniquement si aucune donnée d'entrée n'a été fournie à update() .
[in]	entrée	Données à traiter, conformément aux paramètres définis dans l'appel à begin() . finish() doit consommer toutes les données fournies ou renvoyer KM_ERROR_INVALID_INPUT_LENGTH.
[in]	signature	Signature à valider si l'objectif spécifié dans l'appel begin() était KM_PURPOSE_VERIFY.
[out]	output	Données de sortie, le cas échéant. L'appelant assume la propriété du tampon alloué.

Si l'opération en cours de finalisation est une validation de signature ou un déchiffrement en mode AEAD, et que la validation échoue, finish() renvoie KM_ERROR_VERIFICATION_FAILED.

Définition à la ligne  405 du fichier keymaster2.h .

Consultez les indicateurs définis pour keymaster0_devices::flags dans keymaster_common.h . Utilisé uniquement pour la rétrocompatibilité. Les appareils matériels keymaster2 doivent définir cette valeur sur zéro.

Définition à la ligne  43 du fichier keymaster2.h .

Génère une clé ou une paire de clés, et renvoie un blob de clé et/ou une description de la clé.

Les paramètres de génération de clés sont définis sous forme de paires balise/valeur Keymaster, fournies dans params . Pour obtenir la liste complète, consultez keymaster_tag_t. Voici quelques valeurs toujours requises pour générer des clés utiles:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE ; et
• (KM_TAG_USER_SECURE_ID et KM_TAG_USER_AUTH_TYPE) ou KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT doit généralement être spécifié, sauf si KM_TAG_NO_AUTH_REQUIRED est présent, sinon l'utilisateur devra s'authentifier à chaque utilisation.

KM_TAG_BLOCK_MODE, KM_TAG_PADDING, KM_TAG_MAC_LENGTH et KM_TAG_DIGEST doivent être spécifiés pour les algorithmes qui les nécessitent.

Les balises suivantes ne doivent pas être spécifiées. Leurs valeurs seront fournies par l'implémentation.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	params	Tableau de paramètres de génération de clés
[out]	key_blob	renvoie la clé générée. key_blob ne doit pas être NULL. L'appelant assume la propriété key_blob->key_material et doit la libérer (free()).
[out]	caractéristiques	renvoie les caractéristiques de la clé générée, si elle n'est pas nulle. Si la valeur n'est pas NULL, l'appelant en devient propriétaire et doit la désallouer avec keymaster_free_characteristics() . Notez que KM_TAG_ROOT_OF_TRUST, KM_TAG_APPLICATION_ID et KM_TAG_APPLICATION_DATA ne sont jamais renvoyés.

Définition à la ligne  112 du fichier keymaster2.h .

Renvoie les caractéristiques de la clé spécifiée, ou KM_ERROR_INVALID_KEY_BLOB si le key_blob est non valide (les implémentations doivent valider entièrement l'intégrité de la clé). client_id et app_data doivent correspondre à l'ID et aux données fournis lors de la génération ou de l'importation de la clé, ou être vides si KM_TAG_APPLICATION_ID et/ou KM_TAG_APPLICATION_DATA n'ont pas été fournis lors de la génération. Ces valeurs ne sont pas incluses dans les caractéristiques renvoyées. L'appelant assume la propriété de l'objet de caractéristiques alloué, qui doit être désallooué avec keymaster_free_characteristics() .

Notez que KM_TAG_APPLICATION_ID et KM_TAG_APPLICATION_DATA ne sont jamais renvoyés.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	key_blob	Clé à partir de laquelle les caractéristiques doivent être récupérées.
[in]	client_id	Données de l'ID client, ou NULL si aucun n'est associé.
[in]	app_id	Données de l'application ou NULL si aucune n'est associée.
[out]	caractéristiques	Principales caractéristiques Ne doit pas être NULL. L'appelant s'approprie le contenu et doit le libérer avec keymaster_free_characteristics() .

Définition à la ligne  139 du fichier keymaster2.h .

Importe une clé ou une paire de clés, et renvoie un blob de clé et/ou une description de la clé.

La plupart des paramètres d'importation clés sont définis sous forme de paires balise/valeur Keymaster, fournies dans "params". Pour obtenir la liste complète, consultez keymaster_tag_t. Les valeurs suivantes sont toujours requises pour importer des clés utiles:

• KM_TAG_ALGORITHM;
• KM_TAG_PURPOSE ; et
• (KM_TAG_USER_SECURE_ID et KM_TAG_USER_AUTH_TYPE) ou KM_TAG_NO_AUTH_REQUIRED.

KM_TAG_AUTH_TIMEOUT doit généralement être spécifié. S'il n'est pas spécifié, l'utilisateur devra s'authentifier à chaque utilisation.

Les balises suivantes utiliseront des valeurs par défaut si elles ne sont pas spécifiées:

• La taille de la clé fournie est utilisée par défaut pour KM_TAG_KEY_SIZE.
• La valeur par défaut de KM_TAG_RSA_PUBLIC_EXPONENT est celle de la clé fournie (pour les clés RSA).

Les balises suivantes ne doivent pas être spécifiées. Leurs valeurs seront fournies par l'implémentation.

• KM_TAG_ORIGIN,
• KM_TAG_ROLLBACK_RESISTANT,
• KM_TAG_CREATION_DATETIME

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	params	Paramètres définissant la clé importée.
[in]	params_count	Nombre d'entrées dans params .
[in]	key_format	Spécifie le format des données de clé dans key_data.
[out]	key_blob	Permet de renvoyer le blob de clé opaque. Ne doit pas être NULL. L'appelant assume la propriété du matériel de clé contenu.
[out]	caractéristiques	Permet de renvoyer les caractéristiques de la clé importée. Peut être NULL, auquel cas aucune caractéristique ne sera renvoyée. Si la valeur n'est pas NULL, l'appelant assume la propriété du contenu et doit le désallouer avec keymaster_free_characteristics() . Notez que KM_TAG_APPLICATION_ID et KM_TAG_APPLICATION_DATA ne sont jamais renvoyés.

Définition à la ligne  186 du fichier keymaster2.h .

Fournit des données à une opération cryptographique en cours lancée avec begin() et reçoit éventuellement sa sortie.

Si operation_handle n'est pas valide, update() renvoie KM_ERROR_INVALID_OPERATION_HANDLE.

update() peut ne pas consommer toutes les données fournies dans le tampon de données. update() renvoie la quantité consommée dans *data_consumed. L'appelant doit fournir les données non consommées dans un appel ultérieur.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	operation_handle	Le gestionnaire d'opération renvoyé par begin() .
[in]	in_params	Paramètres supplémentaires pour l'opération. Pour les modes AEAD, il permet de spécifier KM_TAG_ADDITIONAL_DATA. Notez que des données supplémentaires peuvent être fournies dans plusieurs appels à update() , mais uniquement jusqu'à ce que les données d'entrée aient été fournies.
[in]	entrée	Données à traiter, conformément aux paramètres définis dans l'appel à begin() . Notez que update() peut consommer ou non toutes les données fournies. Consultez input_consumed .
[out]	input_consumed	Quantité de données consommées par update() . Si ce montant est inférieur au montant fourni, l'appelant doit fournir le reste dans un appel ultérieur à update() .
[out]	out_params	Paramètres de sortie. Permet de renvoyer des données supplémentaires à partir de l'opération. L'appelant devient propriétaire du tableau des paramètres de sortie et doit le libérer avec keymaster_free_param_set() . out_params peut être défini sur NULL si aucun paramètre de sortie n'est attendu. Si out_params est NULL et que des paramètres de sortie sont générés, begin() renvoie KM_ERROR_OUTPUT_PARAMETER_NULL.
[out]	output	Données de sortie, le cas échéant. L'appelant assume la propriété du tampon alloué. La sortie ne doit pas être NULL.

Notez que update() peut ne pas fournir de sortie, auquel cas output->data_length sera nul, et output->data peut être NULL ou de longueur nulle (l'appelant doit donc toujours le libérer avec free()).

Définition à la ligne  376 du fichier keymaster2.h .

Met à niveau une ancienne clé. Les clés peuvent devenir "obsolètes" de deux manières: Keymaster peut être mis à niveau vers une nouvelle version, ou le système peut être mis à jour pour invalider la version de l'OS et/ou le niveau de correctif. Dans les deux cas, les tentatives d'utilisation d'une ancienne clé entraîneront le retour de KM_ERROR_KEY_REQUIRES_UPGRADE par keymaster. Cette méthode doit ensuite être appelée pour mettre à niveau la clé.

Paramètres

[in]	dev	Structure de l'appareil Keymaster
[in]	key_to_upgrade	Clé Keymaster à mettre à niveau.
[in]	upgrade_params	Paramètres requis pour effectuer la mise à niveau. Plus précisément, KM_TAG_APPLICATION_ID et KM_TAG_APPLICATION_DATA sont obligatoires s'ils ont été définis pour la clé.
[out]	upgraded_key	Blob de clé mis à niveau.

Définition à la ligne  260 du fichier keymaster2.h .