Fonctions Keymaster

Cette page fournit des informations pour aider les implémentateurs des couches d'abstraction matérielle (HAL) Keymaster. Il présente chaque fonction de l'API et la version de Keymaster dans laquelle cette fonction est disponible, et décrit la mise en œuvre par défaut. Pour en savoir plus sur les balises, consultez la page Balises Keymaster.

Consignes générales d'implémentation

Les consignes 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 d'espaces réservés. Par exemple, certains types et modes de clé peuvent ne pas utiliser de valeurs de l'argument inParams pour commencer. L'appelant peut donc définir inParams sur NULL ou fournir un ensemble 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 obligatoire est NULL, les méthodes Keymaster doivent renvoyer ErrorCode::UNEXPECTED_NULL_POINTER.

À partir de Keymaster 3, il n'y a plus de paramètres de pointeur. Tous les paramètres sont transmis par valeur ou par référence 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 défini sur NULL, elle doit renvoyer ErrorCode::OUTPUT_PARAMETER_NULL.

À partir de Keymaster 3, il n'y a plus de paramètres de pointeur. Tous les paramètres sont transmis par valeur ou par référence const.

Usage abusif de l'API

Version: 1, 2, 3

Les appelants peuvent effectuer de nombreuses requêtes qui n'ont pas de sens ou qui sont stupides, mais qui ne sont pas techniquement incorrectes. Les implémentations Keymaster ne sont pas tenues d'échouer dans de tels cas ni d'émettre de 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 obligatoires, la spécification de paramètres obligatoires non valides et les erreurs similaires doivent être diagnostiquées.

Il incombe aux applications, au framework et à Android Keystore de s'assurer que les appels aux modules Keymaster sont pertinents et utiles.

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 comporte 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 les quittent jamais.
  • supportsEllipticCurve est true si le matériel est compatible avec la cryptographie à courbe elliptique avec les courbes NIST (P-224, P-256, P-384 et P-521).
  • supportsSymmetricCryptography est true si le matériel est compatible avec la cryptographie symétrique, y compris AES et HMAC.
  • supportsAttestation est défini sur true si le matériel est compatible avec 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 la 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 abandonnée 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 keymaster. Cette méthode est 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 Keymaster est effectuée sur du matériel sécurisé et que les valeurs de version d'OS et de niveau de correctif fournies ne correspondent pas à celles fournies au matériel sécurisé par le bootloader (ou si le bootloader ne fournit pas de valeurs), cette méthode renvoie KM_ERROR_INVALID_ARGUMENT. Toutes les autres 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

Version: 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom 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, des clés, des IV, etc.

Les implémentations Keymaster doivent mélanger de manière sécurisée l'entropie fournie dans leur pool, qui doit également contenir de 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 pirate informatique qui contrôle complètement les bits fournis par addRngEntropy ou les bits générés par le matériel, mais pas les deux, n'ait aucun avantage non négligeable pour 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.

generateKey

Version: 1, 2, 3

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

Génère une nouvelle clé cryptographique, en spécifiant les autorisations associées, qui sont définitivement liées à la clé. Les implémentations Keymaster rendent impossible l'utilisation d'une clé de manière incohérente 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 non exécutables 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 matériel et par logiciel. Pour en savoir plus, consultez getKeyCharacteristics.

Les paramètres fournis à generateKey dépendent du type de clé générée. Cette section récapitule 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 elle est omise, la méthode renvoie ErrorCode::UNSUPPORTED_KEY_SIZE. Les valeurs acceptées sont 1 024, 2 048, 3 072 et 4 096. Les valeurs recommandées sont toutes les tailles de clé qui sont un multiple de 8.
  • Tag::RSA_PUBLIC_EXPONENT spécifie la valeur d'exposant public RSA. Si elle est omise, la méthode renvoie ErrorCode::INVALID_ARGUMENT. Les valeurs acceptées sont 3 et 65 537. Les valeurs recommandées sont toutes les valeurs premiers 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 génère une clé inutilisable. Toutefois, la fonction generateKey ne renvoie pas d'erreur si ces paramètres sont omis.

  • Tag::PURPOSE spécifie les finalités autorisées. Tous les objectifs doivent être compatibles avec les clés RSA, dans n'importe quelle combinaison.
  • Tag::DIGEST spécifie les algorithmes de condensé pouvant être utilisés avec la nouvelle clé. Les implémentations qui ne sont pas compatibles avec tous les algorithmes de condensé doivent accepter les requêtes de génération de clé qui incluent des condensés non compatibles. Les récapitulatifs non compatibles doivent être placés dans la liste "Software-enforced" (Applications logicielles) dans les caractéristiques de clé renvoyées. En effet, la clé est utilisable avec ces autres récapitulatifs, mais la récapitulation est effectuée par logiciel. Le matériel est ensuite appelé pour effectuer l'opération avec Digest::NONE.
  • Tag::PADDING spécifie les modes de marge intérieure pouvant être utilisés avec la nouvelle clé. Les implémentations qui ne sont pas compatibles avec tous les algorithmes de condensé doivent placer PaddingMode::RSA_PSS et PaddingMode::RSA_OAEP dans la liste des caractéristiques de clé appliquée par le logiciel si des algorithmes de condensé non compatibles sont spécifiés.

Clés ECDSA

Seul Tag::KEY_SIZE est nécessaire pour générer une clé ECDSA. Il permet de sélectionner le groupe EC. Les valeurs acceptées sont 224, 256, 384 et 521, qui correspondent respectivement aux 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 obligatoire pour la génération.

Clés AES

Seul Tag::KEY_SIZE est nécessaire pour générer une clé AES. Si elle est omise, la méthode renvoie ErrorCode::UNSUPPORTED_KEY_SIZE. Les valeurs acceptées sont 128 et 256. Les clés AES 192 bits sont facultatives.

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 pouvant être utilisés. Cela n'est pertinent que pour les modes ECB et CBC.

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

Clés HMAC

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

  • Tag::KEY_SIZE spécifie la taille de la clé en bits. Les valeurs inférieures à 64 et celles qui ne sont pas des multiples de 8 ne sont pas acceptées. Tous les multiples de 8, de 64 à 512, sont acceptés. Des valeurs plus élevées peuvent être acceptées.
  • Tag::MIN_MAC_LENGTH spécifie la longueur minimale des adresses MAC pouvant être générées ou validées avec cette clé. La valeur est un multiple de 8 et au moins 64.
  • Tag::DIGEST spécifie l'algorithme de condensé de la clé. Un seul condensé est spécifié. Sinon, renvoyez ErrorCode::UNSUPPORTED_DIGEST. Si le récapitulatif n'est pas compatible avec le trustlet, renvoyez ErrorCode::UNSUPPORTED_DIGEST.

Principales caractéristiques

Si l'argument "characteristics" n'est pas NULL, generateKey renvoie les caractéristiques de la clé nouvellement générée, divisées en listes appliquées par matériel et par logiciel. Consultez getKeyCharacteristics pour obtenir une description des caractéristiques à placer dans chaque liste. Les caractéristiques renvoyées incluent tous les paramètres spécifiés pour la génération de clés, à l'exception de Tag::APPLICATION_ID et Tag::APPLICATION_DATA. Si ces balises ont été incluses dans les paramètres de clé, elles sont supprimées des caractéristiques renvoyées afin qu'il ne soit pas possible de trouver leurs valeurs en examinant le blob de clé renvoyé. Toutefois, elles sont liées de manière cryptographique au blob de clé. Par conséquent, 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 lié de manière cryptographique à 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 au rollback,

Tag::ROLLBACK_RESISTANT.

Résistance au rollback

La résistance au rollback signifie qu'une fois qu'une clé est supprimée avec deleteKey ou deleteAllKeys, elle est garantie par un matériel sécurisé qui ne pourra plus jamais être réutilisée. Les implémentations sans résistance au rollback renvoient généralement le matériel de clé généré ou importé à l'appelant sous la forme d'un blob de clé, un formulaire chiffré et authentifié. Lorsque le keystore supprime le blob de clé, la clé disparaît, mais un pirate informatique qui a déjà réussi à récupérer le matériel de clé peut potentiellement le restaurer sur l'appareil.

Une clé est résistante au rollback si le matériel sécurisé garantit que les clés supprimées ne peuvent pas être restaurées ultérieurement. Pour ce faire, il est généralement nécessaire de stocker des métadonnées de clé supplémentaires dans un emplacement sécurisé qui ne peut pas être manipulé par un pirate informatique. Sur les appareils mobiles, le mécanisme utilisé est généralement les blocs de mémoire protégés contre la relecture (RPMB, Replay Protected Memory Blocks). Étant donné que le nombre de clés pouvant être créées est essentiellement illimité et que la taille de l'espace de stockage sécurisé utilisé pour la résistance au rollback peut être limitée, cette méthode doit réussir même si la résistance au rollback ne peut pas être fournie pour la nouvelle clé. Dans ce cas, Tag::ROLLBACK_RESISTANT ne doit pas être ajouté aux principales caractéristiques.

getKeyCharacteristics

Version: 1, 2, 3

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

Renvoie les paramètres et les autorisations associés à la clé fournie, répartis en deux ensembles: les paramètres matériels et ceux appliqués par logiciel. La description ci-dessous s'applique également aux listes de caractéristiques de clé 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.

En règle générale, si la signification d'un tag est entièrement garantie par du matériel sécurisé, il s'agit d'un tag appliqué par le matériel. Sinon, il est appliqué par logiciel. Vous trouverez ci-dessous une liste de balises spécifiques dont l'affectation correcte risque de 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 matériel, ces balises figurent dans la liste des balises appliquées par le matériel.
  • Les valeurs Tag::DIGEST compatibles avec le matériel sécurisé sont placées dans la liste des valeurs matérielles compatibles. Les récapitulatifs non compatibles figurent dans la liste des logiciels compatibles.
  • Les valeurs Tag::PADDING figurent généralement dans la liste des valeurs matérielles, sauf si un mode de remplissage spécifique doit être exécuté par un logiciel. Dans ce cas, elles sont ajoutées à la liste des applications appliquées par logiciel. Cette possibilité se produit pour les clés RSA qui autorisent le remplissage PSS ou OAEP avec des algorithmes de condensé qui ne sont pas compatibles avec le matériel sécurisé.
  • Tag::USER_SECURE_ID et Tag::USER_AUTH_TYPE ne sont appliqués en mode matériel que si l'authentification de l'utilisateur est appliquée en mode 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. Pour en savoir plus, consultez la page Authentification.
  • Les balises Tag::ACTIVE_DATETIME, Tag::ORIGINATION_EXPIRE_DATETIME et Tag::USAGE_EXPIRE_DATETIME nécessitent l'accès à une horloge murale valide. La plupart du matériel sécurisé n'a accès qu'aux informations temporelles fournies par le système d'exploitation non sécurisé, ce qui signifie que les tags sont appliqués par logiciel.
  • Tag::ORIGIN figure toujours dans la liste du matériel pour les clés liées au matériel. Sa présence dans cette liste permet aux couches supérieures de déterminer qu'une clé est intégrée au matériel.

cléimportation

Version: 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom import_key et a été 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 traités de la même manière que pour generateKey, avec les exceptions suivantes:

  • Les tags 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. Si aucune valeur n'est fournie, le trustlet déduit les valeurs du matériel de clé fourni et ajoute les balises et valeurs appropriées aux caractéristiques clés. 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.
  • La valeur Tag::ORIGIN renvoyée est la même que celle de KeyOrigin::IMPORTED.

exportKey

Version: 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom export_key et a été 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

Version: 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom delete_key et a été 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 au rollback.

deleteAllKeys

Version: 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom 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 au rollback.

destroyAttestationIds

Version: 3

La méthode destroyAttestationIds() permet de désactiver définitivement la nouvelle fonctionnalité d'attestation d'ID (facultative, mais vivement recommandée). Si le TEE n'a aucun moyen de s'assurer que l'attestation d'identité est définitivement désactivée après l'appel de cette méthode, l'attestation d'identité 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'identité est prise en charge, cette méthode doit être implémentée et doit désactiver définitivement toutes les futures tentatives d'attestation d'identité. La méthode peut être appelée autant de fois que nécessaire. Si l'attestation d'identité 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'identité n'est pas prise en charge), ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED ou l'un des codes d'erreur indiquant un échec de la communication avec le matériel sécurisé.

begin

Version: 1, 2, 3

Démarre une opération cryptographique à l'aide de la clé spécifiée, pour l'objectif spécifié, avec les paramètres spécifiés (le cas échéant), et renvoie un gestionnaire d'opération utilisé avec update et finish pour terminer l'opération. Le handle d'opération est également utilisé comme jeton de "défi" dans les opérations authentifiées. Pour ces opérations, il 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 keystore utilise jusqu'à 15 clés, laissant une clé à vold pour le chiffrement des mots de passe. Lorsque Keystore gère 15 opérations en cours (begin a été appelé, mais finish ou abort n'ont pas été appelés) et qu'il reçoit une requête pour en démarrer une 16e, il appelle abort sur l'opération la moins utilisée récemment pour réduire le nombre d'opérations actives à 14 avant d'appeler begin 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 clés, les appels à begin incluent ces balises avec les valeurs spécifiées à l'origine dans l'argument inParams de cette méthode.

Application des autorisations

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 de clé publique. Les opérations de clé publique, à savoir KeyPurpose::ENCRYPT et KeyPurpose::VERIFY, avec des clés RSA ou EC, sont autorisées à réussir même si les exigences d'autorisation ne sont pas remplies.

  • Tag::PURPOSE: l'objectif spécifié dans l'appel begin() doit correspondre à l'un des objectifs des autorisations de clé, sauf si l'opération demandée est une opération de 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 renvoie ErrorCode::UNSUPPORTED_PURPOSE. Les opérations de clé publique sont des opérations de chiffrement ou de validation 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.
  • Tag::ORIGINATION_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::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 minuteur relatif fiable indiquant la dernière utilisation de la clé. Si l'heure de la dernière utilisation plus la valeur de la balise est inférieure à l'heure actuelle, la méthode renvoie ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Pour en savoir plus sur l'implémentation, consultez la description de la balise.
  • 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 n'est appliqué par cette méthode que si la clé possède également Tag::AUTH_TIMEOUT. Si la clé possède les deux, cette méthode doit recevoir un Tag::AUTH_TOKEN valide dans inParams. Pour que le jeton d'authentification soit valide, toutes les conditions suivantes doivent être remplies :
    • Le champ HMAC est validé correctement.
    • Au moins l'une des valeurs Tag::USER_SECURE_ID de la clé correspond à au moins l'une des valeurs d'ID sécurisé du jeton.
    • La clé possède un Tag::USER_AUTH_TYPE qui correspond au type d'authentification du 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é ne comporte pas cette balise, mais que l'appelant a fourni Tag::NONCE à cette méthode, ErrorCode::CALLER_NONCE_PROHIBITED est renvoyé.
  • Tag::BOOTLOADER_ONLY indique que seul le bootloader peut utiliser la clé. Si cette méthode est appelée avec une clé réservée au bootloader une fois l'exécution du bootloader terminée, elle renvoie ErrorCode::INVALID_KEY_BLOB.

Clés RSA

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

Les opérations de signature et de validation RSA nécessitent un condensé, tout comme les opérations de chiffrement et de déchiffrement RSA avec le mode de remplissage OAEP. Dans ce cas, l'appelant spécifie exactement un condensé dans inParams. Si cette valeur n'est pas spécifiée ou est spécifiée plusieurs fois, la méthode renvoie ErrorCode::UNSUPPORTED_DIGEST.

Les opérations de clé privée (KeyPurpose::DECYPT et KeyPurpose::SIGN) nécessitent l'autorisation du récapitulatif et du remplissage, ce qui signifie que les autorisations de clé doivent contenir les valeurs spécifiées. Sinon, 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 condensé 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 validation, 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é n'est pas compatible avec l'objectif spécifié.

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

  • PaddingMode::NONE indique qu'une opération RSA "brute" est effectuée. Si vous signez ou validez, Digest::NONE est spécifié pour le récapitulatif. Aucun récapitulatif n'est nécessaire pour le chiffrement ou le déchiffrement sans remplissage.
  • La marge intérieure de PaddingMode::RSA_PKCS1_1_5_SIGN nécessite un condensé. Le condensé peut être Digest::NONE. Dans ce cas, l'implémentation de 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. À la place, 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.
  • Le remplissage PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT ne nécessite pas de récapitulatif.
  • Le remplissage PaddingMode::RSA_PSS nécessite un récapitulatif, qui ne peut pas être Digest::NONE. Si Digest::NONE est spécifié, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST. En outre, la taille de la clé RSA doit être supérieure d'au moins 2 + D octets à la taille de sortie du condensé, où D est la taille du condensé, en octets. Sinon, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST. La taille de sel est D.
  • Le remplissage pour PaddingMode::RSA_OAEP nécessite un condensé, qui ne peut pas être Digest::NONE. Si Digest::NONE est spécifié, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST.

Clés EC

Les opérations de clé EC spécifient exactement un seul mode de remplissage dans inParams. Si cette valeur n'est pas spécifiée ou spécifiée plusieurs fois, la méthode renvoie ErrorCode::UNSUPPORTED_PADDING_MODE.

Les opérations de clé privée (KeyPurpose::SIGN) nécessitent l'autorisation du récapitulatif et du 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 condensé ou un remplissage non autorisé.

Clés AES

Les opérations de clé AES spécifient exactement un mode de bloc et un mode de remplissage dans inParams. Si l'une des valeurs n'est pas spécifiée ou est spécifiée plusieurs fois, renvoyez 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 blocage 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 ni inférieur à la valeur de Tag::MIN_MAC_LENGTH dans les autorisations de clé. Pour les longueurs MAC supérieures à 128 ou les 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 marge 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 un nonce est nécessaire. Dans la plupart des cas, les appelants ne doivent pas fournir d'IV ni de nonce. Dans ce cas, l'implémentation Keymaster génère un IV ou un nonce aléatoire et le renvoie avec Tag::NONCE dans outParams. Les IV CBC et CTR sont de 16 octets. Les nonces GCM font 12 octets. Si les autorisations de clé contiennent Tag::CALLER_NONCE, l'appelant peut fournir un vecteur d'initialisation ou un nonce avec Tag::NONCE dans inParams. Si un nonce est fourni lorsque Tag::CALLER_NONCE n'est pas autorisé, renvoyez ErrorCode::CALLER_NONCE_PROHIBITED. Si aucun nonce n'est 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 condensé ni inférieur à la valeur de Tag::MIN_MAC_LENGTH dans les autorisations de clé. Pour les longueurs MAC supérieures à la longueur du condensé ou des 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

Version: 1, 2, 3

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

Pour plus de flexibilité dans la gestion des tampons, les implémentations de cette méthode peuvent consommer moins de données que celles fournies. L'appelant est chargé de boucler 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, sauf si l'opération ne peut pas en accepter plus. Si plus de zéro octet est fourni et qu'aucun octet n'est consommé, 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. Cela n'est pertinent que pour les opérations de chiffrement et de déchiffrement, car la signature et la validation ne renvoient aucune donnée jusqu'à la fin de l'opération finish. Renvoyez les données le plus tôt possible, plutôt que de les mettre en mémoire tampon.

Gestion des exceptions

Si cette méthode renvoie un code d'erreur autre que ErrorCode::OK, l'opération est interrompue et le gestionnaire d'opération est invalidé. Toute utilisation future de la poignée, avec cette méthode, finish ou abort, renvoie ErrorCode::INVALID_OPERATION_HANDLE.

Application des autorisations

L'application de l'autorisation des clés est principalement effectuée dans begin. La seule exception concerne les cas où la clé comporte:

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 qu'il contient un ID utilisateur sécurisé correspondant, correspond au paramètre Tag::USER_AUTH_TYPE de la clé et contient le handle de l'opération en cours dans le champ de défi. Si ces conditions ne sont pas remplies, renvoyez ErrorCode::KEY_USER_NOT_AUTHENTICATED.

L'appelant fournit le jeton d'authentification à chaque appel d'actualisation et de finalisation. 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 validation avec Digest::NONE, cette méthode accepte que l'ensemble du bloc soit signé ou validé en une seule mise à jour. Il ne peut pas consommer qu'une partie du bloc. Toutefois, si l'appelant choisit de fournir les données en plusieurs mises à jour, cette méthode les accepte. Si l'appelant fournit plus de données à signer que celles pouvant être utilisées (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 validation avec Digest::NONE, cette méthode accepte que l'ensemble du bloc soit signé ou validé en une seule mise à jour. Cette méthode ne peut pas consommer qu'une partie du bloc.

Toutefois, si l'appelant choisit de fournir les données en plusieurs mises à jour, cette méthode les accepte. Si l'appelant fournit plus de données à signer que celles pouvant être utilisées, les données sont tronquées de manière silencieuse. (Cela diffère de la gestion des données excédentaires fournies dans des opérations RSA similaires. Cela est dû à la compatibilité avec les anciens clients.)

Clés AES

Le mode AES GCM accepte 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 dans un seul bloc), mais elles 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 ne peuvent 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 incluant 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, les derniers Tag::MAC_LENGTH octets des données fournies au dernier appel de mise à jour correspondent à la balise. Étant donné qu'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 la finalisation.

terminer

Version: 1, 2, 3

Termine une opération en cours lancée avec begin, en traitant toutes les données non traitées fournies par les mises à jour.

Cette méthode est la dernière appelée dans une opération. Toutes les données traitées sont donc renvoyées.

Que l'opération aboutisse ou renvoie une erreur, cette méthode finalise l'opération et invalide donc le gestionnaire d'opération fourni. Toute utilisation future du handle, avec cette méthode ou update (mise à jour) ou abort (abandon), renvoie ErrorCode::INVALID_OPERATION_HANDLE.

Les opérations de signature renvoient la signature en sortie. Les opérations de validation acceptent la signature dans le paramètre signature et ne renvoient aucune sortie.

Application des autorisations

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

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, qu'il correspond à la Tag::USER_AUTH_TYPE de la clé et qu'il contient le handle de l'opération actuelle dans le champ de défi. Si ces conditions ne sont pas remplies, renvoyez ErrorCode::KEY_USER_NOT_AUTHENTICATED.

L'appelant fournit le jeton d'authentification à chaque appel de mise à jour et de fin. L'implémentation ne doit valider le jeton qu'une seule fois, si elle le souhaite.

Clés RSA

Voici quelques exigences supplémentaires, en fonction du mode de marge intérieure:

  • PaddingMode::NONE. Pour les opérations de signature et de chiffrement sans remplissage, si les données fournies sont plus courtes que la clé, elles sont complétées par zéro à gauche avant la signature/le chiffrement. Si les données ont la même longueur que la clé, mais sont numériquement plus grandes, la fonction renvoie ErrorCode::INVALID_ARGUMENT. Pour les opérations de validation et de déchiffrement, les données doivent être exactement aussi longues que la clé. Sinon, renvoyez ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS. Pour les opérations de signature avec remplissage PSS, le sel PSS correspond à la taille du récapitulatif du message et est généré de manière aléatoire. Le condensé spécifié avec Tag::DIGEST dans inputParams sur begin est utilisé comme algorithme de condensé PSS et comme algorithme de condensé MGF1.
  • PaddingMode::RSA_OAEP. Le condensé spécifié avec Tag::DIGEST dans inputParams au début est utilisé comme algorithme de condensé OAEP, et SHA1 est utilisé comme algorithme de condensé MGF1.

Clés ECDSA

Si les données fournies pour la signature ou la validation sans remplissage sont trop longues, les tronquer.

Clés AES

Voici quelques conditions supplémentaires, en fonction du mode de blocage:

  • BlockMode::ECB ou BlockMode::CBC. Si le remplissage est PaddingMode::NONE et que la longueur des données n'est pas un multiple de la taille de bloc AES, renvoyez ErrorCode::INVALID_INPUT_LENGTH. Si le remplissage est PaddingMode::PKCS7, remplissez les données conformément à la spécification PKCS#7. Notez que PKCS#7 recommande d'ajouter un bloc de remplissage supplémentaire si les données sont un multiple de la longueur du bloc.
  • BlockMode::GCM. Pendant le chiffrement, après le traitement de tout le texte brut, calculez le tag (Tag::MAC_LENGTH octets) et ajoutez-le au texte chiffré renvoyé. Lors du déchiffrement, traitez les derniers octets Tag::MAC_LENGTH comme la balise. Si la validation du tag échoue, renvoyez ErrorCode::VERIFICATION_FAILED.

abort

Version: 1, 2, 3

Annule l'opération en cours. Après l'appel pour abandonner, renvoyez ErrorCode::INVALID_OPERATION_HANDLE pour toute utilisation ultérieure du handle d'opération fourni avec update, finish ou abort.

get_supported_algorithms

Version: 1

Renvoie la liste des algorithmes compatibles avec l'implémentation matérielle Keymaster. Une implémentation logicielle renvoie une liste vide. Une implémentation hybride renvoie une liste contenant uniquement les algorithmes compatibles avec le matériel.

Les implémentations de Keymaster 1 sont compatibles avec RSA, EC, AES et HMAC.

get_supported_block_modes

Version: 1

Renvoie la liste des modes de bloc AES compatibles avec l'implémentation matérielle Keymaster pour un algorithme et un objectif spécifiés.

Pour RSA, EC et HMAC, qui ne sont pas des algorithmes de chiffrement par bloc, la méthode renvoie une liste vide pour toutes les utilisations valides. Les objectifs non valides doivent entraîner le retour de ErrorCode::INVALID_PURPOSE par la méthode.

Les implémentations de Keymaster 1 sont compatibles avec ECB, CBC, CTR et GCM pour le chiffrement et le déchiffrement AES.

get_supported_padding_modes

Version: 1

Renvoie la liste des modes de remplissage compatibles avec l'implémentation matérielle Keymaster pour un algorithme et un objectif spécifiés.

HMAC et EC n'ont aucune notion de remplissage. La méthode renvoie donc une liste vide pour toutes les utilisations valides. Les objectifs non valides doivent entraîner le renvoi de ErrorCode::INVALID_PURPOSE par la méthode.

Pour RSA, les implémentations Keymaster 1 prennent en charge:

  • Chiffrement, déchiffrement, signature et validation sans remplissage. Pour le chiffrement et la signature sans remplissage, si le message est plus court que le module public, les implémentations doivent le remplir à gauche avec des zéros. Pour les opérations de déchiffrement et de vérification sans remplissage, la longueur de l'entrée doit correspondre à la taille du module public.
  • Modes de remplissage de chiffrement et de signature PKCS#1 v1.5
  • PSS avec une longueur de salage minimale de 20
  • OAEP

Pour AES en modes ECB et CBC, les implémentations Keymaster 1 ne prennent pas en charge le remplissage et le remplissage PKCS#7. Les modes CTR et GCM n'acceptent qu'aucune marge intérieure.

get_supported_digests

Version: 1

Renvoie la liste des modes de récapitulatif compatibles avec l'implémentation matérielle Keymaster pour un algorithme et un objectif spécifiés.

Aucun mode AES n'est compatible ni requis pour la synthèse. Par conséquent, la méthode renvoie une liste vide à des fins valides.

Les implémentations de Keymaster 1 peuvent implémenter un sous-ensemble des condensés définis. Les implémentations fournissent la norme SHA-256 et peuvent fournir MD5, SHA1, SHA-224, SHA-256, SHA384 et SHA512 (l'ensemble complet des condensés définis).

get_supported_import_formats

Version: 1

Renvoie la liste des formats d'importation compatibles avec l'implémentation matérielle Keymaster d'un algorithme spécifié.

Les implémentations de Keymaster 1 prennent en charge le format PKCS#8 (sans protection par mot de passe) pour l'importation de paires de clés RSA et EC, et acceptent l'importation RAW du matériel de clé AES et HMAC.

get_supported_export_formats

Version: 1

Renvoie la liste des formats d'exportation compatibles avec l'implémentation matérielle Keymaster d'un algorithme spécifié.

Les implémentations Keymaster1 sont compatibles avec le format X.509 pour l'exportation des clés publiques RSA et EC. L'exportation de clés privées ou de clés asymétriques n'est pas prise en charge.

Fonctions historiques

Keymaster 0

Les fonctions suivantes appartiennent à la définition d'origine de Keymaster 0. Ils étaient présents dans la structure keymaster1_device_t de Keymaster 1. Cependant, dans Keymaster 1.0, ils n'étaient pas implémentés et leurs pointeurs de fonction étaient définis sur NULL.

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

Keymaster 1

Les fonctions suivantes appartiennent à la définition de Keymaster 1, mais ont été supprimées dans Keymaster 2, ainsi que les fonctions Keymaster 0 listées ci-dessus.

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

Keymaster 2

Les fonctions suivantes appartiennent à la définition de Keymaster 2, mais ont été supprimées dans Keymaster 3, ainsi que les fonctions Keymaster 1 listées ci-dessus.

  • configure