Fonctions Keymaster

Cette page fournit des informations pour aider les responsables de la mise en œuvre de Keymaster Couches d'abstraction matérielle (HAL) Il aborde chaque fonction de l'API, la version de Keymaster dans laquelle cette fonction est disponible, ainsi que décrit l'implémentation par défaut. Pour les tags, consultez la Page Keymaster Tags (Tags Keymaster).

Consignes générales de mise en œuvre

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 des espaces réservés. Par exemple, il est possible que certains types de clés et certains modes n'utilisent aucune valeur issue du l'argument inParams sur begin, afin que l'appelant puisse définissez inParams sur NULL ou fournissez un paramètre vide. défini. Les appelants peuvent également fournir des paramètres inutilisés, et les méthodes Keymaster doivent ne génèrent pas d'erreurs.

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

À partir de Keymaster 3, il n'existe aucun paramètre de pointeur. Tous les paramètres sont transmises par des références "value" 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 peut être NULL. Si une méthode doit renvoyer des données dans une sortie est NULL, il doit renvoyer ErrorCode::OUTPUT_PARAMETER_NULL

À partir de Keymaster 3, il n'existe aucun paramètre de pointeur. Tous les paramètres sont transmises par des références "value" ou "const".

Usage abusif de l'API

Version: 1, 2, 3

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

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

Fonctions

getHardwareFeatures

Version: 3

La nouvelle méthode getHardwareFeatures expose aux clients les caractéristiques importantes du matériel sécurisé sous-jacent. La méthode n'accepte 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 de ne jamais le laisser.
  • supportsEllipticCurve est true si le le matériel est compatible avec la cryptographie sur les courbes elliptiques avec les courbes NIST (P-224, P-256, P-384 et P-521).
  • "supportsSymmetricCryptography" est "true" si le matériel prend en charge la cryptographie symétrique, y compris AES et HMAC.
  • supportsAttestation est true si le le matériel prend en charge la génération de certificats d'attestation de clé publique Keymaster, signé 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 est obsolète dans Keymaster 3, car ces informations sont disponibles dans les fichiers de propriétés système. Le fabricant les implémentations 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 de les utiliser. Il est utilisé pour fournir KM_TAG_OS_VERSION et KM_TAG_OS_PATCHLEVEL jusqu'à 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 ce ne sont acceptées par keymaster qu'une seule fois par démarrage. Suivant les appels renvoient KM_ERROR_OK, mais ne font rien.

Si l'implémentation de keymaster se trouve dans du matériel sécurisé, et si la version du système d'exploitation et les valeurs de niveau de correctif fournies ne correspondent pas aux valeurs fournies au par le bootloader (ou si le bootloader ne fournit pas de valeurs), cette méthode renvoie KM_ERROR_INVALID_ARGUMENT, et 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 en tant que add_rng_entropy. et renommé 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, des clés, des vecteurs d'initialisation, etc.

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

Les implémentations Keymaster qui tentent d'estimer l'entropie dans leur d'un pool interne partent du principe que les données addRngEntropy ne contient aucune entropie. Les implémentations de Keymaster peuvent renvoie ErrorCode::INVALID_INPUT_LENGTH s'ils reçoivent plus de 2 Kio de données dans un seul appel.

generateKey

Version: 1, 2, 3

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

Génère une nouvelle clé cryptographique, en spécifiant les autorisations associées, qui sont liés de façon permanente à la clé. Les implémentations de Keymaster permettent impossible d'utiliser une clé incompatible avec les autorisations spécifié au moment de la génération. En ce qui concerne les autorisations que le matériel ne peut pas exiger, l'obligation de sécuriser le matériel est limitée garantissant que les autorisations non applicables associées à la clé ne peuvent pas de sorte que chaque appel à la fonction getKeyCharacteristics renvoie la valeur d'origine. De plus, les caractéristiques renvoyées par generateKey alloue correctement les autorisations entre les les listes appliquées par matériel et par logiciel. Voir getKeyCharacteristics pour en savoir plus.

Les paramètres fournis à generateKey dépendent du type de clé en cours de génération. Cette section récapitule les tags nécessaires et facultatifs pour chaque type de clé. Tag::ALGORITHME 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 acceptées sont 1024, 2048, 3072 et 4096. Valeurs recommandées sont toutes des tailles de clé qui sont un multiple de 8.
  • Tag::RSA_PUBLIC_EXPONENT spécifie la valeur d'exposant public RSA. En cas d'omission, 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 elle génère une clé inutilisable. Toutefois, La fonction generateKey ne renvoie pas d'erreur si ces paramètres sont omises.

  • Tag::PURPOSE spécifie aux fins autorisées. Toutes les finalités doivent être prises en charge pour les clés RSA, toute combinaison.
  • Tag::DIGEST spécifie de condensé qui peuvent être utilisés avec la nouvelle clé. Implémentations qui ne sont pas compatibles avec tous les algorithmes de condensé doivent accepter la génération de clés qui incluent des condensés non compatibles. Les condensés non pris en charge doivent être placée dans la catégorie "Application dans la liste des caractéristiques clés renvoyées. En effet, la clé est utilisable avec ces autres condensés, mais le condensé effectuées dans un logiciel. Le matériel est ensuite appelé pour effectuer l'opération avec Digest::NONE.
  • Tag::PADDING spécifie de remplissage qui peuvent être utilisés avec la nouvelle clé. Implémentations compatibles avec tous les algorithmes de condensé doivent placer PaddingMode::RSA_PSS et PaddingMode::RSA_OAEP dans la liste appliquée par logiciel des principales caractéristiques, le cas échéant sont spécifiés.

Clés ECDSA

Seul le paramètre Tag::KEY_SIZE est 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 indiquent Courbes NIST p-224, p-256, p-384 et p521, respectivement.

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

Clés AES

Tag::KEY_SIZE uniquement pour générer une clé AES. Si cette valeur est omise, la méthode renvoie ErrorCode::UNSUPPORTED_KEY_SIZE Les valeurs acceptées sont 128 et 256, avec prise en charge facultative des clés AES 192 bits.

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

  • 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 marge intérieure pouvant être utilisé. Cela ne s'applique qu'aux modes ECB et CBC.

Si le mode de blocage GCM est spécifié, indiquez le 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 générer une clé HMAC:

  • Tag::KEY_SIZE spécifie la taille de la clé en bits. Valeurs inférieures à 64 Les valeurs qui ne sont pas des multiples de 8 ne sont pas acceptées. Tout Les multiples de 8 (de 64 à 512) sont acceptés. Les valeurs supérieures peuvent être compatibles.
  • Tag::MIN_MAC_LENGTH spécifie la longueur minimale MAC qui peuvent être générés ou vérifiés avec cette clé. Cette valeur est une multiple de 8 et d'au moins 64.
  • Tag::DIGEST spécifie l'algorithme de condensé de la clé. Exactement un condensé est spécifié, sinon renvoie ErrorCode::UNSUPPORTED_DIGEST Si le condensé n'est pas compatible par le trustlet, renvoie ErrorCode::UNSUPPORTED_DIGEST

Principales caractéristiques

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

En plus des tags fournis, le trustlet ajoute Tag::ORIGIN, avec la valeur KeyOrigin::GENERATED, et si la clé est résistante aux rollbacks,

Tag::ROLLBACK_RESISTANT.

Résistance au rollback

La résistance au rollback signifie qu'une fois qu'une clé est supprimée deleteKey ou deleteAllKeys, elle est garantie par du matériel sécurisé. pour ne plus jamais être utilisables. En général, les implémentations qui ne résistent pas au rollback renvoyer le matériel de clé généré ou importé à l'appelant sous la forme d'un blob de clé, une sous forme chiffrée et authentifiée. Lorsque le keystore supprime le blob de clé, la clé est disparu, mais un attaquant qui a précédemment réussi à récupérer le matériel de clé peut potentiellement le restaurer sur l’appareil.

Une clé résiste au rollback si le matériel sécurisé garantit que la suppression vous ne pourrez pas les restaurer par la suite. Cela se fait généralement en stockant des clés supplémentaires des métadonnées dans un emplacement de confiance qui ne peut pas être manipulé par un attaquant. Activé les appareils mobiles, le mécanisme utilisé pour cela est généralement la mémoire protégée de relecture Blocs (RPMB). Comme vous pouvez créer un nombre de clés et le stockage fiable utilisé pour la résistance au rollback peut être limité de taille, 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 doivent pas être ajoutées aux caractéristiques clés.

getKeyCharacteristics

Version: 1, 2, 3

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

Renvoie les paramètres et les autorisations associés à la clé fournie. se divise en deux ensembles: les contraintes matérielles et les contraintes logicielles. La description 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 de la clé ou importation, la même valeur est fournie cette méthode dans l'argument clientId. Dans le cas contraire, renvoie ErrorCode::INVALID_KEY_BLOB. De même, si Tag::APPLICATION_DATA a été fourni lors de la génération ou 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 de manière exhaustive le type de la clé spécifiée.

Règle générale pour déterminer si un tag donné appartient au d'application forcée par logiciel ou par matériel est que, si la signification du tag est entièrement assurée par du matériel sécurisé, elle est appliquée au niveau du matériel. Sinon, il est par logiciel. Vous trouverez ci-dessous une liste de balises spécifiques peuvent ne pas être claires:

  • Tag::ALGORITHME, Tag::KEY_SIZE, et Tag::RSA_PUBLIC_EXPONENT sont les propriétés intrinsèques de la clé. Pour toute clé sécurisée par le matériel, ces balises figureront dans la liste des applications appliquées par le matériel.
  • Valeurs Tag::DIGEST pris en charge par le matériel sécurisé sont placés liste des appareils compatibles. Les récapitulatifs non compatibles figurent dans la liste des logiciels compatibles.
  • Valeurs Tag::PADDING figurent généralement dans la liste des appareils compatibles, sauf s'il existe il se peut qu'un mode de remplissage spécifique doive être exécuté par un logiciel. Dans ce cas, elles sont ajoutées à la liste des applications appliquées par logiciel. Une telle possibilité survient pour les clés RSA qui autorisent le remplissage PSS ou OAEP avec des algorithmes de condensé qui ne sont pas prises en charge par le matériel sécurisé.
  • Balise : USER_SECURE_ID et Tag::USER_AUTH_TYPE ne sont appliquées par le matériel que si l'authentification de l'utilisateur est assurée par le matériel. À le trustlet Keymaster et l'authentification adéquate le trustlet 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 le Authentification.
  • Tag::ACTIVE_DATETIME, Balise : ORIGINATION_EXPIRE_DATETIME, et les balises Tag::USAGE_EXPIRE_DATETIME ont besoin d'accéder à une horloge murale vérifiable. Matériel le plus 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 est toujours dans la liste du matériel pour les clés liées au matériel. Sa présence dans ce est la façon dont les couches supérieures déterminent qu'une clé est intégrée au matériel.

cléimportation

Version: 1, 2, 3

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

Importe le matériel de clé dans le matériel Keymaster. Les paramètres de définition des clés les caractéristiques de sortie sont traitées de la même manière que pour generateKey, à quelques exceptions près:

  • 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 à partir du matériel de clé fourni et ajoute les balises et les valeurs appropriées aux caractéristiques clés. Si les paramètres sont fourni, le trustlet les valide par rapport au matériel de clé. Dans d'une non-concordance, la méthode renvoie ErrorCode::IMPORT_PARAMETER_MISMATCH.
  • La valeur Tag::ORIGIN renvoyée comporte le paramètre la même valeur que KeyOrigin::IMPORTED.

Clé d'exportation

Version: 1, 2, 3

Cette fonction a été introduite dans Keymaster 1 en tant que export_key. et renommé 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 de la clé ou , la même valeur est fournie à cette méthode dans le l'argument clientId. Sinon, elle renvoie ErrorCode::INVALID_KEY_BLOB De même, si Tag::APPLICATION_DATA a été fournie 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é dans Keymaster 3.

Supprime la clé fournie. Cette méthode est facultative et n'est implémentés par des modules Keymaster qui offrent une résistance au rollback.

deleteAllKeys

Version: 1, 2, 3

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

Supprime toutes les clés. Cette méthode est facultative et n'est implémentée par des modules Keymaster qui offrent une résistance au rollback.

destroyAttestationIds

Version: 3

La méthode destroyAttestationIds() permet de supprimer définitivement désactiver le nouveau (facultatif, mais vivement recommandé) Attestation d'identité . Si le TEE n'a aucun moyen de s'assurer que l'attestation d'identité est désactivée après l'appel de cette méthode, l'attestation d'ID ne doit pas être n'est pas implémentée, auquel cas cette méthode n'a aucun effet et renvoie ErrorCode::UNIMPLEMENTED. Si l'attestation d'ID est compatible, cette méthode doit être implémentée et doit désactiver définitivement toutes les futures tentatives d'attestation d'ID. Cette méthode peut être appelée n'importe quel nombre fois. Si l'attestation d'ID est déjà désactivée de manière permanente, la méthode 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 disponible) ; ErrorCode:OK, ErrorCode::KEYMASTER_NOT_CONFIGURED ou l'un des codes d'erreur indiquant un échec de communication avec le matériel.

begin

Version: 1, 2, 3

Lance une opération de chiffrement à l'aide de la clé spécifiée, pour la valeur avec les paramètres spécifiés (le cas échéant), et renvoie une poignée d'opération utilisé avec update et finish pour terminer l'opération. Le handle d'opération est également utilisé comme le « défi » dans les opérations authentifiées. est incluse dans le champ challenge du un jeton d'authentification unique.

Une implémentation Keymaster accepte au moins 16 instances simultanées opérations. Keystore utilise jusqu'à 15 enregistrements, dont un que Vold peut utiliser comme mot de passe le chiffrement. Lorsque 15 opérations keystore sont en cours (begin a ont été appelées, mais que finish ou abort n'ont pas encore été et reçoit une requête pour commencer un 16, il appelle abort sur la dernière opération utilisée afin de réduire le nombre de les opérations actives à 14 avant d'appeler begin pour démarrer opération récemment 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 à cette méthode.

Application des autorisations

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

  • Tag::PURPOSE: objectif spécifié dans l'appel begin() doit correspondre à l'un des objectifs dans les autorisations de clé, sauf si l'opération demandée est une clé publique opération. Si l'objectif spécifié ne correspond pas et que l'opération n'est pas opération de clé publique, begin renvoie ErrorCode::UNSUPPORTED_PURPOSE Les opérations de clé publique sont de chiffrement asymétrique ou d’opérations de vérification.
  • Tag::ACTIVE_DATETIME ne peut être appliquée que si une source de temps UTC fiable est disponible. Si le la date et l'heure actuelles antérieures à la valeur de la balise, la méthode renvoie ErrorCode::KEY_NOT_YET_VALID
  • Balise : ORIGINATION_EXPIRE_DATETIME ne peut être appliquée que si une source de temps UTC fiable est disponible. Si le la date et l'heure actuelles sont postérieures à celles de la balise, et l'objectif est KeyPurpose::ENCRYPT ou KeyPurpose::SIGN, la méthode renvoie ErrorCode::KEY_EXPIRED.
  • Balise : USAGE_EXPIRE_DATETIME ne peut être appliquée que si une source de temps UTC fiable est disponible. Si le la date et l'heure actuelles sont postérieures à celles de la balise, et l'objectif est KeyPurpose::DECRYPT ou KeyPurpose::VERIFY, la méthode renvoie ErrorCode::KEY_EXPIRED.
  • Balise : MIN_SECONDS_BETWEEN_OPS est comparée à un minuteur relatif de confiance indiquant la dernière utilisation la clé. Si l'heure de la dernière utilisation et la valeur de la balise sont inférieures à l'heure actuelle, La méthode renvoie ErrorCode::KEY_RATE_LIMIT_EXCEEDED. Consultez le description de la balise pour obtenir des informations importantes sur l'implémentation.
  • 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 valeur renvoie ErrorCode::KEY_MAX_OPS_EXCEEDED.
  • Balise : USER_SECURE_ID n'est appliquée 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 code Tag::AUTH_TOKEN dans inParams Pour que le jeton d'authentification soit valide, tous les éléments suivants doit être vrai: <ph type="x-smartling-placeholder">
      </ph>
    • Le champ HMAC est validé correctement.
    • Au moins l'un des éléments suivants Balise : USER_SECURE_ID de la clé correspond à au moins l'une des valeurs d'identifiant sécurisé à partir d'un jeton d'accès.
    • La clé comporte un Balise : USER_AUTH_TYPE qui correspond au type d'authentification dans le jeton.

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

  • Tag::CALLER_NONCE permet à l'appelant de spécifier un nonce ou un vecteur d'initialisation (IV). Si la clé ne dispose pas de ce tag, mais 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é avec une clé uniquement du bootloader après la fin de l’exécution du bootloader, la fonction 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 aucune valeur n'est spécifiée ou si elle 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 condensé, tout comme le chiffrement RSA. et de déchiffrement avec le mode de remplissage OAEP. Dans ce cas, l'appelant spécifie exactement un condensé dans inParams. Si non spécifié ou spécifié plusieurs fois, la méthode renvoie ErrorCode::UNSUPPORTED_DIGEST.

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

À l'exception de PaddingMode::NONE, tous les modes de marge intérieure RSA sont applicables uniquement à 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 n'acceptent que le chiffrement et le déchiffrement. La méthode renvoie ErrorCode::UNSUPPORTED_PADDING_MODE si le 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 condensés:

  • PaddingMode::NONE indique qu'une valeur "brute" L'opération d'ARR est d'exécution. Lors de la signature ou de la validation, Digest::NONE est spécifié pour le condensé. Aucun condensé n’est nécessaire pour un chiffrement sans remplissage ou le déchiffrement.
  • La marge intérieure de PaddingMode::RSA_PKCS1_1_5_SIGN nécessite un condensé. La le condensé peut être Digest::NONE, auquel cas le Keymaster ne peuvent pas créer une structure de signature PKCS#1 v1.5 appropriée, car il ne peut pas ajouter la structure DigestInfo. À la place, l'implémentation construit 0x00 || 0x01 || PS || 0x00 || M, où M est le fourni et PS est la chaîne de remplissage. La taille de la clé RSA doit avoir au moins 11 octets de plus que le message, sinon la méthode renvoie ErrorCode::INVALID_INPUT_LENGTH
  • Le remplissage pour PaddingMode::RSA_PKCS1_1_1_5_ENCRYPT ne nécessite pas de condensé.
  • La marge intérieure de PaddingMode::RSA_PSS nécessite un condensé, qui peut ne pas être Digest::NONE Si Digest::NONE est spécifié, le renvoie ErrorCode::INCOMPATIBLE_DIGEST. En outre, la taille de la clé RSA doit être supérieure d'au moins 2 + D octets à la sortie taille du condensé, où D est la taille du condensé, en octets. Sinon, La méthode renvoie ErrorCode::INCOMPATIBLE_DIGEST. La taille des valeurs de sel est le D.
  • La marge intérieure de PaddingMode::RSA_OAEP nécessite un condensé, qui peut ne pas être Digest::NONE Si Digest::NONE est spécifié, le renvoie ErrorCode::INCOMPATIBLE_DIGEST.

Clés EC

Les opérations de clé EC spécifient exactement un mode de remplissage dans inParams. Si aucune valeur n'est spécifiée ou si elle 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 condensé et de remplissage, ce qui signifie que les autorisations par clé doivent contenir les valeurs spécifiées. Sinon, renvoyez ErrorCode::INCOMPATIBLE_DIGEST Opérations de clé publique (KeyPurpose::VERIFY) sont autorisés 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ée par la clé. Sinon, elle 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érieure à la valeur de Tag::MIN_MAC_LENGTH dans des autorisations par clé. Pour les longueurs MAC supérieures à 128 ou les non-multiples de 8, renvoyer ErrorCode::UNSUPPORTED_MAC_LENGTH. Pour des valeurs inférieures que la longueur minimale de la clé, renvoyez ErrorCode::INVALID_MAC_LENGTH.

Si le mode de blocage est BlockMode::GCM ou BlockMode::CTR, le mode de marge intérieure 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 marge intérieure ne remplit pas ces conditions, renvoyez ErrorCode::INCOMPATIBLE_PADDING_MODE.

Si le mode de blocage 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 de vecteur d'initialisation ou de nonce. Dans ce cas, L'implémentation de Keymaster génère un vecteur d'initialisation ou un nonce aléatoire et le renvoie via Tag::NONCE dans outParams. Les vecteurs d'initialisation CBC et CTR sont de 16 octets. Les nonces GCM font 12 octets. Si la clé autorisations contiennent Tag::CALLER_NONCE, l'appelant peut alors fournir un IV/nonce avec Tag::NONCE dans inParams. Si un nonce est fourni lors Tag::CALLER_NONCE n'est pas autorisée, renvoyez ErrorCode::CALLER_NONCE_PROHIBITED. Si aucun nonce n'est fourni Tag::CALLER_NONCE est autorisé, générez un vecteur d'initialisation/nonce aléatoire.

Clés HMAC

Les opérations de clé HMAC spécifient Tag::MAC_LENGTH dans inParams. La valeur indiquée doit être un multiple de 8 n'étant pas supérieur au longueur du récapitulatif ou inférieure à la valeur de Tag::MIN_MAC_LENGTH dans les autorisations de clé. Pour les longueurs MAC supérieures à la longueur du condensé, ou non multiples de 8, renvoie 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 le cadre d'une opération en cours commençant par begin (début). 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 a été fourni. L'appelant est qui est responsable de la boucle pour alimenter le reste des données dans les appels suivants. La la quantité d'entrées consommées est renvoyée dans le paramètre inputConsumed. Les implémentations consomment toujours au moins un octet, sauf si le l'opération ne peut plus en accepter ; si le nombre d'octets est supérieur à zéro et si octets sont consommés, 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, en raison de la mise à jour. Cela ne s'applique qu'aux opérations de chiffrement et de déchiffrement, 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 annulée et le handle d'opération est invalidé. N'importe quelle valeur l'utilisation future du handle, avec cette méthode, finish ou abort renvoie ErrorCode::INVALID_OPERATION_HANDLE.

Application des autorisations

L'application des autorisations de clé s'effectue principalement au début. La seule exception concerne les cas où la clé comporte:

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

L'appelant fournit le jeton d'authentification à chaque appel à update. finish. 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 tout le bloc soit signé ou validé mise à jour. Il est possible qu'elle n'utilise qu'une partie du bloc. Toutefois, 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é (longueur de 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 tout le bloc soit signé ou validé mise à jour. Il est possible que cette méthode n'utilise 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 celles qui peuvent être utilisées, les données sont tronquées sans notification. (Ceci diffère de la le traitement des données excédentaires fournies dans des opérations RSA similaires. Cela s'explique par est la compatibilité avec les anciens clients.)

Clés AES

Le mode AES GCM prend en charge les « données d'authentification associées », fournies via la 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 sont toujours antérieures doivent être chiffrées ou déchiffrées. Un appel de mise à jour peut recevoir à la fois les données associées et les données à chiffrer/déchiffrer, mais les mises à jour ultérieures peuvent ne pas inclure données. Si l'appelant fournit des données associées à un appel de mise à jour après un appel qui inclut les données à chiffrer/déchiffrer, renvoyer ErrorCode::INVALID_TAG.

Pour le chiffrement GCM, la balise est ajoutée au texte chiffré par finish. Lors du déchiffrement, le dernier Tag::MAC_LENGTH octets des données fournies au dernier "update" est le tag. Puisqu'un appel donné de update ne peut pas savoir s'il s'agit du dernier appel, le système traite toutes les données, à l'exception de la longueur de la balise, et met en mémoire tampon les éventuelles données de balises. pendant finish.

terminer

Version: 1, 2, 3

Terminer une opération en cours démarrée par begin toutes les données non traitées fournies par Google Cloud mise(s) à jour(s).

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

Qu'elle aboutisse ou qu'elle renvoie une erreur, cette méthode finalise l'opération et invalide donc le handle d'opération fourni. N'importe quelle valeur une utilisation ultérieure du handle, avec cette méthode ou update ou abort, renvoie ErrorCode::INVALID_OPERATION_HANDLE.

Les opérations de signature renvoient la signature en sortie. Opérations de validation accepter la signature dans le paramètre signature et ne renvoyer aucun résultat.

Application des autorisations

L'application des autorisations de clé s'effectue principalement commencer. La seule exception concerne les cas où la clé comporte:

Dans ce cas, la clé nécessite une autorisation par opération, et la mise à jour reçoit un code 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 et contient le handle de l'opération en cours dans le défi. Si ces conditions ne sont pas remplies, ErrorCode::KEY_USER_NOT_AUTHENTICATED

L'appelant fournit le jeton d'authentification à chaque appel vers update et finish. L'implémentation n'a besoin de 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é, les données 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 numériquement plus grande, renvoyez ErrorCode::INVALID_ARGUMENT. Pour de vérification et de déchiffrement, les données doivent être comme clé. Sinon, renvoyez ErrorCode::INVALID_INPUT_LENGTH.
  • PaddingMode::RSA_PSS Pour les opérations de signature avec remplissage PSS, le salage PSS est la taille du condensat du message et généré de manière aléatoire. Condensé spécifié avec Tag::DIGEST. dans inputParams, le begin est utilisé comme condensé PSS et l'algorithme de condensé MGF1.
  • PaddingMode::RSA_OAEP Le condensé spécifié avec Tag::DIGEST dans inputParams au début est utilisé comme OAEP. l’algorithme de condensé, 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, tronquez

Clés AES

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

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

annuler

Version: 1, 2, 3

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

get_supported_algorithmes

Version: 1

Affiche la liste des algorithmes compatibles avec le matériel Keymaster. la mise en œuvre. Une implémentation logicielle renvoie une liste vide. un modèle hybride renvoie une liste contenant uniquement les algorithmes pris en charge par 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 le matériel Keymaster pour un algorithme et un objectif donnés.

Pour RSA, EC et HMAC, qui ne sont pas des algorithmes de chiffrement par bloc, la méthode renvoie une liste vide à des fins valides. Les finalités non valides devraient entraîner renvoient ErrorCode::INVALID_PURPOSE.

Les implémentations Keymaster 1 prennent en charge l'ECB, le CBC, le CTR et GCM pour AES le chiffrement et le déchiffrement.

get_supported_pickup_modes

Version: 1

Renvoie la liste des modes de marge intérieure compatibles avec le matériel Keymaster. pour un algorithme et un objectif donnés.

HMAC et EC n'ont pas de notion de remplissage, la méthode renvoie donc une liste vide à toutes fins valables. Les finalités non valides devraient entraîner le renvoi de ErrorCode::INVALID_PURPOSE

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

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

Pour l'AES en modes ECB et CBC, les implémentations de Keymaster 1 n'acceptent aucun le remplissage et PKCS#7-rembourrage. Les modes CTR et GCM n'acceptent qu'aucune marge intérieure.

get_supported_digests

Version: 1

Renvoie la liste des modes de condensé compatibles avec le matériel Keymaster. pour un algorithme et un objectif donnés.

Comme aucun mode AES n'est compatible ou ne nécessite un condensé, la méthode renvoie une valeur à des fins valides.

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

get_supported_import_formats

Version: 1

Renvoie la liste des formats d'importation compatibles avec le matériel Keymaster. la mise en œuvre d'un algorithme spécifié.

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

get_supported_export_formats

Version: 1

Renvoie la liste des formats d'exportation compatibles avec le matériel Keymaster. la mise en œuvre d'un algorithme spécifié.

Les implémentations de Keymaster1 prennent en charge le format X.509 pour l'exportation RSA et Clés publiques EC. L'exportation de clés privées ou de clés asymétriques n'est pas acceptée.

Fonctions historiques

Keymaster 0

Les fonctions suivantes appartiennent à la définition Keymaster 0 d'origine. Ils étaient présentes dans Keymaster 1 struct keymaster1_device_t. Toutefois, 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 elles étaient supprimées dans Keymaster 2, ainsi que les fonctions Keymaster 0 répertorié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 elles étaient supprimées dans Keymaster 3, ainsi que les fonctions Keymaster 1 répertoriées ci-dessus.

  • configure