Fonctions Keymaster,Fonctions Keymaster

Cette page fournit des détails pour aider les implémenteurs des couches d'abstraction matérielle Keymaster (HAL). Il couvre chaque fonction de l'API et la version de Keymaster dans laquelle cette fonction est disponible et décrit l'implémentation par défaut. Pour les balises, consultez la page Keymaster Tags .

Consignes générales de mise en œuvre

Les directives suivantes s'appliquent à toutes les fonctions de l'API.

Paramètres du pointeur d'entrée

Version : 1, 2

Les paramètres de pointeur d'entrée qui ne sont pas utilisés pour un appel donné peuvent être NULL . L'appelant n'est pas tenu de fournir des espaces réservés. Par exemple, certains types et modes de clé peuvent n'utiliser aucune valeur de l'argument inParams pour begin , de sorte que l'appelant peut définir inParams sur NULL ou fournir un jeu de paramètres vide. Les appelants peuvent également fournir des paramètres inutilisés et les méthodes Keymaster ne doivent pas générer d'erreurs.

Si un paramètre d'entrée requis est NULL, les méthodes Keymaster doivent renvoyer ErrorCode::UNEXPECTED_NULL_POINTER .

À partir de Keymaster 3, il n'y a pas de paramètres de pointeur. Tous les paramètres sont passés par des références de valeur ou const.

Paramètres du pointeur de sortie

Version : 1, 2

Comme pour les paramètres de pointeur d'entrée, les paramètres de pointeur de sortie inutilisés peuvent être NULL . Si une méthode doit renvoyer des données dans un paramètre de sortie trouvé NULL , elle doit renvoyer ErrorCode::OUTPUT_PARAMETER_NULL .

À partir de Keymaster 3, il n'y a pas de paramètres de pointeur. Tous les paramètres sont passés par des références de valeur ou const.

Utilisation abusive de l'API

Variantes : 1, 2, 3

Il existe de nombreuses façons pour les appelants de faire des demandes qui n'ont pas de sens ou qui sont stupides mais pas techniquement erronées. Les implémentations Keymaster ne sont pas tenues d'échouer dans de tels cas ou d'émettre un diagnostic. L'utilisation de clés trop petites, la spécification de paramètres d'entrée non pertinents, la réutilisation d'IV ou de nonces, la génération de clés sans but (donc inutiles) et autres ne doivent pas être diagnostiquées par les implémentations. L'omission de paramètres requis, la spécification de paramètres requis non valides et les erreurs similaires doivent être diagnostiquées.

Il est de la responsabilité des applications, du framework et du magasin de clés Android de s'assurer que les appels aux modules Keymaster sont sensés et utiles.

Les fonctions

getHardwareFeatures

Version : 3

La nouvelle méthode getHardwareFeatures expose aux clients certaines caractéristiques importantes du matériel sécurisé sous-jacent. La méthode ne prend aucun argument et renvoie quatre valeurs, toutes booléennes :

  • isSecure est true si les clés sont stockées dans du matériel sécurisé (TEE, etc.) et ne le quittent jamais.
  • supportsEllipticCurve est true si le matériel prend en charge la cryptographie à courbe elliptique avec les courbes NIST (P-224, P-256, P-384 et P-521).
  • supportsSymmetricCryptography est true si le matériel prend en charge la cryptographie symétrique, y compris AES et HMAC.
  • supportsAttestation vaut true si le matériel prend en charge la génération de certificats d'attestation de clé publique Keymaster, signés avec une clé injectée dans un environnement sécurisé.

Les seuls codes d'erreur que cette méthode peut renvoyer sont ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED ou l'un des codes d'erreur indiquant un échec de communication avec le matériel sécurisé.

getHardwareFeatures()
    generates(bool isSecure, bool supportsEllipticCurve, bool supportsSymmetricCryptography,
              bool supportsAttestation, bool supportsAllDigests, string keymasterName,
              string keymasterAuthorName);

configurer

Version : 2

Cette fonction a été introduite dans Keymaster 2 et obsolète dans Keymaster 3, car ces informations sont disponibles dans les fichiers de propriétés système et les implémentations du fabricant lisent ces fichiers au démarrage.

Configure le keymaster. Cette méthode est 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 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 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 renvoie KM_ERROR_INVALID_ARGUMENT , et tous les autres les méthodes continuent de renvoyer KM_ERROR_KEYMASTER_NOT_CONFIGURED .

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

addRngEntropy

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom de add_rng_entropy et renommée dans Keymaster 3.

Ajoute l'entropie fournie par l'appelant au pool utilisé par l'implémentation Keymaster 1 pour générer des nombres aléatoires, pour les clés, les IV, etc.

Les implémentations Keymaster doivent mélanger en toute sécurité l'entropie fournie dans leur pool, qui doit également contenir l'entropie générée en interne à partir d'un générateur de nombres aléatoires matériel. Le mélange doit être géré de sorte qu'un attaquant qui a le contrôle total des bits fournis par addRngEntropy ou des bits générés par le matériel, mais pas des deux, n'ait aucun avantage non négligeable à prédire les bits générés à partir du pool d'entropie.

Les implémentations Keymaster qui tentent d'estimer l'entropie dans leur pool interne supposent que les données fournies par addRngEntropy ne contiennent aucune entropie. Les implémentations Keymaster peuvent renvoyer ErrorCode::INVALID_INPUT_LENGTH si elles reçoivent plus de 2 Ko de données en un seul appel.

générer une clé

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom de generate_key et renommée dans Keymaster 3.

Génère une nouvelle clé cryptographique, en spécifiant les autorisations associées, qui sont liées en permanence à la clé. Les implémentations de Keymaster rendent impossible l'utilisation d'une clé d'une manière incompatible avec les autorisations spécifiées au moment de la génération. En ce qui concerne les autorisations que le matériel sécurisé ne peut pas appliquer, l'obligation du matériel sécurisé se limite à s'assurer que les autorisations inapplicables associées à la clé ne peuvent pas être modifiées, de sorte que chaque appel à getKeyCharacteristics renvoie la valeur d'origine. De plus, les caractéristiques renvoyées par generateKey allouent correctement les autorisations entre les listes appliquées par le matériel et appliquées par le logiciel. Voir getKeyCharacteristics pour plus de détails.

Les paramètres fournis à generateKey dépendent du type de clé générée. Cette section résume les balises nécessaires et facultatives pour chaque type de clé. Tag::ALGORITHM est toujours nécessaire, pour spécifier le type.

Clés RSA

Les paramètres suivants sont nécessaires pour générer une clé RSA.

  • Tag::KEY_SIZE spécifie la taille du module public, en bits. Si omis, la méthode renvoie ErrorCode::UNSUPPORTED_KEY_SIZE . Les valeurs prises en charge sont 1024, 2048, 3072 et 4096. Les valeurs recommandées sont toutes les tailles de clé qui sont un multiple de 8.
  • Tag::RSA_PUBLIC_EXPONENT spécifie la valeur de l'exposant public RSA. Si omis, la méthode renvoie ErrorCode::INVALID_ARGUMENT . Les valeurs prises en charge sont 3 et 65537. Les valeurs recommandées sont toutes les valeurs premières jusqu'à 2^64.

Les paramètres suivants ne sont pas nécessaires pour générer une clé RSA, mais la création d'une clé RSA sans eux produit une clé inutilisable. Cependant, la fonction generateKey ne renvoie pas d'erreur si ces paramètres sont omis.

  • Tag::PURPOSE spécifie les objectifs autorisés. Tous les objectifs doivent être pris en charge pour les clés RSA, dans n'importe quelle combinaison.
  • Tag::DIGEST spécifie les algorithmes de résumé qui peuvent être utilisés avec la nouvelle clé. Les implémentations qui ne prennent pas en charge tous les algorithmes de résumé doivent accepter les demandes de génération de clé qui incluent des résumés non pris en charge. Les résumés non pris en charge doivent être placés dans la liste "appliquée par logiciel" dans les caractéristiques de clé renvoyées. En effet, la clé est utilisable avec ces autres résumés, mais la digestion est effectuée dans le logiciel. Ensuite, le matériel est appelé pour effectuer l'opération avec Digest::NONE .
  • Tag::PADDING spécifie les modes de remplissage pouvant être utilisés avec la nouvelle clé. Les implémentations qui ne prennent pas en charge tous les algorithmes de résumé doivent placer PaddingMode::RSA_PSS et PaddingMode::RSA_OAEP dans la liste appliquée par logiciel des caractéristiques clés si des algorithmes de résumé non pris en charge sont spécifiés.

Clés ECDSA

Seul Tag::KEY_SIZE est nécessaire pour générer une clé ECDSA. Il est utilisé pour sélectionner le groupe EC. Les valeurs prises en charge sont 224, 256, 384 et 521, qui indiquent respectivement les courbes NIST p-224, p-256, p-384 et p521.

Tag::DIGEST est également nécessaire pour une clé ECDSA utile, mais n'est pas requis pour la génération.

Clés AES

Seul Tag::KEY_SIZE est nécessaire pour générer une clé AES. Si omis, la méthode renvoie ErrorCode::UNSUPPORTED_KEY_SIZE . Les valeurs prises en charge sont 128 et 256, avec prise en charge facultative des clés AES 192 bits.

Les paramètres suivants sont particulièrement pertinents pour les clés AES, mais pas nécessaires pour en générer une :

  • Tag::BLOCK_MODE spécifie les modes de bloc avec lesquels la nouvelle clé peut être utilisée.
  • Tag::PADDING spécifie les modes de remplissage qui peuvent être utilisés. Ceci n'est pertinent que pour les modes ECB et CBC.

Si le mode de bloc GCM est spécifié, fournissez le Tag::MIN_MAC_LENGTH . Si omis, la méthode renvoie ErrorCode::MISSING_MIN_MAC_LENGTH . La valeur de la balise est un multiple de 8 et comprise entre 96 et 128.

Clés HMAC

Les paramètres suivants sont requis pour la génération de clé HMAC :

  • Tag::KEY_SIZE spécifie la taille de la clé en bits. Les valeurs inférieures à 64 et les valeurs qui ne sont pas des multiples de 8 ne sont pas prises en charge. Tous les multiples de 8, de 64 à 512, sont pris en charge. Des valeurs supérieures peuvent être prises en charge.
  • Tag::MIN_MAC_LENGTH spécifie la longueur minimale des MAC pouvant être générées ou vérifiées avec cette clé. La valeur est un multiple de 8 et au moins 64.
  • Tag::DIGEST spécifie l'algorithme de résumé pour la clé. Exactement un résumé est spécifié, sinon renvoie ErrorCode::UNSUPPORTED_DIGEST . Si le résumé n'est pas pris en charge par le trustlet, renvoyez ErrorCode::UNSUPPORTED_DIGEST .

Principales caractéristiques

Si l'argument de caractéristiques n'est pas NULL, generateKey renvoie les caractéristiques de la clé nouvellement générée divisées de manière appropriée en listes appliquées par le matériel et appliquées par le logiciel. Voir getKeyCharacteristics pour une description des caractéristiques qui vont dans quelle liste. Les caractéristiques renvoyées incluent tous les paramètres spécifiés pour la génération de clé, à l'exception de Tag::APPLICATION_ID et Tag::APPLICATION_DATA . Si ces balises étaient incluses dans les paramètres de clé, elles sont supprimées des caractéristiques renvoyées de sorte qu'il n'est pas possible de trouver leurs valeurs en examinant le blob de clé renvoyé. Cependant, ils sont cryptographiquement liés au blob de clé, de sorte que si les valeurs correctes ne sont pas fournies lorsque la clé est utilisée, l'utilisation échoue. De même, Tag::ROOT_OF_TRUST est cryptographiquement lié à la clé, mais il ne peut pas être spécifié lors de la création ou de l'importation de la clé et n'est jamais renvoyé.

En plus des balises fournies, le trustlet ajoute également Tag::ORIGIN , avec la valeur KeyOrigin::GENERATED , et si la clé est résistante à la restauration,

Balise :: ROLLBACK_RESISTANT .

Résistance au recul

La résistance à la restauration signifie qu'une fois qu'une clé est supprimée avec deleteKey ou deleteAllKeys , le matériel sécurisé garantit qu'elle ne sera plus jamais utilisable. Les implémentations sans résistance à l'annulation renvoient généralement le matériel de clé généré ou importé à l'appelant sous la forme d'un blob de clé, une forme chiffrée et authentifiée. Lorsque le magasin de clés supprime le blob de clé, la clé a disparu, mais un attaquant qui a précédemment réussi à récupérer le matériel de clé peut potentiellement le restaurer sur l'appareil.

Une clé est résistante à la restauration si le matériel sécurisé garantit que les clés supprimées ne pourront pas être restaurées ultérieurement. Cela se fait généralement en stockant des métadonnées clés supplémentaires dans un emplacement de confiance qui ne peut pas être manipulé par un attaquant. Sur les appareils mobiles, le mécanisme utilisé pour cela est généralement Replay Protected Memory Blocks (RPMB). Étant donné que le nombre de clés qui peuvent être créées est essentiellement illimité et que le stockage de confiance utilisé pour la résistance à la restauration peut être limité en taille, cette méthode doit réussir même si la résistance à la restauration ne peut pas être fournie pour la nouvelle clé. Dans ce cas, Tag::ROLLBACK_RESISTANT ne doit pas être ajouté aux caractéristiques clés.

getKeyCharacteristics

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom de get_key_characteristics et renommée dans Keymaster 3.

Renvoie les paramètres et les autorisations associés à la clé fournie, divisés en deux ensembles : appliqués par le matériel et appliqués par le logiciel. La description ici s'applique également aux listes de caractéristiques clés renvoyées par generateKey et importKey .

Si Tag::APPLICATION_ID a été fourni lors de la génération ou de l'importation de la clé, la même valeur est fournie à cette méthode dans l'argument clientId . Sinon, la méthode renvoie ErrorCode::INVALID_KEY_BLOB . De même, si Tag::APPLICATION_DATA a été fourni lors de la génération ou de l'importation, la même valeur est fournie à cette méthode dans l'argument appData .

Les caractéristiques renvoyées par cette méthode décrivent complètement le type et l'utilisation de la clé spécifiée.

La règle générale pour décider si une étiquette donnée appartient à la liste appliquée par le matériel ou par le logiciel est que si la signification de l'étiquette est entièrement assurée par un matériel sécurisé, elle est appliquée par le matériel. Sinon, c'est un logiciel appliqué. Vous trouverez ci-dessous une liste de balises spécifiques dont l'attribution correcte peut ne pas être claire :

  • Tag::ALGORITHM , Tag::KEY_SIZE et Tag::RSA_PUBLIC_EXPONENT sont des propriétés intrinsèques de la clé. Pour toute clé sécurisée par le matériel, ces balises figureront dans la liste appliquée par le matériel.
  • Les valeurs Tag::DIGEST prises en charge par le matériel sécurisé sont placées dans la liste prise en charge par le matériel. Les résumés non pris en charge vont dans la liste des logiciels pris en charge.
  • Les valeurs Tag::PADDING vont généralement dans la liste prise en charge par le matériel, sauf s'il est possible qu'un mode de remplissage spécifique doive être exécuté par le logiciel. Dans ce cas, ils vont dans la liste appliquée par logiciel. Une telle possibilité se présente pour les clés RSA qui permettent le remplissage PSS ou OAEP avec des algorithmes de résumé qui ne sont pas pris en charge par le matériel sécurisé.
  • Tag::USER_SECURE_ID et Tag::USER_AUTH_TYPE sont appliqués par le matériel uniquement si l'authentification de l'utilisateur est appliquée par le matériel. Pour ce faire, le trustlet Keymaster et le trustlet d'authentification concerné doivent tous deux être sécurisés et partager une clé HMAC secrète utilisée pour signer et valider les jetons d'authentification. Voir la page Authentification pour plus de détails.
  • Les balises Tag::ACTIVE_DATETIME , Tag ::ORIGINATION_EXPIRE_DATETIME et Tag::USAGE_EXPIRE_DATETIME nécessitent l'accès à une horloge murale dont l'exactitude peut être vérifiée. La plupart des matériels sécurisés n'ont accès qu'aux informations temporelles fournies par le système d'exploitation non sécurisé, ce qui signifie que les balises sont appliquées par logiciel.
  • Tag::ORIGIN est toujours dans la liste du matériel pour les clés liées au matériel. Sa présence dans cette liste est la façon dont les couches supérieures déterminent qu'une clé est basée sur le matériel.

importKey

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 en tant que import_key et renommée dans Keymaster 3.

Importe le matériel de clé dans le matériel Keymaster. Les paramètres de définition de clé et les caractéristiques de sortie sont gérés de la même manière que pour generateKey , avec les exceptions suivantes :

  • Tag::KEY_SIZE et Tag::RSA_PUBLIC_EXPONENT (pour les clés RSA uniquement) ne sont pas nécessaires dans les paramètres d'entrée. S'il n'est pas fourni, le trustlet déduit les valeurs du matériel de clé fourni et ajoute les balises et les valeurs appropriées aux caractéristiques de clé. Si les paramètres sont fournis, le trustlet les valide par rapport au matériel de clé. En cas de non-concordance, la méthode renvoie ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • Le Tag::ORIGIN renvoyé a la même valeur que KeyOrigin::IMPORTED .

clé d'exportation

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 en tant que export_key et renommée dans Keymaster 3.

Exporte une clé publique à partir d'une paire de clés Keymaster RSA ou EC.

Si Tag::APPLICATION_ID a été fourni lors de la génération ou de l'importation de la clé, la même valeur est fournie à cette méthode dans l'argument clientId . Sinon, la méthode renvoie ErrorCode::INVALID_KEY_BLOB . De même, si Tag::APPLICATION_DATA a été fourni lors de la génération ou de l'importation, la même valeur est fournie à cette méthode dans l'argument appData .

deleteKey

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom de delete_key et renommée dans Keymaster 3.

Supprime la clé fournie. Cette méthode est facultative et n'est implémentée que par les modules Keymaster qui offrent une résistance à la restauration.

deleteAllKeys

Variantes : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom de delete_all_keys et renommée dans Keymaster 3.

Supprime toutes les clés. Cette méthode est facultative et n'est implémentée que par les modules Keymaster qui offrent une résistance à la restauration.

destroyAttestationIds

Version : 3

La méthode destroyAttestationIds() est utilisée pour désactiver définitivement la nouvelle fonctionnalité d'attestation d'ID (facultative, mais fortement recommandée). Si le TEE n'a aucun moyen de s'assurer que l'attestation d'ID est définitivement désactivée après l'appel de cette méthode, alors l'attestation d'ID ne doit pas être implémentée du tout, auquel cas cette méthode ne fait rien et renvoie ErrorCode::UNIMPLEMENTED . Si l'attestation d'ID est prise en charge, cette méthode doit être implémentée et doit désactiver de manière permanente toutes les futures tentatives d'attestation d'ID. La méthode peut être appelée un nombre quelconque de fois. Si l'attestation d'ID est déjà désactivée de manière permanente, la méthode ne fait rien et renvoie ErrorCode::OK .

Les seuls codes d'erreur que cette méthode peut renvoyer sont ErrorCode::UNIMPLEMENTED (si l'attestation d'ID n'est pas prise en charge), ErrorCode:OK , ErrorCode::KEYMASTER_NOT_CONFIGURED ou l'un des codes d'erreur indiquant un échec de communication avec le matériel sécurisé.

commencer

Variantes : 1, 2, 3

Commence une opération de chiffrement à l'aide de la clé spécifiée, dans le but spécifié, avec les paramètres spécifiés (le cas échéant) et renvoie un descripteur d'opération qui est utilisé avec update et finish pour terminer l'opération. Le descripteur d'opération est également utilisé comme jeton "challenge" dans les opérations authentifiées, et pour de telles opérations est inclus dans le champ challenge du jeton d'authentification.

Une implémentation Keymaster prend en charge au moins 16 opérations simultanées. Le magasin de clés en utilise jusqu'à 15, ce qui en laisse un à vold pour le cryptage du mot de passe. Lorsque Keystore a 15 opérations en cours (le begin a été appelé, mais finish ou l' abort n'ont pas encore été appelés) et qu'il reçoit une demande pour en commencer une 16e, il appelle l' abort sur l'opération la moins récemment utilisée pour réduire le nombre d'opérations actives à 14 avant de begin à appeler pour démarrer l'opération nouvellement demandée.

Si Tag::APPLICATION_ID ou Tag::APPLICATION_DATA ont été spécifiés lors de la génération ou de l'importation de la clé, les appels à begin incluent ces balises avec les valeurs spécifiées à l'origine dans l'argument inParams de cette méthode.

Application de l'autorisation

Au cours de cette méthode, les autorisations de clé suivantes sont appliquées par le trustlet si l'implémentation les a placées dans les caractéristiques "appliquées par le matériel" et si l'opération n'est pas une opération à clé publique. Les opérations de clé publique, c'est-à-dire KeyPurpose::ENCRYPT et KeyPurpose::VERIFY , avec des clés RSA ou EC, sont autorisées à réussir même si les conditions d'autorisation ne sont pas remplies.

  • Tag::PURPOSE : Le but spécifié dans l'appel begin() doit correspondre à l'un des buts dans les autorisations de clé, sauf si l'opération demandée est une opération à clé publique. Si l'objectif spécifié ne correspond pas et que l'opération n'est pas une opération de clé publique, begin renverra ErrorCode::UNSUPPORTED_PURPOSE . Les opérations à clé publique sont des opérations de chiffrement ou de vérification asymétriques.
  • Tag::ACTIVE_DATETIME ne peut être appliqué que si une source de temps UTC fiable est disponible. Si la date et l'heure actuelles sont antérieures à la valeur de la balise, la méthode renvoie ErrorCode::KEY_NOT_YET_VALID .
  • La balise ::ORIGINATION_EXPIRE_DATETIME ne peut être appliquée que si une source de temps UTC fiable est disponible. Si la date et l'heure actuelles sont postérieures à la valeur de la balise et que l'objectif est KeyPurpose::ENCRYPT ou KeyPurpose::SIGN , la méthode renvoie ErrorCode::KEY_EXPIRED .
  • Tag::USAGE_EXPIRE_DATETIME ne peut être appliqué que si une source de temps UTC fiable est disponible. Si la date et l'heure actuelles sont postérieures à la valeur de la balise et que l'objectif est KeyPurpose::DECRYPT ou KeyPurpose::VERIFY , la méthode renvoie ErrorCode::KEY_EXPIRED .
  • Tag::MIN_SECONDS_BETWEEN_OPS est comparé à un temporisateur relatif de confiance indiquant la dernière utilisation de la clé. Si la dernière heure d'utilisation plus la valeur de la balise est inférieure à l'heure actuelle, la méthode renvoie ErrorCode::KEY_RATE_LIMIT_EXCEEDED . Voir la description de la balise pour les détails de mise en œuvre importants.
  • Tag::MAX_USES_PER_BOOT est comparé à un compteur sécurisé qui suit les utilisations de la clé depuis le démarrage. Si le nombre d'utilisations précédentes dépasse la valeur de la balise, la méthode renvoie ErrorCode::KEY_MAX_OPS_EXCEEDED .
  • Tag::USER_SECURE_ID est appliqué par cette méthode uniquement si la clé a également Tag::AUTH_TIMEOUT . Si la clé a les deux, alors cette méthode doit recevoir un Tag::AUTH_TOKEN valide dans inParams . Pour que le jeton d'authentification soit valide, tous les éléments suivants doivent être vrais :
    • Le champ HMAC valide correctement.
    • Au moins une des valeurs Tag::USER_SECURE_ID de la clé correspond à au moins une des valeurs d'ID sécurisé dans le jeton.
    • La clé a un Tag::USER_AUTH_TYPE qui correspond au type d'authentification dans le jeton.

    Si l'une de ces conditions n'est pas remplie, la méthode renvoie ErrorCode::KEY_USER_NOT_AUTHENTICATED .

  • Tag::CALLER_NONCE permet à l'appelant de spécifier un nonce ou un vecteur d'initialisation (IV). Si la clé n'a pas cette balise, mais que l'appelant a fourni Tag::NONCE à cette méthode, ErrorCode::CALLER_NONCE_PROHIBITED est renvoyé.
  • Tag::BOOTLOADER_ONLY spécifie que seul le bootloader peut utiliser la clé. Si cette méthode est appelée avec une clé réservée au bootloader après que le bootloader a fini de s'exécuter, elle renvoie ErrorCode::INVALID_KEY_BLOB .

Clés RSA

Toutes les opérations de clé RSA spécifient exactement un mode de remplissage dans inParams . S'il n'est pas spécifié ou s'il est spécifié plusieurs fois, la méthode renvoie ErrorCode::UNSUPPORTED_PADDING_MODE .

Les opérations de signature et de vérification RSA nécessitent un résumé, tout comme les opérations de chiffrement et de déchiffrement RSA avec le mode de remplissage OAEP. Dans ces cas, l'appelant spécifie exactement un résumé dans inParams . S'il n'est pas spécifié ou s'il est spécifié plusieurs fois, la méthode renvoie ErrorCode::UNSUPPORTED_DIGEST .

Les opérations de clé privée ( KeyPurpose::DECYPT et KeyPurpose::SIGN ) nécessitent une autorisation de résumé et de remplissage, ce qui signifie que les autorisations de clé doivent contenir les valeurs spécifiées. Si ce n'est pas le cas, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST ou ErrorCode::INCOMPATIBLE_PADDING , selon le cas. Les opérations de clé publique ( KeyPurpose::ENCRYPT et KeyPurpose::VERIFY ) sont autorisées avec un résumé ou un remplissage non autorisé.

À l'exception de PaddingMode::NONE , tous les modes de remplissage RSA ne sont applicables qu'à certaines fins. Plus précisément, PaddingMode::RSA_PKCS1_1_5_SIGN et PaddingMode::RSA_PSS ne prennent en charge que la signature et la vérification, tandis que PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT et PaddingMode::RSA_OAEP ne prennent en charge que le chiffrement et le déchiffrement. La méthode renvoie ErrorCode::UNSUPPORTED_PADDING_MODE si le mode spécifié ne prend pas en charge l'objectif spécifié.

Il existe des interactions importantes entre les modes de remplissage et les résumés :

  • PaddingMode::NONE indique qu'une opération RSA "brute" est effectuée. En cas de signature ou de vérification, Digest::NONE est spécifié pour le résumé. Aucun résumé n'est nécessaire pour le chiffrement ou le déchiffrement sans remplissage.
  • PaddingMode::RSA_PKCS1_1_5_SIGN remplissage RSA_PKCS1_1_5_SIGN nécessite un résumé. Le résumé peut être Digest::NONE , auquel cas l'implémentation Keymaster ne peut pas créer une structure de signature PKCS#1 v1.5 appropriée, car elle ne peut pas ajouter la structure DigestInfo. Au lieu de cela, l'implémentation construit 0x00 || 0x01 || PS || 0x00 || M , où M est le message fourni et PS est la chaîne de remplissage. La taille de la clé RSA doit être supérieure d'au moins 11 octets à celle du message, sinon la méthode renvoie ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT padding ne nécessite pas de résumé.
  • Le remplissage PaddingMode::RSA_PSS nécessite un résumé, qui peut ne pas être Digest::NONE . Si Digest::NONE est spécifié, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST . De plus, la taille de la clé RSA doit être supérieure d'au moins 2 + D octets à la taille de sortie du résumé, où D est la taille du résumé, en octets. Sinon, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST . La taille du sel est D.
  • Le remplissage PaddingMode::RSA_OAEP nécessite un résumé, qui peut ne pas être Digest::NONE . Si Digest::NONE est spécifié, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST .

Clés CE

Les opérations de touche EC spécifient exactement un mode de remplissage dans inParams . S'il n'est pas spécifié ou s'il est spécifié plusieurs fois, la méthode renvoie ErrorCode::UNSUPPORTED_PADDING_MODE .

Les opérations de clé privée ( KeyPurpose::SIGN ) nécessitent une autorisation de résumé et de remplissage, ce qui signifie que les autorisations de clé doivent contenir les valeurs spécifiées. Si ce n'est pas le cas, renvoyez ErrorCode::INCOMPATIBLE_DIGEST . Les opérations de clé publique ( KeyPurpose::VERIFY ) sont autorisées avec un résumé ou un remplissage non autorisé.

Clés AES

Les opérations de touche AES spécifient exactement un mode de bloc et un mode de remplissage dans inParams . Si l'une ou l'autre des valeurs n'est pas spécifiée ou est spécifiée plusieurs fois, renvoie ErrorCode::UNSUPPORTED_BLOCK_MODE ou ErrorCode::UNSUPPORTED_PADDING_MODE . Les modes spécifiés doivent être autorisés par la clé, sinon la méthode renvoie ErrorCode::INCOMPATIBLE_BLOCK_MODE ou ErrorCode::INCOMPATIBLE_PADDING_MODE .

Si le mode de bloc est BlockMode::GCM , inParams spécifie Tag::MAC_LENGTH et la valeur spécifiée est un multiple de 8 qui n'est pas supérieur à 128 ou inférieur à la valeur de Tag::MIN_MAC_LENGTH dans les autorisations de clé. Pour les longueurs MAC supérieures à 128 ou non multiples de 8, renvoyez ErrorCode::UNSUPPORTED_MAC_LENGTH . Pour les valeurs inférieures à la longueur minimale de la clé, renvoyez ErrorCode::INVALID_MAC_LENGTH .

Si le mode de bloc est BlockMode::GCM ou BlockMode::CTR , le mode de remplissage spécifié doit être PaddingMode::NONE . Pour BlockMode::ECB ou BlockMode::CBC , le mode peut être PaddingMode::NONE ou PaddingMode::PKCS7 . Si le mode de remplissage ne remplit pas ces conditions, renvoyez ErrorCode::INCOMPATIBLE_PADDING_MODE .

Si le mode de bloc est BlockMode::CBC , BlockMode::CTR ou BlockMode::GCM , un vecteur d'initialisation ou nonce est nécessaire. Dans la plupart des cas, les appelants ne doivent pas fournir de IV ou de nonce. Dans ce cas, l'implémentation Keymaster génère un IV aléatoire ou un nonce et le renvoie via Tag::NONCE dans outParams . Les IV CBC et CTR font 16 octets. Les nonces GCM sont de 12 octets. Si les autorisations de clé contiennent Tag::CALLER_NONCE , l'appelant peut fournir un IV/nonce avec Tag::NONCE dans inParams . Si un nonce est fourni lorsque Tag::CALLER_NONCE n'est pas autorisé, renvoie ErrorCode::CALLER_NONCE_PROHIBITED . Si un nonce n'est pas fourni lorsque Tag::CALLER_NONCE est autorisé, générez un IV/nonce aléatoire.

Clés HMAC

Les opérations de clé HMAC spécifient Tag::MAC_LENGTH dans inParams . La valeur spécifiée doit être un multiple de 8 qui n'est pas supérieur à la longueur du résumé ni inférieur à la valeur de Tag::MIN_MAC_LENGTH dans les autorisations de clé. Pour les longueurs MAC supérieures à la longueur du résumé ou non multiples de 8, renvoyez ErrorCode::UNSUPPORTED_MAC_LENGTH . Pour les valeurs inférieures à la longueur minimale de la clé, renvoyez ErrorCode::INVALID_MAC_LENGTH .

mettre à jour

Variantes : 1, 2, 3

Fournit des données à traiter dans une opération en cours démarrée avec begin . L'opération est spécifiée par le paramètre operationHandle .

Pour fournir plus de flexibilité pour la gestion des tampons, les implémentations de cette méthode ont la possibilité de consommer moins de données que celles fournies. L'appelant est responsable de la boucle pour alimenter le reste des données dans les appels suivants. La quantité d'entrée consommée est renvoyée dans le paramètre inputConsumed . Les implémentations consomment toujours au moins un octet, à moins que l'opération ne puisse en accepter plus ; si plus de zéro octets sont fournis et que zéro octets sont consommés, les appelants considèrent qu'il s'agit d'une erreur et abandonnent l'opération.

Les implémentations peuvent également choisir la quantité de données à renvoyer, à la suite de la mise à jour. Ceci n'est pertinent que pour les opérations de chiffrement et de déchiffrement, car la signature et la vérification ne renvoient aucune donnée avant finish . Renvoyez les données le plus tôt possible, plutôt que de les mettre en mémoire tampon.

La gestion des erreurs

Si cette méthode renvoie un code d'erreur autre que ErrorCode::OK , l'opération est abandonnée et le descripteur d'opération est invalidé. Toute utilisation future du handle, avec cette méthode, finish , ou abort , renvoie ErrorCode::INVALID_OPERATION_HANDLE .

Application de l'autorisation

L'application de l'autorisation de clé est effectuée principalement dans begin . La seule exception est le cas où la clé a :

Dans ce cas, la clé nécessite une autorisation par opération, et la méthode de mise à jour reçoit un Tag::AUTH_TOKEN dans l'argument inParams . HMAC vérifie que le jeton est valide et contient un ID utilisateur sécurisé correspondant, correspond à la clé Tag::USER_AUTH_TYPE et contient le descripteur d'opération de l'opération en cours dans le champ challenge. Si ces conditions ne sont pas remplies, renvoyez ErrorCode::KEY_USER_NOT_AUTHENTICATED .

L'appelant fournit le jeton d'authentification à chaque appel pour mettre à jour et terminer . L'implémentation n'a besoin de valider le jeton qu'une seule fois si elle le souhaite.

Clés RSA

Pour les opérations de signature et de vérification avec Digest::NONE , cette méthode accepte que le bloc entier soit signé ou vérifié en une seule mise à jour. Il ne peut consommer qu'une partie du bloc. Cependant, si l'appelant choisit de fournir les données dans plusieurs mises à jour, cette méthode l'accepte. Si l'appelant fournit plus de données à signer qu'il n'est possible d'en utiliser (la longueur des données dépasse la taille de la clé RSA), renvoyez ErrorCode::INVALID_INPUT_LENGTH .

Clés ECDSA

Pour les opérations de signature et de vérification avec Digest::NONE , cette méthode accepte que le bloc entier soit signé ou vérifié en une seule mise à jour. Cette méthode ne peut consommer qu'une partie du bloc.

Cependant, si l'appelant choisit de fournir les données dans plusieurs mises à jour, cette méthode l'accepte. Si l'appelant fournit plus de données à signer qu'il n'est possible d'en utiliser, les données sont tronquées en silence. (Cela diffère de la gestion des données excédentaires fournies dans des opérations RSA similaires. La raison en est la compatibilité avec les clients hérités.)

Clés AES

Le mode AES GCM prend en charge les "données d'authentification associées", fournies via la balise Tag::ASSOCIATED_DATA dans l'argument inParams . Les données associées peuvent être fournies dans des appels répétés (important si les données sont trop volumineuses pour être envoyées en un seul bloc) mais précèdent toujours les données à chiffrer ou à déchiffrer. Un appel de mise à jour peut recevoir à la fois des données associées et des données à chiffrer/déchiffrer, mais les mises à jour ultérieures peuvent ne pas inclure de données associées. Si l'appelant fournit des données associées à un appel de mise à jour après un appel qui inclut des données à chiffrer/déchiffrer, renvoyez ErrorCode::INVALID_TAG .

Pour le chiffrement GCM, la balise est ajoutée au texte chiffré par finish . Lors du déchiffrement, le dernier Tag::MAC_LENGTH octets des données fournies au dernier appel de mise à jour est le tag. Puisqu'une invocation donnée de update ne peut pas savoir s'il s'agit de la dernière invocation, elle traite tout sauf la longueur de la balise et met en mémoire tampon les données de balise possibles pendant finish .

terminer

Variantes : 1, 2, 3

Termine une opération en cours commencée par begin , en traitant toutes les données non encore traitées fournies par update (s).

This method is the last one called in an operation, so all processed data is returned.

Whether it completes successfully or returns an error, this method finalizes the operation and therefore invalidates the provided operation handle. Any future use of the handle, with this method or update or abort , returns ErrorCode::INVALID_OPERATION_HANDLE .

Signing operations return the signature as the output. Verification operations accept the signature in the signature parameter, and return no output.

Authorization enforcement

Key authorization enforcement is performed primarily in begin . The one exception is the case where the key has:

In this case, the key requires an authorization per operation, and the update method receives a Tag::AUTH_TOKEN in the inParams argument. HMAC verifies that the token is valid and contains a matching secure user ID, matches the key's Tag::USER_AUTH_TYPE , and contains the operation handle of the current operation in the challenge field. If these conditions aren't met, return ErrorCode::KEY_USER_NOT_AUTHENTICATED .

The caller provides the authentication token to every call to update and finish . The implementation need only validate the token once if it prefers.

RSA keys

Some additional requirements, depending on the padding mode:

  • PaddingMode::NONE . For unpadded signing and encryption operations, if the provided data is shorter than the key, the data is be zero-padded on the left before signing/encryption. If the data is the same length as the key, but numerically larger, return ErrorCode::INVALID_ARGUMENT . For verification and decryption operations, the data must be exactly as long as the key. Otherwise, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . For PSS-padded signature operations, the PSS salt is the size of the message digest and randomly generated. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and as the MGF1 digest algorithm.
  • PaddingMode::RSA_OAEP . The digest specified with Tag::DIGEST in inputParams on begin is used as the OAEP digest algorithm, and SHA1 is used as the MGF1 digest algorithm.

ECDSA keys

If the data provided for unpadded signing or verification is too long, truncate it.

AES keys

Some additional conditions, depending on block mode:

  • BlockMode::ECB or BlockMode::CBC . If padding is PaddingMode::NONE and the data length is not a multiple of the AES block size, return ErrorCode::INVALID_INPUT_LENGTH . If padding is PaddingMode::PKCS7 , pad the data per the PKCS#7 specification. Note that PKCS#7 recommends adding an additional padding block if the data is a multiple of the block length.
  • BlockMode::GCM . During encryption, after processing all plaintext, compute the tag ( Tag::MAC_LENGTH bytes) and append it to the returned ciphertext. During decryption, process the last Tag::MAC_LENGTH bytes as the tag. If tag verification fails, return ErrorCode::VERIFICATION_FAILED .

abort

Version : 1, 2, 3

Aborts the in-progress operation. After the call to abort, return ErrorCode::INVALID_OPERATION_HANDLE for any subsequent use of the provided operation handle with update , finish , or abort .

get_supported_algorithms

Version : 1

Returns the list of algorithms supported by the Keymaster hardware implementation. A software implementation returns an empty list; a hybrid implementation returns a list containing only the algorithms that are supported by hardware.

Keymaster 1 implementations support RSA, EC, AES and HMAC.

get_supported_block_modes

Version : 1

Returns the list of AES block modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

For RSA, EC and HMAC, which are not block ciphers, the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

Keymaster 1 implementations support ECB, CBC, CTR and GCM for AES encryption and decryption.

get_supported_padding_modes

Version : 1

Returns the list of padding modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

HMAC and EC have no notion of padding so the method returns an empty list for all valid purposes. Invalid purposes should cause the method to return ErrorCode::INVALID_PURPOSE .

For RSA, Keymaster 1 implementations support:

  • Unpadded encryption, decryption, signing and verification. For unpadded encryption and signing, if the message is shorter than the public modulus, implementations must left-pad it with zeros. For unpadded decryption and verification, the input length must match the public modulus size.
  • PKCS#1 v1.5 encryption and signing padding modes
  • PSS with a minimum salt length of 20
  • OAEP

For AES in ECB and CBC modes, Keymaster 1 implementations support no padding and PKCS#7-padding. CTR and GCM modes support only no padding.

get_supported_digests

Version : 1

Returns the list of digest modes supported by the Keymaster hardware implementation for a specified algorithm and purpose.

No AES modes support or require digesting, so the method returns an empty list for valid purposes.

Keymaster 1 implementations can implement a subset of the defined digests. Implementations provide SHA-256 and can provide MD5, SHA1, SHA-224, SHA-256, SHA384 and SHA512 (the full set of defined digests).

get_supported_import_formats

Version : 1

Returns the list of import formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster 1 implementations support the PKCS#8 format (without password protection) for importing RSA and EC key pairs, and support RAW import of AES and HMAC key material.

get_supported_export_formats

Version : 1

Returns the list of export formats supported by the Keymaster hardware implementation of a specified algorithm.

Keymaster1 implementations support the X.509 format for exporting RSA and EC public keys. Export of private keys or asymmetric keys is not supported.

Historical functions

Keymaster 0

The following functions belong to the original Keymaster 0 definition. They were present in Keymaster 1 struct keymaster1_device_t. However, in Keymaster 1.0 they were not implemented, and their function pointers were set to NULL.

  • generate_keypair
  • import_keypair
  • get_keypair_public
  • delete_keypair
  • delete_all
  • sign_data
  • Verify_data

Keymaster 1

The following functions belong to the Keymaster 1 definition, but were removed in Keymaster 2, along with the Keymaster 0 functions listed above.

  • get_supported_algorithms
  • get_supported_block_modes
  • get_supported_padding_modes
  • get_supported_digests
  • get_supported_import_formats
  • get_supported_export_formats

Keymaster 2

The following functions belong to the Keymaster 2 definition, but were removed in Keymaster 3, along with the Keymaster 1 functions listed above.

  • configure