classe ara::crypto::Serializable

L’interface ara::crypto::Serializable définit le standard uniforme pour l’exportation publique d’objets cryptographiques vers des séquences d’octets spécifiques à un format. Les applications déterminent préalablement via GetExportSize() la taille de tampon requise et exécutent ensuite la sérialisation proprement dite via ExportPublicly() dans un tampon mis à disposition [SWS_CRYPT_10711]. Toutes les opérations sont sécurisées vis-à-vis des exceptions ainsi que sûres du point de vue des threads, l’exportation de clés nécessitant obligatoirement l’autorisation kAllowPlaintextExport et les erreurs étant toujours soumises à une sémantique de rollback [SWS_CRYPT_50006].

plus ›

Contexte

L’interface ara::crypto::Serializable définit le contrat abstrait pour les objets cryptographiques du module crypto pouvant être convertis en une représentation d’octets standardisée. En tant que pure interface, elle encapsule la capacité de sérialiser un objet dans un format de sortie spécifié par un identifiant de format (FormatId) [SWS_CRYPT_10711]. Parmi les partenaires d’interaction typiques figurent des composants d’application ou de plateforme qui doivent stocker de manière persistante des artefacts cryptographiques tels que des clés ou des certificats, les transmettre sur des canaux de communication ou les échanger en texte clair. L’interface garantit que l’exportation a lieu de manière contrôlée et en tenant compte des formats ainsi que des restrictions de sécurité.

Cycle de vie

Comme ara::crypto::Serializable représente une interface purement virtuelle avec des méthodes purement virtuelles, la classe ne dispose d’aucune logique d’instanciation propre. La durée de vie et la création dépendent entièrement des classes cryptographiques concrètes dérivées qui implémentent l’interface. Les deux méthodes spécifiées de l’interface, GetExportSize() [SWS_CRYPT_50006] ainsi que ExportPublicly() [SWS_CRYPT_10711], sont déclarées comme const et ne modifient pas l’état interne de l’objet lors de la sérialisation. Conformément à la spécification, les opérations sont conçues pour être sûres vis-à-vis des exceptions (exception safe) et sûres du point de vue des threads (thread-safe) [SWS_CRYPT_10711], [SWS_CRYPT_50006], de sorte que les accès concurrents en lecture sur la même instance d’objet sont autorisés.

Parcours d'utilisation

Le déroulement régulier d’une exportation se divise en une séquence à deux étapes composée de la détermination de la taille et de la sérialisation proprement dite. Afin d’éviter les dépassements de tampon ou les échecs d’allocation, l’appelant demande préalablement, via la méthode GetExportSize(), la taille exacte de tampon requise en octets pour le format cible souhaité [SWS_CRYPT_50006]. Après un retour positif, l’appelant met à disposition une zone mémoire inscriptible du type ReadWriteMemRegion. Cette zone mémoire est probablement allouée dynamiquement dans la plupart des implémentations en fonction du nombre d’octets déterminé ou mise à disposition à partir d’un pool de mémoire préalablement réservé. Question Q-0c04ba0a352f0a37 (ouverte)

À l’étape suivante, l’application appelle ExportPublicly() et transmet aussi bien le tampon mis à disposition que la FormatId [SWS_CRYPT_10711] préalablement choisie. L’objet sérialise ses données utiles dans la zone mémoire transmise et renvoie, en cas de succès, le nombre d’octets réellement écrits au sein du type de retour ara::core::Result<std::size_t> [SWS_CRYPT_10711].

Diagramme de séquence : ordre d’appel typique pour la sérialisation d’un objet via l’interrogation de la taille et l’exportation consécutive. Sources : [SWS_CRYPT_50006], [SWS_CRYPT_10711]

Scénarios d'erreur

Les opérations de l’interface signalent les états d’erreur via le type de retour ara::core::Result, toutes les erreurs spécifiées garantissant une sémantique stricte de rollback (rollback_semantics) [SWS_CRYPT_10711], [SWS_CRYPT_50006]. En cas d’échec d’un appel, le système global demeure dans un état cohérent. Les cas d’erreur suivants sont définis :

• ara::crypto::CryptoErrc::kUnsupportedFormat : renvoyé aussi bien par GetExportSize() [SWS_CRYPT_50006] que par ExportPublicly() [SWS_CRYPT_10711] lorsque la FormatId indiquée n’est pas prise en charge pour le type d’objet concret.
• ara::crypto::CryptoErrc::kInsufficientCapacity : survient dans ExportPublicly() lorsque la capacité du tampon ReadWriteMemRegion transmis n’est pas suffisante pour les données sérialisées [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUnsupported : signalé par ExportPublicly() dans le cas où l’exportation n’est par principe pas prise en charge pour l’objet spécifique [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUsageViolation : survient lors de ExportPublicly() lorsqu’il s’agit, pour l’objet, d’une clé dont les règles d’utilisation n’autorisent pas une exportation en texte clair (l’utilisation autorisée n’inclut pas kAllowPlaintextExport) [SWS_CRYPT_10711].