classe ara::crypto::cryp::MessageAuthnCodeCtx

La méthode virtuelle pure Cancel sert, dans l'interface ara::crypto::cryp::MessageAuthnCodeCtx, à interrompre une opération de streaming en cours, initiée au préalable via Start() et non encore achevée [SWS_CRYPT_50027]. L'appel s'effectue de manière synchrone, ne prend aucun paramètre d'entrée et renvoie en cas de succès un ara::core::Result<void> vide, ce qui confirme l'interruption réussie de l'opération [SWS_CRYPT_50027].

Si le traitement des données n'a pas été correctement initié par la méthode Start() avant l'appel, l'exécution échoue. Dans ce cas, la fonction renvoie un résultat avec le code d'erreur spécifique ara::crypto::CryptoErrc::kProcessingNotStarted en garantissant une sémantique de retour arrière (rollback) [SWS_CRYPT_50027]. Concernant la sécurité d'exécution, l'interface est spécifiée comme sûre pour les threads (thread-safe) et garantit la sécurité vis-à-vis des exceptions (exception safe), car elle est déclarée comme noexcept et ne lève aucune exception [SWS_CRYPT_50027].

Le comportement d'interruption identique pour les traitements de streaming non encore finalisés est partagé par toutes les interfaces de contexte apparentées du module cryptographique :

• VerifierPublicCtx pour la vérification de signatures numériques [SWS_CRYPT_50023],
• SignerPrivateCtx pour la génération de signatures numériques [SWS_CRYPT_50041],
• SymmetricCipherCtx pour les chiffrements symétriques [SWS_CRYPT_50046],
• HashFunctionCtx pour les calculs de valeur de hachage [SWS_CRYPT_50058],
• DecryptorPrivateCtx pour les déchiffrements asymétriques [SWS_CRYPT_50069],
• AuthCipherCtx pour les chiffrements authentifiés [SWS_CRYPT_50077] ainsi que
• EncryptorPublicCtx pour les chiffrements asymétriques [SWS_CRYPT_50089].

Interprétation : grâce à l'interruption de l'opération inachevée, le contexte devrait être ramené à un état nettoyé qui permet une réinitialisation ultérieure via Start(). Question Q-a8fa5cb85c3dab50 (ouverte)

Utilisation

La méthode purement virtuelle Compare de la classe ara::crypto::cryp::MessageAuthnCodeCtx sert à comparer la taille et le contenu d'un Message Authentication Code (MAC) calculé avec un digest attendu [SWS_CRYPT_50133]. Le digest MAC attendu est transmis via le paramètre ReadOnlyMemRegion expected. La fonction renvoie un ara::core::Result<bool> qui contient true si la valeur MAC calculée correspond exactement à la valeur attendue, et sinon false [SWS_CRYPT_50133].

Gestion des erreurs

En cas d'erreur, un code d'erreur est renvoyé dans l'objet de résultat, avec application d'une sémantique de rollback [SWS_CRYPT_50133] :

• ara::crypto::CryptoErrc::kProcessingNotFinished : est signalé lorsque le calcul du digest n'a pas été préalablement finalisé par l'appel de la méthode Finish() [SWS_CRYPT_50133].
• ara::crypto::CryptoErrc::kInvalidInputSize : survient lorsque la taille de tampon transmise pour le digest MAC attendu n'est pas prise en charge par le contexte [SWS_CRYPT_50133].

Concurrence et restrictions

La méthode est déclarée comme const ainsi que noexcept et est, conformément aux spécifications, sûre au regard des threads (thread-safe) et des exceptions (exception safe) [SWS_CRYPT_50133]. Une précondition essentielle est l'achèvement préalable et réussi du calcul du digest via Finish() [SWS_CRYPT_50133].

Interaction

Par opposition à Compare, qui valide la correspondance complète de l'ensemble du digest MAC [SWS_CRYPT_50133], CompareSubspan compare dans le même contexte uniquement les bits de poids fort (most significant bits) avec la valeur attendue [SWS_CRYPT_50028]. Pour les fonctions de hachage non indexées par clé, il existe une fonction Compare de même nom dans ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50154].

La méthode synchrone CompareSubspan de la classe ara::crypto::cryp::MessageAuthnCodeCtx compare les bits les plus significatifs (Most Significant Bits) d'une valeur MAC calculée avec une référence prédéfinie [SWS_CRYPT_50028]. La valeur de comparaison attendue est transmise via le paramètre expected en tant que ReadOnlyMemRegion [SWS_CRYPT_50028]. Le résultat est retourné sous forme de ara::core::Result<bool> et contient true en cas d'identité des bits de poids fort ainsi que false en cas d'écarts [SWS_CRYPT_50028].

Gestion des erreurs et conditions de déroulement

Pour une comparaison valide, le calcul de la valeur de contrôle doit être achevé. En l'absence d'appel préalable à la méthode Finish(), l'appel échoue avec le code d'erreur ara::crypto::CryptoErrc::kProcessingNotFinished [SWS_CRYPT_50028]. Si la taille du tampon du paramètre transmis expected n'est pas autorisée pour le procédé utilisé, la méthode signale ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_50028]. Les deux types d'erreurs garantissent une sémantique de rollback [SWS_CRYPT_50028].

Concurrence et contexte d'exécution

L'opération est spécifiée comme noexcept (exception-safe) et classée comme thread-safe [SWS_CRYPT_50028]. Interprétation : la sécurité des threads déclarée devrait faire référence à l'état consécutif à Finish(), de sorte que plusieurs threads puissent vérifier en parallèle le même condensé calculé. Question Q-ac8b7ead6a5b508e (ouverte)

La méthode Finish() finalise obligatoirement le calcul en cours d'un code d'authentification de message (MAC) au sein de l'interface MessageAuthnCodeCtx [SWS_CRYPT_22115]. L'appel s'effectue de manière synchrone, ne prend aucun paramètre et renvoie ara::core::Result<void>, ce qui représente un résultat vide en cas de succès nominal [SWS_CRYPT_22115].

En cas d'erreur, la fonction fournit le code d'erreur ara::crypto::CryptoErrc::kProcessingNotStarted si le calcul de MAC n'a pas été démarré avec succès avant l'appel ; une sémantique de retour arrière s'applique alors [SWS_CRYPT_22115]. L'opération est déclarée comme noexcept et spécifiée, conformément à la spécification, à la fois comme sûre vis-à-vis des exceptions (exception safe) et sûre vis-à-vis des threads (thread-safe) [SWS_CRYPT_22115].

Dans le flux de traitement, Finish() constitue le lien entre le traitement des données et l'évaluation : après l'appel, le condensé MAC généré peut être transféré dans un tampon fourni via GetDigest() [SWS_CRYPT_22116] ou être directement vérifié par rapport à une valeur de référence avec CompareSubspan() [SWS_CRYPT_50028]. Alors que GetMaximumChunkSize() [SWS_CRYPT_50033] décrit de manière générique des tailles de tampon pour Update() ou Finish(), Finish() ne traite ici aucune donnée directement ; sa mention dans l'exigence reflète vraisemblablement un modèle uniforme à travers tous les contextes cryptographiques. Question Q-79b4f4ecf3998e48 (ouverte)

La fonction membre synchrone Generate de la classe ara::crypto::cryp::MessageAuthnCodeCtx sert, conformément à [SWS_CRYPT_50029], à calculer un Message Authentication Code (MAC) en une seule étape et écrit le condensé calculé dans le tampon de sortie fourni.

Pour l'appel, les paramètres suivants sont transmis :

• data : données d'entrée pour le calcul du MAC en tant que ReadOnlyMemRegion.
• digest : zone mémoire de destination de type ReadWriteMemRegion dans laquelle le condensé est écrit.
• iv : un vecteur d'initialisation optionnel sous forme de ara::core::Optional<ReadOnlyMemRegion>.

En cas de succès, la fonction renvoie un ara::core::Result<std::size_t> contenant la taille en octets du condensé MAC écrit [SWS_CRYPT_50029].

Si une erreur survient, un code d'erreur avec sémantique de rollback est renvoyé [SWS_CRYPT_50029] :

• UninitializedContext : le contexte n'a pas encore été initialisé par l'assignation d'une clé.
• ara::crypto::CryptoErrc::kUsageViolation : la clé utilisée ne possède pas l'indicateur d'utilisation requis kAllowMac. Interprétation : une clé symétrique adaptée devrait être générée et configurée préalablement via GenerateSymmetricKey [SWS_CRYPT_20721]. Question Q-d22f397bbc02487b (ouverte)
• ara::crypto::CryptoErrc::kEmptyKeySlot : Un KeySlot configuré est actuellement vide.
• ara::crypto::CryptoErrc::kUnsupported : le traitement en un seul appel n'est pas pris en charge ou l'indication du vecteur d'initialisation ne correspond pas aux exigences de l'algorithme (IV manquant ou spécifié de manière non autorisée).
• ara::crypto::CryptoErrc::kInvalidInputSize : la taille de tampon des données d'entrée ou de l'IV n'est pas prise en charge.
• ara::crypto::CryptoErrc::kInsufficientCapacity : le tampon de destination digest est trop petit pour le condensé MAC.
• ara::crypto::CryptoErrc::kBusyResource : une ressource système requise est occupée.

En ce qui concerne la concurrence, la méthode est spécifiée comme thread-safe et exception safe [SWS_CRYPT_50029]. Elle est déclarée comme const noexcept et ne modifie pas l'état du contexte lors de son exécution.

La méthode GenerateSubspan de la classe ara::crypto::cryp::MessageAuthnCodeCtx calcule en une seule étape un code d'authentification de message (MAC) pour les données d'entrée data et écrit le début (les octets de poids fort, MSB) du condensé calculé dans le tampon de sortie truncatedDigest [SWS_CRYPT_50030]. Via le paramètre optionnel iv, un vecteur d'initialisation peut être transmis si nécessaire [SWS_CRYPT_50030]. Le retour direct de ara::core::Result<std::size_t> devrait indiquer une exécution synchrone ; en cas de déroulement réussi, le nombre d'octets écrits du condensé MAC est renvoyé [SWS_CRYPT_50030]. Question Q-167c6d44b9f39fed (ouverte)

La spécification définit une sémantique de retour arrière en cas d'erreur et prévoit les codes d'erreur suivants [SWS_CRYPT_50030] :

• UninitializedContext : le contexte n'a pas été préalablement initialisé par l'assignation d'une clé [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kEmptyKeySlot : un KeySlot configuré est actuellement vide [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUsageViolation : L'utilisation autorisée de la clé n'inclut pas kAllowMac [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kUnsupported : Le traitement en une seule étape n'est pas pris en charge, ou la configuration de l'IV ne correspond pas au contexte (IV requis manquant ou IV non autorisé transmis) [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kInvalidInputSize : La taille des données transmises data ou du iv n'est pas prise en charge [SWS_CRYPT_50030].
• ara::crypto::CryptoErrc::kBusyResource : une ressource requise est occupée [SWS_CRYPT_50030].

En ce qui concerne l'environnement d'exécution, la méthode est spécifiée comme thread-safe et offre une sécurité vis-à-vis des exceptions (noexcept) [SWS_CRYPT_50030]. La fourniture préalable d'une clé dotée de l'autorisation correspondante dans le contexte constitue un prérequis pour un appel sans erreur [SWS_CRYPT_50030].

La méthode SetKey configure une instance de ara::crypto::cryp::MessageAuthnCodeCtx pour le calcul ultérieur de MAC avec une clé symétrique fournie [SWS_CRYPT_22118]. L'appel s'effectue de manière synchrone et reçoit l'objet de clé sous la forme d'un pointeur intelligent SymmetricKey::Sptr. Comme résultat, la fonction renvoie un ara::core::Result<void> qui est vide en cas de succès ou qui encapsule un code d'erreur spécifique en cas d'erreur [SWS_CRYPT_22118].

Si l'assignation échoue, une sémantique de rollback s'applique, préservant l'état antérieur du contexte [SWS_CRYPT_22118]. Les états d'erreur suivants issus de ara::crypto::CryptoErrc sont spécifiés :

• kUnsupported : Le contexte prend exclusivement en charge la liaison via un KeySlot au lieu d'objets de clé directs [SWS_CRYPT_22118].
• kIncompatibleObject : L'objet de clé symétrique transmis est incompatible avec le contexte cible [SWS_CRYPT_22118].
• kUsageViolation : Les drapeaux d'autorisation de la clé ne contiennent pas l'utilisation strictement requise kAllowMac [SWS_CRYPT_22118].

Concernant la sécurité d'exécution, l'interface est définie comme thread-safe et exception safe (avec noexcept) [SWS_CRYPT_22118]. En interaction avec la gestion des clés, elle constitue le pendant direct de l'assignation basée sur des slots : si une implémentation ou un cas d'usage prend en charge l'utilisation de slots persistants, la surcharge pour KeySlot::Sptr est utilisée à la place [SWS_CRYPT_50026].

Utilisation

La fonction membre virtuelle SetKey de l'interface ara::crypto::cryp::MessageAuthnCodeCtx issue du fichier d'en-tête ara/crypto/cryp/message_authn_code_ctx.h configure le contexte pour le calcul ou la vérification d'un Message Authentication Code (MAC) [SWS_CRYPT_50026]. Comme paramètre, la méthode synchrone accepte un pointeur intelligent keySlot de type KeySlot::Sptr, qui tient à disposition une clé symétrique, et renvoie un ara::core::Result<void> [SWS_CRYPT_50026]. La liaison de la clé est sémantiquement différée : la clé stockée dans le slot n'est prise en compte qu'au moment où le calcul du MAC est effectivement démarré [SWS_CRYPT_50026]. Interprétation : des mises à jour ultérieures du contenu du slot jusqu'au démarrage du calcul devraient ainsi rester effectives. Question Q-d1886811d8af71e3 (ouverte)

Concurrence et sécurité d'exécution

L'interface est définie comme noexcept, garantit la sécurité vis-à-vis des exceptions (exception safe) et est explicitement spécifiée pour l'appel concurrent (thread-safe) [SWS_CRYPT_50026].

Traitement des erreurs et interaction

En cas d'erreur, la méthode garantit une sémantique stricte de rollback, de sorte que l'état précédent du contexte est intégralement préservé [SWS_CRYPT_50026]. Les codes d'erreur suivants peuvent survenir dans l'objet de résultat :

• ara::crypto::CryptoErrc::kIncompatibleObject : le KeySlot transmis est incompatible avec ce contexte de clé symétrique [SWS_CRYPT_50026].
• ara::crypto::CryptoErrc::kUnsupported : l'implémentation concrète du contexte ne prend pas en charge la définition via KeySlot [SWS_CRYPT_50026]. Dans ce cas, la surcharge SetKey(SymmetricKey::Sptr) doit être utilisée comme alternative pour la transmission directe d'une clé [SWS_CRYPT_22118].

La méthode Start de ara::crypto::cryp::MessageAuthnCodeCtx initialise le contexte pour un nouveau calcul de MAC et définit ce faisant un vecteur d'initialisation ou une valeur de nonce via le paramètre iv ([SWS_CRYPT_22110]). Cela est par exemple utilisé pour des algorithmes tels que GMAC ([SWS_CRYPT_22110]). Pour les calculs sans vecteur d'initialisation explicite, la surcharge sans paramètre Start() est disponible comme alternative ([SWS_CRYPT_22111]).

Utilisation et concurrence

L'appel s'effectue de manière synchrone et est spécifié comme thread-safe ainsi que exception safe ([SWS_CRYPT_22110]). Après un appel réussi, des parties de message peuvent être transmises successivement au contexte au moyen de Update ([SWS_CRYPT_22113]). Une opération de streaming en cours et non encore achevée peut être interrompue si nécessaire via Cancel ([SWS_CRYPT_50027]).

Gestion des erreurs

La méthode renvoie un ara::core::Result<void> qui possède une sémantique de rollback en cas d'erreur ([SWS_CRYPT_22110]). Les états d'erreur possibles sont :

• UninitializedContext : aucune clé n'a été préalablement assignée au contexte ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kEmptyKeySlot : un KeySlot configuré est vide ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUsageViolation : les autorisations de la clé ne contiennent pas kAllowMac ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kInvalidInputSize : la taille d'IV transmise n'est pas prise en charge ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kUnsupported : le streaming ou la définition d'un IV n'est pas pris en charge par l'algorithme ou le contexte ([SWS_CRYPT_22110]).
• ara::crypto::CryptoErrc::kBusyResource : une ressource requise est occupée ([SWS_CRYPT_22110]).

Utilisation

La méthode Start() initialise une instance de ara::crypto::cryp::MessageAuthnCodeCtx pour un nouveau calcul de MAC [SWS_CRYPT_22111]. L'appel ne prend aucun paramètre et renvoie un ara::core::Result<void> [SWS_CRYPT_22111]. L'exécution devrait être synchrone, dans la mesure où un objet de résultat est directement fourni. Question Q-1e6e36f4ed1176d3 (ouverte)

Gestion des erreurs et concurrence

Si une erreur survient lors de l'initialisation, la sémantique de rollback s'applique et l'un des codes d'erreur suivants est renvoyé [SWS_CRYPT_22111] :

• UninitializedContext : aucune clé n'a été préalablement assignée au contexte [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUnsupported : le contexte ne prend pas en charge le streaming ou l'algorithme exige impérativement un vecteur d'initialisation (IV) [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kBusyResource : une ressource requise est occupée [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kEmptyKeySlot : un KeySlot configuré est vide [SWS_CRYPT_22111].
• ara::crypto::CryptoErrc::kUsageViolation : la clé ne permet pas de calcul de MAC sans kAllowMac défini [SWS_CRYPT_22111].

La fonction est spécifiée comme sûre vis-à-vis des threads et sûre vis-à-vis des exceptions (exception safe) [SWS_CRYPT_22111].

Interaction dans le déroulement du streaming

Si l'algorithme exige un IV (par ex. GMAC), il convient d'utiliser à la place la surcharge Start(ReadOnlyMemRegion iv) [SWS_CRYPT_22110]. Après un appel réussi, les données de message peuvent être transmises progressivement via Update() [SWS_CRYPT_22113]. Une opération de streaming non encore terminée peut être abandonnée via Cancel() [SWS_CRYPT_50027].

Utilisation

La méthode synchrone Update du contexte ara::crypto::cryp::MessageAuthnCodeCtx sert à compléter le calcul en cours d'un code d'authentification de message (MAC) par un nouveau fragment du message d'entrée [SWS_CRYPT_22113]. Le segment de données à traiter est transmis via le paramètre data sous la forme d'une ReadOnlyMemRegion. En valeur de retour, la fonction renvoie un ara::core::Result<void> qui confirme l'étape intermédiaire réussie ou, en cas d'erreur, renseigne sur la cause de l'erreur [SWS_CRYPT_22113].

Gestion des erreurs et concurrence

En cas d'erreur, une sémantique de rollback est garantie, de sorte que l'état de calcul antérieur reste inchangé [SWS_CRYPT_22113]. Les causes d'erreur possibles sont :

• ara::crypto::CryptoErrc::kProcessingNotStarted : le calcul n'a pas été préalablement initié par l'appel de la méthode Start() [SWS_CRYPT_22113].
• ara::crypto::CryptoErrc::kInvalidInputSize : la taille du bloc de données transmis n'est pas prise en charge par le contexte [SWS_CRYPT_22113].

La méthode est déclarée comme noexcept et spécifiée comme sûre vis-à-vis des threads et sûre vis-à-vis des exceptions (exception safe) [SWS_CRYPT_22113].

Interaction

Afin d'éviter les erreurs de mémoire tampon avec ara::crypto::CryptoErrc::kInvalidInputSize, la taille d'entrée maximale autorisée pour des appels individuels peut être interrogée au préalable via la méthode GetMaximumChunkSize() [SWS_CRYPT_50033]. Après le traitement successif de tous les fragments de message, le calcul du tag MAC devrait typiquement, selon l'interprétation, être finalisé via la méthode Finish() [SWS_CRYPT_50033]. Question Q-7f8eaf8ebbf30d55 (ouverte)

Utilisation

La méthode Verify dans ara::crypto::cryp::MessageAuthnCodeCtx ([SWS_CRYPT_50031]) sert au calcul synchrone d'un condensé MAC sur le tampon d'entrée data et à sa comparaison directe avec la valeur attendue expected. De manière optionnelle, un vecteur d'initialisation peut être transmis via iv. Comme résultat, la fonction renvoie un ara::core::Result<bool> qui contient true si le MAC calculé correspond à la séquence d'octets attendue, sinon false.

Gestion des erreurs

Si la vérification échoue pour des raisons systémiques ou cryptographiques, la méthode renvoie un ara::core::Result avec un code d'erreur correspondant ([SWS_CRYPT_50031]) :

• UninitializedContext : si le contexte n'a pas été initialisé préalablement par l'assignation d'une clé.
• ara::crypto::CryptoErrc::kEmptyKeySlot : si le KeySlot configuré est vide.
• ara::crypto::CryptoErrc::kUsageViolation : si l'utilisation autorisée de la clé n'englobe pas kAllowMac.
• ara::crypto::CryptoErrc::kInvalidInputSize : si la taille de tampon de data, expected ou iv est non autorisée.
• ara::crypto::CryptoErrc::kUnsupported : si l'exécution en un seul appel n'est pas prise en charge ou si la mise à disposition du iv ne correspond pas aux exigences de l'algorithme.
• ara::crypto::CryptoErrc::kBusyResource : en cas de conflits de ressources.

Concurrence et interaction

La méthode est spécifiée comme thread-safe et exception safe ([SWS_CRYPT_50031]). En cas d'erreur, une sémantique de rollback s'applique. À la différence des vérifications de signature asymétriques dans ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_24112], [SWS_CRYPT_50024]), Verify opère sur des contextes MAC symétriques. La taille de tampon maximale traitable dans un appel unique devrait – de manière analogue à l'interrogation de tampon chez les vérificateurs de signature ([SWS_CRYPT_50025]) – être limitée par l'implémentation du contexte. Question Q-51e7427e4e082881 (ouverte)

La méthode VerifySubspan de la classe ara::crypto::cryp::MessageAuthnCodeCtx sert au calcul synchrone d'un condensé MAC et à la comparaison subséquente de ses bits les plus significatifs avec une séquence d'octets attendue [SWS_CRYPT_50032]. Elle traite des données d'entrée via data, les bits de tête attendus via expected ainsi qu'un vecteur d'initialisation optionnel via iv [SWS_CRYPT_50032]. Le résultat est renvoyé sous la forme de ara::core::Result<bool> et signale true en cas de correspondance réussie, et sinon false [SWS_CRYPT_50032].

L'interface est spécifiée comme noexcept, est exception safe ainsi que thread-safe et applique une sémantique de retour arrière en cas d'erreur [SWS_CRYPT_50032]. Les appels ayant échoué fournissent des codes d'erreur spécifiques dans la valeur de retour [SWS_CRYPT_50032] :

• UninitializedContext : Le contexte n'a pas été initialisé auparavant en lui assignant une clé [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUsageViolation : l'utilisation autorisée de la clé n'inclut pas kAllowMac [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kEmptyKeySlot : un KeySlot configuré est actuellement vide [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kInvalidInputSize : La taille des données transmises, de la valeur de contrôle attendue ou de l'IV n'est pas prise en charge [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kUnsupported : L'opération en appel unique (single-call) n'est pas prise en charge ou la fourniture de l'IV contredit les exigences du contexte [SWS_CRYPT_50032].
• ara::crypto::CryptoErrc::kBusyResource : une ressource requise est occupée [SWS_CRYPT_50032].