Fonctions Keymaster,Fonctions Keymaster

Cette page fournit des détails pour aider les implémenteurs de couches d'abstraction matérielles (HAL) Keymaster. 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 Balises Keymaster .

Directives 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 commencer , l'appelant peut donc 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 aucun paramètre 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

Semblables 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é comme étant NULL , elle doit renvoyer ErrorCode::OUTPUT_PARAMETER_NULL .

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

Utilisation abusive de l'API

Versions : 1, 2, 3

Il existe de nombreuses façons pour les appelants de formuler des demandes qui n'ont aucun sens ou qui sont insensées mais qui ne sont pas techniquement fausses. Il n’est pas nécessaire que les implémentations Keymaster échouent dans de tels cas ou émettent un diagnostic. L'utilisation de clés trop petites, la spécification de paramètres d'entrée non pertinents, la réutilisation de IV ou de noms occasionnels, 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 des 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 keystore Android de garantir que les appels aux modules Keymaster sont judicieux 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 est true si le matériel prend en charge la cryptographie symétrique, notamment AES et HMAC.
  • supportsAttestation est 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 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 du système d'exploitation et 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), alors 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);

addRngEntropie

Versions : 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 de 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 matériel de nombres aléatoires. Le mixage doit être géré de manière à ce qu'un attaquant qui a le contrôle complet soit des bits fournis par addRngEntropy , soit des bits générés par le matériel, mais pas des deux, n'ait aucun avantage non négligeable dans la prédiction des 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é

Versions : 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 sous le nom 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 de manière permanente à la clé. Les implémentations 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, afin 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 matérielles et logicielles. 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. En cas d'omission, la méthode renvoie ErrorCode::UNSUPPORTED_KEY_SIZE . Les valeurs prises en charge sont 1 024, 2 048, 3 072 et 4 096. Les valeurs recommandées correspondent à 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 créer 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, quelle que soit leur 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 par 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 logicielle 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 permet de 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. En cas d'omission, 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 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 ne concerne que les modes ECB et CBC.

Si le mode de 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 du tag est un multiple de 8 et compris 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é 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 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 matérielles et logicielles. 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 le blob de clé renvoyé. Cependant, ils sont liés cryptographiquement au blob de clé, de sorte que si les valeurs correctes ne sont pas fournies lors de l’utilisation de la clé, l’utilisation échoue. De même, Tag::ROOT_OF_TRUST est lié cryptographiquement à 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,

Balise ::ROLLBACK_RESISTANT .

Résistance au retour en arrière

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é qu'elle ne sera plus jamais utilisable. Les implémentations sans résistance au rollback renvoient généralement les éléments de clé générés ou importés à l'appelant sous la forme d'un blob de clé, un formulaire chiffré et authentifié. Lorsque le magasin de clés supprime le blob de clé, la clé disparaît, mais un attaquant qui a déjà réussi à récupérer le matériel de clé peut potentiellement le restaurer sur l'appareil.

Une clé résiste à la restauration si le matériel sécurisé garantit que les clés supprimées ne peuvent 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 fiable qui ne peut pas être manipulé par un attaquant. Sur les appareils mobiles, le mécanisme utilisé à cet effet est généralement le Replay Protected Memory Blocks (RPMB). Étant donné que le nombre de clés pouvant être créées est essentiellement illimité et que le stockage fiable utilisé pour la résistance à la restauration peut être de taille limitée, 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

Versions : 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 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 balise donnée appartient à la liste matérielle ou logicielle est que si la signification de la balise est entièrement assurée par un matériel sécurisé, elle est matériellement appliquée. 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 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 du matériel pris en charge. Les résumés non pris en charge figurent dans la liste des logiciels pris en charge.
  • Les valeurs de Tag::PADDING vont généralement dans la liste matérielle prise en charge, à moins qu'il soit possible qu'un mode de remplissage spécifique doive être exécuté par logiciel. Dans ce cas, ils vont dans la liste imposée par le 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 correspondant 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 est vérifiable. 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 indique la manière dont les couches supérieures déterminent qu'une clé est sauvegardée sur du matériel.

clé d'importation

Versions : 1, 2, 3

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

Importe les éléments clés 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 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 renvoyé a la même valeur que KeyOrigin::IMPORTED .

clé d'exportation

Versions : 1, 2, 3

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

Supprimer la clé

Versions : 1, 2, 3

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

supprimerTouteslesClés

Versions : 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() est utilisée pour désactiver définitivement la nouvelle fonctionnalité d'attestation d'identité (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, alors 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'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 plusieurs fois. Si l’attestation d’identité est déjà définitivement désactivée, 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'identification 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

Versions : 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 renvoie un handle 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 de « défi » dans les opérations authentifiées, et pour de telles 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. Keystore en utilise jusqu'à 15, en laissant un à vold pour le cryptage du mot 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 en commencer une 16ème, 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 pour begin 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é, les appels pour begin incluent ces balises avec les valeurs initialement spécifiées 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 de clé publique. Les opérations de clé publique, c'est-à-dire KeyPurpose::ENCRYPT et KeyPurpose::VERIFY , avec des clés RSA ou EC, peuvent 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 indiqués dans les 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 renverra ErrorCode::UNSUPPORTED_PURPOSE . Les opérations de 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 .
  • 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 ulté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 ulté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 de confiance indiquant la dernière utilisation de la clé. Si la durée 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 les détails importants de 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é possède 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 est correctement validé.
    • 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 nom occasionnel 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 chargeur de démarrage peut utiliser la clé. Si cette méthode est appelée avec une clé réservée au chargeur de démarrage une fois l'exécution du chargeur de démarrage terminée, elle renvoie ErrorCode::INVALID_KEY_BLOB .

Clés RSA

Toutes les opérations sur les touches RSA spécifient exactement un mode de remplissage dans inParams . Si elle 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 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 . Si elle 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 une autorisation de résumé 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 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 prennent uniquement en charge la signature et la vérification, tandis que PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT et PaddingMode::RSA_OAEP prennent uniquement en charge le cryptage 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 non complété.
  • Le remplissage PaddingMode::RSA_PKCS1_1_5_SIGN nécessite un résumé. Le résumé peut être Digest::NONE , auquel 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. 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 d'au moins 11 octets supérieure à 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é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 d'au moins 2 + D octets supérieure à 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 sur les touches EC spécifient exactement un mode de remplissage dans inParams . Si elle 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 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 résumé 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 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 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 un nom occasionnel est nécessaire. Dans la plupart des cas, les appelants ne doivent pas fournir d'intraveineuse ou d'occasion. 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 CBC et CTR IV font 16 octets. Les noms occasionnels GCM font 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 nom occasionnel est fourni lorsque Tag::CALLER_NONCE n'est pas autorisé, renvoyez 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 sur les touches 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é ou 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 .

mise à jour

Versions : 1, 2, 3

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

Pour offrir plus de flexibilité dans 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 du bouclage pour alimenter le reste des données lors des appels ultérieurs. 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 davantage ; si plus de zéro octet est fourni 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 handle 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 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 au Tag::USER_AUTH_TYPE de la clé et contient le handle 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 préfère.

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 pas consommer seulement une partie du bloc. Toutefois, si l’appelant choisit de fournir les données dans plusieurs mises à jour, cette méthode les 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 pas consommer seulement une partie du bloc.

Toutefois, si l’appelant choisit de fournir les données dans plusieurs mises à jour, cette méthode les accepte. Si l’appelant fournit plus de données à signer qu’il ne peut en utiliser, 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 existants.)

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 à 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 incluant des données à chiffrer/déchiffrer, renvoyez ErrorCode::INVALID_TAG .

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

finition

Versions : 1, 2, 3

Termine une opération en cours commencée avec start , en traitant toutes les données non encore traitées fournies par la ou les mises à jour .

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

Qu'il termine avec succès ou renvoie une erreur, cette méthode finalise l'opération et invalide donc la poignée de fonctionnement fournie. Toute utilisation future de la poignée, avec cette méthode ou mise à jour ou abandonne , renvoie ErrorCode::INVALID_OPERATION_HANDLE .

Les opérations de signature renvoient la signature comme sortie. Les opérations de vérification acceptent la signature dans le paramètre signature et ne renvoient aucune sortie.

Application de l'autorisation

L'application de l'autorisation 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 une balise :: auth_token dans l'argument inParams . HMAC vérifie que le jeton est valide et contient un ID utilisateur sécurisé correspondant, correspond à la balise de la clé :: user_auth_type et contient la poignée de fonctionnement de l'opération actuelle dans le champ Challenge. Si ces conditions ne sont pas remplies, retournez 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 que de valider le jeton une fois s'il préfère.

Clés RSA

Quelques exigences supplémentaires, selon le mode de rembourrage:

  • PaddingMode::NONE . Pour les opérations de signature et de chiffrement non rembourrées, si les données fournies sont plus courtes que la clé, les données sont zéro padées sur la gauche avant la signature / le cryptage. Si les données sont de la même longueur que la clé, mais numériquement plus grande, retournez ErrorCode::INVALID_ARGUMENT . Pour les opérations de vérification et de décryptage, les données doivent être exactement aussi longues que la clé. Sinon, return ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS . Pour les opérations de signature PSS-Padded, le sel PSS est de la taille du digestion du message et généré au hasard. Le digest spécifié avec TAG :: Digest dans inputParams au début est utilisé comme algorithme de digest PSS et comme algorithme de digest MGF1.
  • PaddingMode::RSA_OAEP . Le digest spécifié avec TAG :: Digest dans inputParams au début est utilisé comme algorithme OAEP Digest, et SHA1 est utilisé comme algorithme de digest MGF1.

Ecdsa Keys

Si les données fournies pour la signature ou la vérification non rembourrée sont trop longues, tronquez-la.

Clés AES

Quelques conditions supplémentaires, selon le mode bloc:

  • BlockMode::ECB ou BlockMode::CBC . Si le padding est PaddingMode::NONE et la longueur des données n'est pas un multiple de la taille du bloc AES, retournez ErrorCode::INVALID_INPUT_LENGTH . Si le padding est PaddingMode::PKCS7 , remplissez les données selon la spécification PKCS # 7. Notez que PKCS # 7 recommande d'ajouter un bloc de rembourrage 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 texte en clair, calculez la balise ( balise :: mac_length bytes) et ajoutez-la au chiffre d'affaires renvoyé. Pendant le décryptage, traitez la dernière balise :: mac_length octets comme balise. Si la vérification de la balise échoue, return ErrorCode::VERIFICATION_FAILED .

avorter

Version : 1, 2, 3

Abandonne l'opération en cours. Après l'appel pour abandonner, renvoyez ErrorCode::INVALID_OPERATION_HANDLE pour toute utilisation ultérieure de la poignée de fonctionnement fournie avec mise à jour , finition ou avort .

get_supported_algorithms

Version 1

Renvoie la liste des algorithmes pris en charge par l'implémentation du matériel KeyMaster. Une implémentation logicielle renvoie une liste vide; Une implémentation hybride renvoie une liste ne contenant que les algorithmes pris en charge par le matériel.

Les implémentations de KeyMaster 1 prennent en charge RSA, EC, AES et HMAC.

get_supported_block_modes

Version 1

Renvoie la liste des modes de blocs AES pris en charge par l'implémentation du matériel KeyMaster pour un algorithme et un objectif spécifié.

Pour RSA, EC et HMAC, qui ne sont pas des chiffres de blocs, la méthode renvoie une liste vide à toutes fins valides. Les objectifs non valides devraient faire en sorte que la méthode renvoie ErrorCode::INVALID_PURPOSE .

Les implémentations de KeyMaster 1 prennent en charge la BEC, CBC, CTR et GCM pour le cryptage et le déchiffrement AES.

get_supported_padding_modes

Version 1

Renvoie la liste des modes de rembourrage pris en charge par l'implémentation du matériel KeyMaster pour un algorithme et un objectif spécifié.

HMAC et EC n'ont aucune notion de rembourrage, donc la méthode renvoie une liste vide à toutes fins valides. Les objectifs non valides devraient faire en sorte que la méthode renvoie ErrorCode::INVALID_PURPOSE .

Pour RSA, le support des implémentations KeyMaster 1:

  • Cryptage, décryptage, signature et vérification non. Pour le cryptage et la signature non todés, si le message est plus court que le module public, les implémentations doivent le faire à gauche avec des zéros. Pour le décryptage et la vérification non battus, la longueur d'entrée doit correspondre à la taille du module public.
  • PKCS # 1 V1.5 MODES DE CRYPTION ET DE SIGNAGE
  • PSS avec une longueur de sel minimale de 20
  • Oaep

Pour les AES dans les modes ECB et CBC, les implémentations KeyMaster 1 ne prennent pas en charge sans rembourrage et PKCS # 7-padding. Les modes CTR et GCM ne prennent en charge qu'aucun rembourrage.

get_supported_digests

Version 1

Renvoie la liste des modes de digest pris en charge par l'implémentation du matériel KeyMaster pour un algorithme et un objectif spécifié.

Aucun modes AES ne prend en charge ou ne nécessite pas de digestion, donc la méthode renvoie une liste vide à des fins valides.

Les implémentations de KeyMaster 1 peuvent implémenter un sous-ensemble des digestions définis. Les implémentations fournissent le SHA-256 et peuvent fournir MD5, Sha1, SHA-224, SHA-256, SHA384 et SHA512 (l'ensemble complet de digests définis).

get_supported_import_formats

Version 1

Renvoie la liste des formats d'importation pris en charge par l'implémentation du matériel KeyMaster d'un algorithme spécifié.

Les implémentations 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 prennent en charge l'importation brute de matériaux clés AES et HMAC.

get_supported_export_formats

Version 1

Renvoie la liste des formats d'exportation pris en charge par la mise en œuvre du matériel KeyMaster d'un algorithme spécifié.

Les implémentations KeyMaster1 prennent en charge 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 KeyMaster 0. Ils étaient présents dans Keymaster 1 struct keymaster1_device_t. Cependant, dans Keymaster 1.0, ils n'ont pas été mis en œuvre et leurs pointeurs de fonction ont été mis en œuvre.

  • 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 énuméré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 énumérées ci-dessus.

  • configure