classe ara::crypto::cryp::HashFunctionCtx

La méthode CalculateHashDigest effectue un calcul one-shot synchrone d'une valeur de hachage cryptographique et écrit le résultat dans le tampon de sortie fourni [SWS_CRYPT_50060]. Sont transmis comme paramètres le message d'entrée à traiter data, le tampon cible digest ainsi que, de manière optionnelle, un vecteur d'initialisation iv. En cas d'exécution réussie, la fonction renvoie via l'objet de résultat ara::core::Result<std::size_t> le nombre effectif d'octets de digest écrits [SWS_CRYPT_50060].

Gestion des erreurs

Si le calcul échoue, l'interface garantit une sémantique de rollback [SWS_CRYPT_50060]. Les codes d'erreur suivants peuvent être contenus dans le résultat :

• ara::crypto::CryptoErrc::kInvalidInputSize : La taille des données transmises ou du vecteur d'initialisation n'est pas prise en charge [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kUnsupported : Le calcul en appel unique (single-call) n'est pas pris en charge par le contexte, ou la transmission du vecteur d'initialisation ne correspond pas à la configuration du contexte (IV requis mais manquant, ou IV transmis alors qu'il n'est pas pris en charge) [SWS_CRYPT_50060].
• ara::crypto::CryptoErrc::kInsufficientCapacity : La capacité du tampon de sortie digest n'est pas suffisante pour le digest calculé [SWS_CRYPT_50060].

Concurrence et interaction

La fonction est déclarée sûre vis-à-vis des exceptions (exception safe) et sûre vis-à-vis des threads (thread-safe) [SWS_CRYPT_50060]. Afin d'éviter en amont des erreurs relatives à des longueurs d'entrée non autorisées, la taille de tampon maximale admissible pour un appel unique du contexte peut être déterminée via GetMaximumChunkSize [SWS_CRYPT_50062].

Utilisation

La méthode Cancel() sert à l'interruption ciblée d'une opération de streaming en cours, commencée auparavant via la méthode Start() et non encore terminée de manière régulière [SWS_CRYPT_50058]. L'appel s'effectue de manière synchrone et sans paramètre sur une instance de ara::crypto::cryp::HashFunctionCtx issue du fichier d'en-tête ara/crypto/cryp/hash_function_ctx.h [SWS_CRYPT_50058]. En cas d'exécution réussie, l'opération renvoie un ara::core::Result<void> vide [SWS_CRYPT_50058].

Gestion des erreurs

Si un problème survient pendant l'exécution, le ara::core::Result renvoyé contient une valeur d'erreur correspondante [SWS_CRYPT_50058]. Si le traitement n'a pas été initié par Start() avant l'appel de Cancel(), l'interruption échoue et retourne le code d'erreur spécifique ara::crypto::CryptoErrc::kProcessingNotStarted avec une sémantique de rollback [SWS_CRYPT_50058].

Concurrence et restrictions

L'interface est définie comme thread-safe et exception safe et déclarée avec noexcept [SWS_CRYPT_50058]. Comme condition préalable fonctionnelle essentielle, le traitement des données doit se trouver dans un état actif généré par un appel antérieur de Start() [SWS_CRYPT_50058].

Interaction

Le modèle mis en œuvre par Cancel() est standardisé à travers divers contextes de streaming de la pile cryptographique. Les contextes VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SignerPrivateCtx [SWS_CRYPT_50041], SymmetricCipherCtx [SWS_CRYPT_50046], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] et EncryptorPublicCtx [SWS_CRYPT_50089] présentent également une sémantique et une signalisation d'erreur exactement identiques.

La méthode Compare de la classe ara::crypto::cryp::HashFunctionCtx ([SWS_CRYPT_50154]) compare de manière synchrone la taille et le contenu d'un digest de hachage préalablement calculé avec une valeur de référence attendue. La valeur de consigne est transmise via le paramètre expected de type ReadOnlyMemRegion. En cas de succès, la fonction renvoie un ara::core::Result<bool> qui contient true si et seulement si la séquence d'octets attendue est identique au digest calculé.

La précondition pour l'appel est que le calcul du digest ait été préalablement terminé avec la méthode Finish(). Si ce n'est pas le cas, l'appel échoue et renvoie l'erreur ara::crypto::CryptoErrc::kProcessingNotFinished avec une sémantique de rollback ([SWS_CRYPT_50154]). Interprétation : Une longueur différente ou un contenu non identique de expected n'entraîne probablement pas de code d'erreur, mais un false normal dans l'objet de résultat. Question Q-fdd0ecaec22f6985 (ouverte)

En ce qui concerne la concurrence, la méthode est spécifiée comme thread-safe et exception safe ([SWS_CRYPT_50154]). En raison de sa déclaration en tant que noexcept, elle ne lève aucune exception C++.

Le même schéma de vérification est employé dans des contextes cryptographiques similaires : pour les Message Authentication Codes, ara::crypto::cryp::MessageAuthnCodeCtx::Compare ([SWS_CRYPT_50133]) compare la taille et le contenu de la valeur MAC calculée, tandis que CompareSubspan ([SWS_CRYPT_50028]) vérifie les bits de poids fort. Les deux méthodes exigent de la même façon un calcul préalablement terminé.

La méthode [SWS_CRYPT_50064] de la classe ara::crypto::cryp::HashFunctionCtx écrit de manière synchrone l'état actuel d'un contexte de hachage dans le tampon de sortie transmis contextState de type ReadWriteMem Region. Cela permet aux applications d'interrompre une opération de hachage cryptographique en cours et de la reprendre à un moment ultérieur. En cas d'exécution réussie, l'appel renvoie un ara::core::Result<void> vide.

Interaction et dimensionnement du tampon

Afin d'éviter des erreurs de mémoire, la taille de tampon impérativement requise en octets devrait être demandée au préalable via la fonction [SWS_CRYPT_50063]. L'état exporté peut être réinjecté ultérieurement dans un contexte de hachage au moyen de [SWS_CRYPT_50065]. La condition préalable à cela est que le contexte cible présente la même AlgorithmId et soit fourni par le même Crypto Provider que le contexte d'origine. Lors de l'importation, un état de calcul éventuellement existant est entièrement écrasé.

Gestion des erreurs

Si l'opération échoue, une erreur est renvoyée dans le ara::core::Result. Les codes d'erreur suivants issus de ara::crypto::CryptoErrc sont spécifiés :

• ara::crypto::CryptoErrc::kUnsupported : Le contexte concret ne prend pas en charge l'exportation ou l'importation d'états.
• ara::crypto::CryptoErrc::kInsufficientCapacity : La capacité du tampon contextState transmis ne suffit pas pour accueillir l'état.

Pour les deux cas d'erreur, une sémantique de rollback est définie, de sorte que l'état de l'objet reste inchangé.

Concurrence et sécurité d'exécution

L'interface est déclarée comme const et noexcept. Conformément à la spécification, l'appel est à la fois thread-safe et exception-safe.

Utilisation

La méthode synchrone Finish() finalise le calcul d'une valeur de hachage dans ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_21115]. L'appel sans paramètre renvoie un ara::core::Result<void> qui signale l'achèvement réussi ou encapsule une erreur [SWS_CRYPT_21115]. L'interface est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des exceptions (exception safe) et thread-safe (thread-safe) [SWS_CRYPT_21115].

Gestion des erreurs et concurrence

Si le calcul de hachage n'a pas été démarré avec succès avant l'appel, la méthode échoue avec l'erreur ara::crypto::CryptoErrc::kInvalidUsageOrder [SWS_CRYPT_21115]. Une sémantique de rollback est définie pour ce cas d'erreur, de sorte que les appelants doivent impérativement veiller à ce qu'un contexte soit correctement démarré avant la finalisation [SWS_CRYPT_21115].

Interaction

Après un appel réussi de Finish(), le condensé de hachage calculé est typiquement transféré dans un tampon fourni au moyen de GetDigest() [SWS_CRYPT_21116], [SWS_CRYPT_50059]. GetIntermediateDigest() sert de démarcation : cette fonction fournit la même valeur de hachage que la séquence de Finish() et GetDigest(), mais autorise ensuite la transmission d'autres données [SWS_CRYPT_50059]. Interprétation : après l'appel de Finish(), le calcul devrait être définitivement terminé et le contexte ne devrait plus accepter de données supplémentaires. Question Q-f4daf29364f45fd5 (ouverte) Les tailles de tampon admissibles pour les étapes de traitement dans le contexte peuvent être interrogées via GetMaximumChunkSize() [SWS_CRYPT_50062].

La méthode ImportContextState de la classe ara::crypto::cryp::HashFunctionCtx (définie dans ara/crypto/cryp/hash_function_ctx.h) sert à restaurer l'état interne d'un contexte de hachage à partir d'un tampon transmis et à poursuivre ainsi une opération de hachage interrompue précédemment [SWS_CRYPT_50065]. Un état de calcul éventuellement en cours du contexte actuel est alors entièrement remplacé par l'état importé [SWS_CRYPT_50065].

Appel et préconditions

L'appel synchrone s'effectue via la signature ImportContextState(ReadOnlyMem Region contextState) noexcept et renvoie un ara::core::Result<void> [SWS_CRYPT_50065]. Les conditions préalables obligatoires suivantes s'appliquent au paramètre contextState :

• Le tampon de données doit avoir été préalablement exporté depuis une instance de HashFunctionCtx à l'aide de la méthode ExportContextState() [SWS_CRYPT_50065].
• Le contexte source doit avoir possédé le même AlgorithmId et avoir été fourni par le même Crypto Provider que le contexte cible [SWS_CRYPT_50065].

Gestion des erreurs et concurrence

En cas d'erreur, un code d'erreur avec une sémantique de rollback est renvoyé, de sorte que l'état existant du contexte reste inchangé en cas d'échec [SWS_CRYPT_50065] :

• ara::crypto::CryptoErrc::kInvalidArgument : l'argument contextState contient des données non valides [SWS_CRYPT_50065].
• ara::crypto::CryptoErrc::kUnsupported : le contexte spécifique ne prend pas en charge l'exportation et l'importation d'états de contexte [SWS_CRYPT_50065].

L'opération est spécifiée comme thread-safe et exception safe [SWS_CRYPT_50065].

La méthode Start() de l'interface ara::crypto::cryp::HashFunctionCtx initialise le contexte pour le calcul pas à pas d'une valeur de hachage sans vecteur d'initialisation (IV) [SWS_CRYPT_50152]. Un nouvel appel interrompt un éventuel calcul de hachage déjà en cours et réinitialise le contexte pour un nouveau calcul [SWS_CRYPT_50152].

La fonction est synchrone, ne prend aucun paramètre et renvoie un ara::core::Result<void> [SWS_CRYPT_50152]. Si une erreur survient lors de l'initialisation, une sémantique de rollback s'applique avec les codes d'erreur spécifiques suivants [SWS_CRYPT_50152] :

• ara::crypto::CryptoErrc::kUnsupported : la fonction de hachage utilisée attend obligatoirement un vecteur d'initialisation [SWS_CRYPT_50152].
• ara::crypto::CryptoErrc::kBusyResource : une ressource interne obligatoirement requise pour l'opération est occupée [SWS_CRYPT_50152].

Concernant la concurrence, la méthode est spécifiée comme thread-safe ainsi qu'exception safe et déclarée comme noexcept [SWS_CRYPT_50152]. Après une initialisation réussie, des portions de message peuvent être injectées séquentiellement via la méthode Update() du contexte [SWS_CRYPT_21113]. Étant donné que l'appel interrompt les calculs en cours, la fonction devrait également servir en pratique de mécanisme de réinitialisation avant un redémarrage. Question Q-9c369489a6c6e8cb (ouverte)

Utilisation

La fonction Start de l'interface ara::crypto::cryp::HashFunctionCtx initialise le contexte pour le calcul d'un condensé de hachage à l'aide d'un vecteur d'initialisation (IV) [SWS_CRYPT_50153]. Le vecteur d'initialisation iv est transmis en paramètre via une ReadOnlyMemRegion [SWS_CRYPT_50153]. L'appel synchrone renvoie un ara::core::Result<void> qui, en cas de succès, ne contient aucune valeur de retour [SWS_CRYPT_50153]. Un appel interrompt en outre un éventuel calcul de hachage déjà en cours sur ce contexte [SWS_CRYPT_50153].

Gestion des erreurs

Si une erreur survient lors de l'initialisation, un code d'erreur correspondant est renvoyé, une sémantique de rollback étant garantie pour tous les cas d'erreur [SWS_CRYPT_50153] :

• ara::crypto::CryptoErrc::kInvalidInputSize : la taille du vecteur d'initialisation fourni n'est pas prise en charge [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kUnsupported : la fonction de hachage sous-jacente n'utilise pas de vecteur d'initialisation [SWS_CRYPT_50153].
• ara::crypto::CryptoErrc::kBusyResource : une ressource nécessaire à l'initialisation est occupée [SWS_CRYPT_50153].

Concurrence et interaction

L'interface est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des threads (thread-safe) et sûre vis-à-vis des exceptions (exception safe) [SWS_CRYPT_50153]. Dans le déroulement type, l'appel constitue la précondition pour le traitement pas à pas ultérieur du message d'entrée via la méthode Update [SWS_CRYPT_21113].

La méthode synchrone Update sert dans [SWS_CRYPT_21113] à la mise à jour incrémentielle d'un contexte de calcul de hachage en cours (ara::crypto::cryp::HashFunctionCtx). Une partie du message d'entrée à traiter est transmise via le paramètre data (ReadOnlyMemRegion). La fonction renvoie un ara::core::Result<void> qui est vide en cas de succès ou encapsule un code d'erreur correspondant.

Concernant le comportement en cas d'erreur, la méthode offre une sémantique de rollback pour deux états d'erreur spécifiques :

• ara::crypto::CryptoErrc::kProcessingNotStarted : le calcul n'a pas été initié au préalable par un appel de la méthode Start() [SWS_CRYPT_21113].
• ara::crypto::CryptoErrc::kInvalidInputSize : la taille des données transmises n'est pas prise en charge par le contexte [SWS_CRYPT_21113].

Des conditions claires d'ordre et de taille s'appliquent au contexte d'appel : l'opération de hachage doit avoir été initialisée avant la transmission des données [SWS_CRYPT_21113]. Pour éviter kInvalidInputSize, la taille maximale de bloc autorisée pour un appel unique à Update peut être déterminée au préalable via GetMaximumChunkSize [SWS_CRYPT_50062]. Conformément à la spécification, la fonction est déclarée comme sûre vis-à-vis des exceptions (exception safe) et sûre pour les threads (thread-safe) [SWS_CRYPT_21113].

Dans l'interaction avec d'autres interfaces, il existe au sein de HashFunctionCtx une surcharge pour la transmission d'objets de clé via Update(CryptoObject::Sptr) [SWS_CRYPT_50057]. Après la fourniture de tous les blocs de données, la finalisation de la somme de contrôle devrait vraisemblablement s'effectuer via Finish() [SWS_CRYPT_50062]. Question Q-dcac20f353ca55f4 (ouverte)

Dans [SWS_CRYPT_50057], la méthode synchrone Update sert à étendre progressivement le contexte d'un calcul de valeur de hachage dans ara::crypto::cryp::HashFunctionCtx avec un nouveau segment de message sous la forme d'un objet de clé. Un pointeur intelligent vers l'objet de clé (CryptoObject::Sptr key) est transmis comme paramètre. Comme valeur de retour, l'appel fournit un ara::core::Result<void> qui est vide en cas de traitement réussi ou encapsule un code d'erreur correspondant en cas d'erreur [SWS_CRYPT_50057].

Comme condition d'ordonnancement, le calcul doit impérativement avoir été initié au préalable par l'appel de Start() ; sinon, l'erreur ProcessingNotStarted est signalée [SWS_CRYPT_50057]. D'autres cas d'erreur spécifiques comprennent (chacun avec sémantique de rollback) [SWS_CRYPT_50057] :

• ara::crypto::CryptoErrc::kUnsupported, si le contexte de hachage ne prend généralement pas en charge le hachage de clés,
• ara::crypto::CryptoErrc::kIncompatibleObject, si l'objet de clé transmis n'est pas compatible avec le contexte,
• ara::crypto::CryptoErrc::kUsageViolation, dans la mesure où l'utilisation autorisée de la clé n'inclut pas kAllowHash Calculation,
• ara::crypto::CryptoErrc::kInvalidInputSize, si la taille de données de la clé transmise n'est pas prise en charge.

La méthode est déclarée comme thread-safe ainsi qu'exception safe (noexcept) [SWS_CRYPT_50057]. En interaction avec d'autres interfaces du module, la taille maximale de tampon autorisée pour des appels individuels de Update peut être déterminée via GetMaximumChunkSize() [SWS_CRYPT_50062]. Pour les parties de message régulières sans objet de clé, la surcharge Update(ReadOnlyMemRegion data) existe en parallèle dans HashFunctionCtx [SWS_CRYPT_21113].