référence de structure keymaster2_device

référence de structure keymaster2_device

#include < keymaster2.h >

Champs de données

structure hw_device_t commun
annuler * le contexte
uint32_t drapeaux
keymaster_error_t (* configurer )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)
keymaster_error_t (* add_rng_entropy )(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)
keymaster_error_t (* generate_key )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)
keymaster_error_t (* get_key_characteristics )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *caractéristiques)
keymaster_error_t (* import_key )(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *caractéristiques)
keymaster_error_t (* export_key )(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)
keymaster_error_t (* attest_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain)
keymaster_error_t (* upgrade_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key)
keymaster_error_t (* delete_key )(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)
keymaster_error_t (* delete_all_keys )(structure const keymaster2_device *dev)
keymaster_error_t (* begin )(const struct keymaster2_device *dev, keymaster_purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle)
keymaster_error_t (* mise à jour )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
keymaster_error_t (* finition )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)
keymaster_error_t (* abandonner )(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

Description détaillée

Définition de l'appareil Keymaster2

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

Documentation de terrain

keymaster_error_t (* abandonner)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle)

Abandonne une opération cryptographique commencée avec begin() , libérant toutes les ressources internes et invalidant operation_handle .

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

keymaster_error_t (* add_rng_entropy)(const struct keymaster2_device *dev, const uint8_t *data, size_t data_length)

Ajoute de l'entropie au RNG utilisé par keymaster. L'entropie ajoutée par cette méthode est garantie de ne pas être la seule source d'entropie utilisée, et la fonction de mélange doit être sécurisée, en ce sens que si le RNG est amorcé (à partir de n'importe quelle source) avec des données que l'attaquant ne peut pas prédire (ou contrôle), alors la sortie RNG est indiscernable du hasard. Ainsi, si l'entropie de n'importe quelle source est bonne, la sortie sera bonne.

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] Les données Données aléatoires à mélanger.
[dans] data_length Longueur des data .

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

keymaster_error_t (* attest_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_attest, const keymaster_key_param_set_t *attest_params, keymaster_cert_chain_t *cert_chain)

Génère une chaîne de certificats X.509 signée attestant de la présence de key_to_attest dans keymaster (TODO(swillden): Décrire le contenu du certificat plus en détail). 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
[dans] développeur La structure du périphérique keymaster.
[dans] key_to_attest La clé principale pour laquelle le certificat d'attestation sera généré.
[dans] attest_params Paramètres définissant comment faire l'attestation. Actuellement, le seul paramètre est KM_TAG_ALGORITHM, qui doit être soit KM_ALGORITHM_EC soit KM_ALGORITHM_RSA. Cela sélectionne laquelle des clés d'attestation provisionnées sera utilisée pour signer le certificat.
[dehors] cert_chain Un tableau de certificats X.509 codés DER. Le premier sera le certificat pour key_to_attest . Les entrées restantes remonteront à la racine. L'appelant prend possession et doit désallouer avec keymaster_free_cert_chain.

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

keymaster_error_t (* begin)(const struct keymaster2_device *dev, keymaster_purpose_t purpose, const keymaster_key_blob_t *key, const keymaster_key_param_set_t *in_params, keymaster_key_param_set_t *out_params, keymaster_operation_handle_t *operation_handle)

Commence une opération de chiffrement à l'aide de la clé spécifiée. Si tout va bien, begin() renverra KM_ERROR_OK et créera un handle d'opération qui doit être passé aux appels suivants à update() , finish() ou abort() .

Il est essentiel que chaque appel à begin() soit associé à un appel ultérieur à finish() ou abort() , pour permettre à l'implémentation keymaster de nettoyer tout état de fonctionnement interne. Ne pas le faire peut entraîner une fuite d'espace d'état interne ou d'autres ressources internes et peut éventuellement amener begin() à renvoyer KM_ERROR_TOO_MANY_OPERATIONS lorsqu'il manque d'espace pour les opérations. Tout résultat autre que KM_ERROR_OK de begin() , update() ou finish() interrompt implicitement l'opération, auquel cas abort() n'a pas besoin d'être appelé (et renverra KM_ERROR_INVALID_OPERATION_HANDLE s'il est appelé).

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] objectif Le but de l'opération, l'un des 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 vérification, mais doivent être spécifiés comme KM_PURPOSE_ENCRYPT et KM_PURPOSE_DECRYPT.
[dans] clé Clé à utiliser pour l'opération. key doit avoir un but compatible avec le purpose et toutes ses exigences d'utilisation doivent être satisfaites, sinon begin() renverra un code d'erreur approprié.
[dans] in_params Paramètres supplémentaires pour l'opération. Ceci 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 qui ont été générées avec KM_TAG_CALLER_NONCE, in_params peut contenir une balise KM_TAG_NONCE.
[dehors] out_params Paramètres de sortie. Utilisé pour retourner des données supplémentaires à partir de l'initialisation de l'opération, notamment pour retourner l'IV ou le nonce des 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 les paramètres de sortie sont générés, begin() renverra KM_ERROR_OUTPUT_PARAMETER_NULL.
[dehors] operation_handle Le handle d'opération nouvellement créé qui doit être passé à update() , finish() ou abort() . Si operation_handle est NULL, begin() renverra KM_ERROR_OUTPUT_PARAMETER_NULL.

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

structure hw_device_t commun

Méthodes courantes de l'appareil keymaster. Ce doit être le premier membre de keymaster_device car les utilisateurs de cette structure lanceront un pointeur hw_device_t vers keymaster_device dans des 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 .

keymaster_error_t (* configure)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params)

Configure le keymaster. Cette méthode doit être appelée une fois après l'ouverture du périphérique et avant son utilisation. Il est utilisé pour fournir KM_TAG_OS_VERSION et KM_TAG_OS_PATCHLEVEL au keymaster. Jusqu'à ce que cette méthode soit appelée, toutes les autres méthodes renverront 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 renverront KM_ERROR_OK, mais ne font rien.

Si l'implémentation du keymaster est dans un matériel sécurisé et que les valeurs de version et de niveau de correctif du système d'exploitation fournies ne correspondent pas aux valeurs fournies au matériel sécurisé par le chargeur de démarrage (ou si le chargeur de démarrage n'a pas fourni de valeurs), cette méthode renverra KM_ERROR_INVALID_ARGUMENT, et tous les autres méthodes continueront à renvoyer KM_ERROR_KEYMASTER_NOT_CONFIGURED.

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

contexte vide*

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

keymaster_error_t (* delete_all_keys)(const struct keymaster2_device *dev)

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

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

Paramètres
[dans] développeur La structure du périphérique keymaster.

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

keymaster_error_t (* delete_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key)

Supprime la clé, ou la paire de clés, associée au blob de clés. Après avoir appelé cette fonction, il sera impossible d'utiliser la clé pour toute autre opération. Peut être appliqué aux clés provenant de racines de confiance étrangères (clés non utilisables sous 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
[dans] développeur La structure du périphérique keymaster.
[dans] clé Clé à supprimer.

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

keymaster_error_t (* export_key)(const struct keymaster2_device *dev, keymaster_key_format_t export_format, const keymaster_key_blob_t *key_to_export, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_blob_t *export_data)

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

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

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] export_format Le format à utiliser pour exporter la clé.
[dans] clé_à_exporter La clé de l'exportation.
[dans] identité du client Blob d'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).
[dans] données d'application Blob de données d'application, qui doit correspondre au blob fourni dans KM_TAG_APPLICATION_DATA lors de la génération de la clé (le cas échéant).
[dehors] exporter des données Le matériel de clé exporté. L'appelant en assume la propriété.

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

keymaster_error_t (* terminer)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, const keymaster_blob_t *signature, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

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

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] operation_handle Le handle d'opération renvoyé par begin() . Ce descripteur sera invalidé.
[dans] in_params Paramètres supplémentaires pour l'opération. Pour les modes AEAD, ceci est utilisé pour spécifier KM_TAG_ADDITIONAL_DATA, mais uniquement si aucune donnée d'entrée n'a été fournie à update() .
[dans] saisir Données à traiter, selon les paramètres établis dans l'appel à begin() . finish() doit consommer toutes les données fournies ou renvoyer KM_ERROR_INVALID_INPUT_LENGTH.
[dans] Signature La signature à vérifier si le but spécifié dans l'appel begin() était KM_PURPOSE_VERIFY.
[dehors] production Les données de sortie, le cas échéant. L'appelant assume la propriété du tampon alloué.

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

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

Drapeaux uint32_t

Voir les drapeaux définis pour keymaster0_devices::flags dans keymaster_common.h . Utilisé uniquement pour la rétrocompatibilité ; Les périphériques matériels keymaster2 doivent le régler sur zéro.

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

keymaster_error_t (* generate_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *characteristics)

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

Les paramètres de génération de clé sont définis comme des paires balise/valeur keymaster, fournies dans params . Voir keymaster_tag_t pour la liste complète. Certaines valeurs qui sont toujours requises pour la génération de clés utiles sont :

  • 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 peuvent ne 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
[dans] développeur La structure du périphérique keymaster.
[dans] paramètres Tableau de paramètres de génération de clé
[dehors] 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 le libérer().
[dehors] les caractéristiques renvoie les caractéristiques de la clé qui a été, générée, si non NULL. Si non-NULL, l'appelant assume la propriété et doit 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 .

keymaster_error_t (* get_key_characteristics)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_blob, const keymaster_blob_t *client_id, const keymaster_blob_t *app_data, keymaster_key_characteristics_t *caractéristiques)

Renvoie les caractéristiques de la clé spécifiée, ou KM_ERROR_INVALID_KEY_BLOB si le key_blob est invalide (les implémentations doivent valider entièrement l'intégrité de la clé). client_id et app_data doivent être l'ID et les données fournies lors de la génération ou de l'importation de la clé, ou 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ésalloué avec keymaster_free_characteristics() .

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

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] key_blob La clé pour récupérer les caractéristiques de.
[dans] identité du client Les données d'ID client, ou NULL si aucune n'est associée.
[dans] app_id Les données de l'application, ou NULL si aucune n'est associée.
[dehors] les caractéristiques Les caractéristiques clés. Ne doit pas être NULL. L'appelant assume la propriété du contenu et doit désallouer avec keymaster_free_characteristics() .

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

keymaster_error_t (* import_key)(const struct keymaster2_device *dev, const keymaster_key_param_set_t *params, keymaster_key_format_t key_format, const keymaster_blob_t *key_data, keymaster_key_blob_t *key_blob, keymaster_key_characteristics_t *caractéristiques)

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

La plupart des paramètres d'importation de clé sont définis comme des paires balise/valeur keymaster, fournies dans "params". Voir keymaster_tag_t pour la liste complète. Les valeurs qui sont toujours requises pour l'importation de clés utiles sont :

  • 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é. Si non spécifié, l'utilisateur devra s'authentifier pour chaque utilisation.

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

  • KM_TAG_KEY_SIZE prendra par défaut la taille de la clé fournie.
  • KM_TAG_RSA_PUBLIC_EXPONENT prendra par défaut la valeur de la clé fournie (pour les clés RSA)

Les balises suivantes peuvent ne 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
[dans] développeur La structure du périphérique keymaster.
[dans] paramètres Paramètres définissant la clé importée.
[dans] params_count Le nombre d'entrées dans params .
[dans] format_clé spécifie le format des données de clé dans key_data.
[dehors] key_blob Utilisé pour renvoyer le blob de clé opaque. Doit être non NULL. L'appelant assume la propriété du key_material contenu.
[dehors] les caractéristiques Permet de retourner les caractéristiques de la clé importée. Peut être NULL, auquel cas aucune caractéristique ne sera renvoyée. Si non NULL, l'appelant assume la propriété du contenu et doit 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 .

keymaster_error_t (* mise à jour)(const struct keymaster2_device *dev, keymaster_operation_handle_t operation_handle, const keymaster_key_param_set_t *in_params, const keymaster_blob_t *input, size_t *input_consumed, keymaster_key_param_set_t *out_params, keymaster_blob_t *output)

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

Si operation_handle est invalide, update() renverra KM_ERROR_INVALID_OPERATION_HANDLE.

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

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] operation_handle Le handle d'opération renvoyé par begin() .
[dans] in_params Paramètres supplémentaires pour l'opération. Pour les modes AEAD, ceci est utilisé pour 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.
[dans] saisir Données à traiter, selon les paramètres établis dans l'appel à begin() . Notez que update() peut consommer ou non toutes les données fournies. Voir input_consumed .
[dehors] entrée_consommée Quantité de données consommées par update() . Si cela est inférieur au montant fourni, l'appelant doit fournir le reste dans un appel ultérieur à update() .
[dehors] out_params Paramètres de sortie. Utilisé pour renvoyer des données supplémentaires à partir de l'opération. 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 les paramètres de sortie sont générés, begin() renverra KM_ERROR_OUTPUT_PARAMETER_NULL.
[dehors] production Les 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 fournir aucune sortie, auquel cas output->data_length sera égal à zéro, et output->data peut être NULL ou de longueur nulle (donc l'appelant doit toujours le libérer()).

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

keymaster_error_t (* upgrade_key)(const struct keymaster2_device *dev, const keymaster_key_blob_t *key_to_upgrade, const keymaster_key_param_set_t *upgrade_params, keymaster_key_blob_t *upgraded_key)

Met à niveau une ancienne clé. Les clés peuvent devenir "anciennes" 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 du système d'exploitation et/ou le niveau de correctif. Dans les deux cas, les tentatives d'utilisation d'une ancienne clé entraîneront le renvoi par le maître de clés de KM_ERROR_KEY_REQUIRES_UPGRADE. Cette méthode doit ensuite être appelée pour mettre à jour la clé.

Paramètres
[dans] développeur La structure du périphérique keymaster.
[dans] key_to_upgrade La clé principale à mettre à niveau.
[dans] upgrade_params Paramètres nécessaires pour terminer la mise à niveau. En particulier, KM_TAG_APPLICATION_ID et KM_TAG_APPLICATION_DATA seront requis s'ils ont été définis pour la clé.
[dehors] clé_améliorée Le blob de clé mis à niveau.

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


La documentation de cette structure a été générée à partir du fichier suivant :