Google s'est engagé à promouvoir l'équité raciale pour les communautés noires. Regarde comment.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

Fonctions Keymaster

Cette page fournit des détails pour aider les implémenteurs de Keymaster Hardware Abstraction Layers (HAL). Il couvre chaque fonction de l'API et dans quelle version de Keymaster cette fonction est disponible et décrit l'implémentation par défaut. Pour les tags, consultez la page Keymaster Tags .

Directives générales de mise en œuvre

Les instructions 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 obligé 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 commencer , 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 obligatoire 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 référence valeur ou const.

Paramètres du pointeur de sortie

Version : 1, 2

Similaire aux 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 référence valeur ou const.

Mauvaise utilisation de l'API

Version : 1, 2, 3

Il existe de nombreuses façons dont les appelants peuvent faire des demandes qui n'ont aucun sens ou qui sont stupides mais pas techniquement fausses. Les implémentations de Keymaster ne sont pas obligées 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 inutile) et autres ne devraient pas être diagnostiquées par les implémentations. L'omission des paramètres requis, la spécification des paramètres requis invalides et des erreurs similaires doivent être diagnostiquées.

Il est de la responsabilité des applications, du framework et du keystore 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 Elliptic Curve avec les courbes NIST (P-224, P-256, P-384 et P-521).
  • supportsSymmetricCryptography true si le matériel prend en charge la cryptographie symétrique, y compris AES et HMAC.
  • supportsAttestation 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 de l'appareil et avant son utilisation. Il est utilisé pour fournir KM_TAG_OS_VERSION et KM_TAG_OS_PATCHLEVEL au 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 fois par démarrage. Les appels suivants renvoient KM_ERROR_OK , mais ne font rien.

Si l'implémentation de keymaster est dans un matériel sécurisé et que la version du système d'exploitation et les valeurs de niveau de correctif 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

Version : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 en tant que 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 de Keymaster doivent mélanger en toute sécurité l'entropie fournie dans leur pool, qui doit également contenir une 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 manière à ce qu'un attaquant qui ait le contrôle complet soit des bits addRngEntropy soit des bits générés par le matériel, mais pas les deux, n'ait aucun avantage non négligeable à prédire les bits générés à partir du pool d'entropie.

Les implémentations de 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 de Keymaster peuvent retourner ErrorCode::INVALID_INPUT_LENGTH si elles reçoivent plus de 2 Kio de données en un seul appel.

generateKey

Version : 1, 2, 3

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

Génère une nouvelle clé cryptographique, 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 à garantir 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. En outre, les caractéristiques renvoyées par generateKey attribuent correctement les autorisations entre les listes appliquées par le matériel et les logiciels. Voir getKeyCharacteristics pour plus de détails.

Les paramètres fournis pour generateKey dépendent du type de clé en cours de génération. 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. En cas d'omission, 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. En cas d'omission, 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 clés renvoyées. En effet, la clé est utilisable avec ces autres résumés, mais la digestion est effectuée dans un logiciel. Ensuite, le matériel est appelé pour effectuer l'opération avec Digest::NONE .
  • Tag :: PADDING spécifie les modes de remplissage 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 placer PaddingMode::RSA_PSS et PaddingMode::RSA_OAEP dans la liste des caractéristiques clés appliquées par logiciel 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 les courbes NIST p-224, p-256, p-384 et p521, respectivement.

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

Clés AES

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

Les paramètres suivants sont particulièrement pertinents pour les clés AES, mais ne sont 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 bloc GCM est spécifié, fournissez le Tag :: MIN_MAC_LENGTH . En cas d'omission, la méthode renvoie ErrorCode::MISSING_MIN_MAC_LENGTH . La valeur de la balise est un multiple de 8 et 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 plus élevées peuvent être prises en charge.
  • Tag :: MIN_MAC_LENGTH spécifie la longueur minimale des MAC qui peuvent être générées ou vérifiées avec cette clé. La valeur est un multiple de 8 et d'au moins 64.
  • Tag :: DIGEST spécifie l'algorithme de résumé de la clé. Un seul condensé est spécifié, sinon renvoie ErrorCode::UNSUPPORTED_DIGEST . Si le condensé 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 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 afin qu'il ne soit pas possible de trouver leurs valeurs en examinant l'objet blob de clé renvoyé. Cependant, ils sont liés de manière cryptographique à l'objet 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 lié de manière cryptographique à la clé, mais il peut ne pas être spécifié lors de la création ou de l'importation de la clé et n'est jamais retourné.

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

Balise :: ROLLBACK_RESISTANT .

Résistance au retour

La résistance au retour en arrière signifie qu'une fois qu'une clé est supprimée avec deleteKey ou deleteAllKeys , elle est garantie par un matériel sécurisé qu'elle ne sera plus jamais utilisable. Les implémentations sans résistance au retour arrière renvoient généralement les éléments de clé générés ou importés à l'appelant sous forme de blob de clés, un formulaire chiffré et authentifié. Lorsque le magasin de clés supprime l'objet 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 le périphérique.

Une clé résiste à 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

Version : 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 logiciel. La description ici s'applique également aux listes de caractéristiques clés renvoyées par generateKey et importKey .

Si Tag::APPLICATION_ID é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 é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 balise donnée appartient à la liste appliquée par matériel ou par logiciel est que si la signification de la balise 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 qui sont prises en charge par le matériel sécurisé sont placées dans la liste de matériel pris en charge. Les résumés non pris en charge vont dans la liste des logiciels pris en charge.
  • Les valeurs de Tag :: PADDING vont généralement dans la liste matérielle, sauf s'il y a une possibilité qu'un mode de remplissage spécifique doive être exécuté par le logiciel. Dans ce cas, ils vont dans la liste des logiciels appliqués. Une telle possibilité se présente pour les clés RSA qui permettent un remplissage PSS ou OAEP avec des algorithmes de résumé qui ne sont pas pris en charge par le matériel sécurisé.
  • Les balises :: USER_SECURE_ID et Tag :: USER_AUTH_TYPE sont appliquées 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 approprié doivent tous deux être sécurisés et partager une clé HMAC secrète utilisée pour signer et valider les jetons d'authentification. Consultez la page Authentification pour plus de détails.
  • Tag :: ACTIVE_DATETIME , Tag :: ORIGINATION_EXPIRE_DATETIME et Tag :: USAGE_EXPIRE_DATETIME balises doivent avoir accès à une horloge murale correcte vérifiable. La plupart du matériel sécurisé n'a accès qu'aux informations de temps 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 sauvegardée par le matériel.

importKey

Version : 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 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:

  • 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 la clé. Si les paramètres sont fournis, le trustlet les valide par rapport au matériel clé. En cas de non-concordance, la méthode renvoie ErrorCode::IMPORT_PARAMETER_MISMATCH .
  • Le Tag :: ORIGIN retourné a la même valeur que KeyOrigin::IMPORTED .

exportKey

Version : 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 é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 é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 en tant que 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 fournissent une résistance au retour arrière.

deleteAllKeys

Version : 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 fournissent une résistance au retour arrière.

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 garantir que l'attestation d'ID est définitivement désactivée après l'appel de cette méthode, l'attestation d'ID ne doit pas du tout être implémentée, 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 définitivement toutes les futures tentatives d'attestation d'ID. La méthode peut être appelée un nombre illimité de fois. Si l'attestation d'ID est déjà désactivée définitivement, 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

Version : 1, 2, 3

Commence une opération cryptographique, en utilisant la clé spécifiée, dans le but spécifié, avec les paramètres spécifiés (le cas échéant), et retourne un handle d'opération qui est utilisé avec la mise à jour et la fin pour terminer l'opération. Le descripteur d'opération est également utilisé comme jeton «défi» 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. Keystore en utilise jusqu'à 15, en laissant un à vold à utiliser pour le cryptage des mots de passe. Lorsque Keystore a 15 opérations en cours ( begin a été appelé, mais finish ou abort n'ont pas encore été appelés) et qu'il reçoit une demande pour commencer un 16e, il appelle abort sur l'opération la moins récemment utilisée pour réduire le nombre d'opérations actives à 14 avant d'appeler, begin la nouvelle opération 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é, les appels pour begin incluent ces balises avec les valeurs spécifiées à l'origine dans l'argument inParams de cette méthode.

Application des autorisations

Pendant 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, c'est-à-dire 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 satisfaites.

  • Tag :: BUT : 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 retournera ErrorCode::UNSUPPORTED_PURPOSE . Les opérations de clé publique sont des opérations de chiffrement ou de vérification asymétriques.
  • La balise :: ACTIVE_DATETIME ne peut être appliquée que si une source d'heure UTC approuvée 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 d'heure 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 retourne ErrorCode::KEY_EXPIRED .
  • La balise :: USAGE_EXPIRE_DATETIME ne peut être appliquée que si une source d'heure UTC approuvée 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 retourne ErrorCode::KEY_EXPIRED .
  • Tag :: MIN_SECONDS_BETWEEN_OPS est comparé à un temporisateur relatif de confiance 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 . Consultez la description de la balise pour obtenir des détails importants sur la mise en œuvre.
  • 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, toutes les conditions suivantes doivent être remplies:
    • 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 vecteur nonce ou 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 retourné.
  • Tag :: BOOTLOADER_ONLY spécifie que seul le chargeur de démarrage peut utiliser la clé. Si cette méthode est appelée avec une clé de chargeur de démarrage uniquement une fois que le chargeur de démarrage a terminé son exécution, 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 . Si non spécifié ou spécifié plus d'une 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 condensé dans inParams . Si non spécifié ou spécifié plus d'une 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 condensé et de 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 s'appliquent 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 retourne 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 condensé. Aucun résumé n'est nécessaire pour le chiffrement ou le déchiffrement non rembourré.
  • PaddingMode::RSA_PKCS1_1_5_SIGN remplissage nécessite un condensé. Le condensé peut être Digest::NONE , auquel cas l'implémentation Keymaster ne peut pas construire une structure de signature PKCS # 1 v1.5 correcte, 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 au moins 11 octets plus grande que le message, sinon la méthode retourne ErrorCode::INVALID_INPUT_LENGTH .
  • PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT remplissage ne nécessite pas de résumé.
  • PaddingMode::RSA_PSS padding 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 . En outre, la taille de la clé RSA doit être au moins 2 + D octets plus grande que 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 du sel est D.
  • PaddingMode::RSA_OAEP padding nécessite un condensé, qui peut ne pas être Digest::NONE . Si Digest::NONE est spécifié, la méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST .

Clés EC

Les opérations sur les touches EC spécifient exactement un mode de remplissage dans inParams . Si non spécifié ou spécifié plus d'une 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. Sinon, 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 sur les touches 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 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 retourne 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 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 répond 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 de Keymaster génère un IV ou nonce aléatoire 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 , alors 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é, retournez ErrorCode::CALLER_NONCE_PROHIBITED . Si un nonce n'est pas fourni lorsque Tag :: CALLER_NONCE est autorisé, générer 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é ou inférieur à la valeur de Tag::MIN_MAC_LENGTH dans les autorisations de clé. Pour les longueurs MAC supérieures à la longueur de 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

Version : 1, 2, 3

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

Pour offrir 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 ce qui était fourni. 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, sauf si l'opération ne peut plus en accepter; si plus de zéro octet sont fournis et que zéro octet est consommé, les appelants considèrent cela comme une erreur et abandonnent l'opération.

Les implémentations peuvent également choisir la quantité de données à renvoyer, suite à 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 jusqu'à la fin . 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, terminer ou abandonner , retourne ErrorCode::INVALID_OPERATION_HANDLE .

Application des autorisations

L'application des autorisations de clé est effectuée principalement au début . 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 à Tag :: USER_AUTH_TYPE de la clé et contient le descripteur d' opération 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 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 que ce qui peut être utilisé (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 que ce qui peut être utilisé, les données sont tronquées silencieusement. (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 lors d'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 à crypter / décrypter, mais les mises à jour ultérieures peuvent ne pas inclure les données associées. Si l'appelant fournit des données associées à un appel de mise à jour après un appel qui comprend des données à chiffrer / déchiffrer, renvoyez ErrorCode::INVALID_TAG .

For GCM encryption, the tag is appended to the ciphertext by finish . During decryption, the last Tag::MAC_LENGTH bytes of the data provided to the last update call is the tag. Since a given invocation of update cannot know if it's the last invocation, it processes all but the tag length and buffer the possible tag data during finish .

finish

Version : 1, 2, 3

Finishes an ongoing operation started with begin , processing all of the as-yet-unprocessed data provided by 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 at least 20 bytes in length and randomly generated. The salt may be longer; the reference implementation uses maximally sized salt. The digest specified with Tag::DIGEST in inputParams on begin is used as the PSS digest algorithm, and SHA1 is used 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