classe ara::crypto::cryp::SignerPrivateCtx

La méthode Cancel() sert à l'interruption synchrone d'une opération de streaming en cours et non encore achevée au sein de la classe ara::crypto::cryp::SignerPrivateCtx, qui avait été initiée auparavant par un appel de Start() [SWS_CRYPT_50041]. L'interface purement virtuelle virtual ara::core::Result<void> Cancel() noexcept = 0; est déclarée dans l'en-tête ara/crypto/cryp/signer_private_ctx.h, ne prend aucun paramètre d'entrée et signale l'interruption réussie par un ara::core::Result<void> vide [SWS_CRYPT_50041]. Pour l'appelant, la méthode est spécifiée comme sûre vis-à-vis des exceptions (exception safe) et sûre pour les threads en accès concurrent (thread-safe) [SWS_CRYPT_50041].

En ce qui concerne l'ordre des appels et le traitement des erreurs, Cancel() requiert impérativement un traitement actif : si le traitement des données n'a pas été préalablement engagé par un appel de la méthode Start(), l'interruption échoue et renvoie le code d'erreur ara::crypto::CryptoErrc::kProcessingNotStarted avec une sémantique de rollback définie [SWS_CRYPT_50041]. Interprétation : après un appel réussi de Cancel(), le contexte devrait revenir à un état initial non démarré, de sorte qu'une nouvelle opération de signature ou de streaming puisse être commencée. Question Q-348fb3ae43e424c9 (ouverte)

La conception suit un principe uniforme pour toutes les opérations de streaming du module cryptographique. Des signatures et des sémantiques d'erreur strictement identiques existent pour des contextes apparentés tels que VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SymmetricCipherCtx [SWS_CRYPT_50046], HashFunctionCtx [SWS_CRYPT_50058], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] ainsi que EncryptorPublicCtx [SWS_CRYPT_50089].

Utilisation

La méthode ara::crypto::cryp::SignerPrivateCtx::Finish finalise la génération de signature de manière synchrone et écrit la signature calculée directement dans le tampon de sortie fourni signature [SWS_CRYPT_50040]. La fonction attend comme paramètres d'entrée la zone mémoire accessible en écriture signature (type ReadWriteMemRegion) et le format souhaité signatureFormat (type FormatId) [SWS_CRYPT_50040]. Comme valeur de retour, ara::core::Result<size_t> fournit la taille réelle en octets des données de signature écrites ; cette quantité de données peut être inférieure à la capacité du tampon cible [SWS_CRYPT_50040].

Gestion des erreurs

Une sémantique de rollback est spécifiée pour tous les cas d'erreur survenant [SWS_CRYPT_50040]. Les codes d'erreur suivants peuvent être renvoyés via le résultat :

• ara::crypto::CryptoErrc::kProcessingNotStarted : la génération de signature n'a pas été démarrée avec succès au préalable [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kInsufficientCapacity : la capacité du tampon de sortie transmis signature est insuffisante [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kUnsupportedFormat : la valeur de signatureFormat est inconnue ou n'est pas prise en charge [SWS_CRYPT_50040].

Concurrence et restrictions

La méthode est spécifiée comme thread-safe et exception safe et ne doit lever aucune exception (noexcept) [SWS_CRYPT_50040]. Un appel valide exige impérativement que le processus de génération ait été initié avec succès au préalable dans le contexte [SWS_CRYPT_50040].

Interaction

La méthode ara::crypto::cryp::VerifierPublicCtx::Finish constitue le pendant fonctionnel direct pour la vérification de la signature générée [SWS_CRYPT_50022]. Par comparaison avec les contextes de calculs de hachage ou de MAC, dans lesquels Finish() finalise uniquement le calcul et le résultat intermédiaire ou final est récupéré séparément [SWS_CRYPT_21115] [SWS_CRYPT_21116], SignerPrivateCtx::Finish écrit la signature directement dans le tampon [SWS_CRYPT_50040].

Utilisation

La méthode virtuelle SetKey de la classe ara::crypto::cryp::SignerPrivateCtx (#include "ara/crypto/cryp/signer_private_ctx.h") configure le contexte de signature pour l'utilisation d'une clé privée fournie [SWS_CRYPT_23515]. key de type PrivateKey::Sptr est transmis comme paramètre en tant qu'objet clé source [SWS_CRYPT_23515]. La méthode est exécutée de manière synchrone et renvoie un ara::core::Result<void> qui est vide en cas de succès ou qui transporte le code d'erreur survenu en cas d'erreur [SWS_CRYPT_23515].

Gestion des erreurs

Si une erreur survient pendant la configuration, une sémantique de rollback s'applique [SWS_CRYPT_23515]. Les codes d'erreur suivants sont spécifiés :

• ara::crypto::CryptoErrc::kIncompatibleObject : L'objet clé transmis est incompatible avec le contexte actuel [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUsageViolation : L'utilisation autorisée de la clé n'inclut pas la génération de signature (kAllowSig Generation) [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUnsupported : Le contexte spécifique prend exclusivement en charge la définition via un KeySlot [SWS_CRYPT_23515].

Concurrence et restrictions

L'interface est déclarée comme noexcept et classée selon la spécification à la fois comme sûre vis-à-vis des exceptions (« exception safe ») et comme thread-safe (« thread-safe ») [SWS_CRYPT_23515].

Interaction

Dans SignerPrivateCtx, il existe alternativement la surcharge SetKey(KeySlot::Sptr), qui configure le contexte de telle sorte que la clé stockée dans un KeySlot ne soit prise en compte qu'au moment du démarrage du calcul de la signature [SWS_CRYPT_50036]. Pour la vérification des signatures côté vérification, le pendant fonctionnel SetKey avec PublicKey::Sptr au sein de ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_24115] est utilisé.

Utilisation

La méthode SetKey configure le contexte de signature [SWS_CRYPT_50036] pour l'utilisation d'une clé située dans le KeySlot::Sptr transmis. La clé n'est exploitée qu'au moment où le calcul effectif de la signature est démarré [SWS_CRYPT_50036]. L'appel s'effectue de manière synchrone, est déclaré comme noexcept et fournit un ara::core::Result<void> en retour [SWS_CRYPT_50036].

Gestion des erreurs

Si la configuration échoue, une erreur est transmise dans l'objet de retour, la sémantique de rollback s'appliquant [SWS_CRYPT_50036] :

• ara::crypto::CryptoErrc::kIncompatibleObject : survient lorsque le keySlot fourni n'est pas compatible avec ce contexte de signature [SWS_CRYPT_50036].
• ara::crypto::CryptoErrc::kUnsupported : est signalé si le contexte prend exclusivement en charge la définition directe d'un PrivateKey [SWS_CRYPT_50036].

Concurrence et interaction

L'interface appartient à la classe ara::crypto::cryp::SignerPrivateCtx et est spécifiée comme thread-safe ainsi qu'exception-safe [SWS_CRYPT_50036]. En plus de cette variante basée sur des slots, SignerPrivateCtx met également à disposition une surcharge qui accepte directement un objet PrivateKey::Sptr [SWS_CRYPT_23515]. Des liaisons de slot analogues existent pour d'autres contextes cryptographiques, par exemple pour le contrôle de signature avec KeySlot dans VerifierPublicCtx [SWS_CRYPT_50018] ou pour la dérivation de clé dans KeyDerivationFunctionCtx [SWS_CRYPT_50010].

La méthode Sign signe un message de manière synchrone en une seule étape conformément à [SWS_CRYPT_23512]. Elle reçoit le message d'entrée à signer (message), le tampon cible (signature), le format de signature souhaité (signatureFormat) ainsi que, facultativement, une valeur de contexte (context). En cas de succès, la fonction retourne via ara::core::Result<std::size_t> la taille réelle en octets de la signature générée, qui peut être inférieure à la capacité du tampon cible [SWS_CRYPT_23512].

Concernant la concurrence et la sécurité vis-à-vis des exceptions, la méthode est déclarée comme noexcept, est considérée comme exception safe et est explicitement spécifiée comme thread-safe [SWS_CRYPT_23512].

Avant l'appel, le contexte doit être correctement initialisé avec une valeur de clé ; sinon, UninitializedContext est signalé [SWS_CRYPT_23512]. En ce qui concerne la longueur d'entrée, Sign interagit avec [SWS_CRYPT_50042] : via GetMaximumChunkSize, la taille maximale de tampon prise en charge pour le traitement en une seule étape peut être déterminée afin de prévenir des erreurs telles que ara::crypto::CryptoErrc::kInvalidInputSize [SWS_CRYPT_23512] [SWS_CRYPT_50042].

Le traitement des erreurs prévoit des sémantiques de rollback pour des codes d'erreur spécifiques [SWS_CRYPT_23512] :

• ara::crypto::CryptoErrc::kInsufficientCapacity : Le tampon de sortie signature est trop petit.
• ara::crypto::CryptoErrc::kUnsupported : Le traitement en une seule étape n'est pas pris en charge, ou l'indication de contexte context n'est pas conforme aux exigences.
• ara::crypto::CryptoErrc::kUnsupportedFormat : Le FormatId spécifié est inconnu ou non pris en charge.
• ara::crypto::CryptoErrc::kUsageViolation : L'utilisation autorisée de la clé n'inclut pas kAllowSig Generation.
• ara::crypto::CryptoErrc::kEmptyKeySlot ou ara::crypto::CryptoErrc::kBusyResource : Le KeySlot configuré est vide ou une ressource requise est occupée.

La méthode sans paramètre Start initialise un contexte de la classe ara::crypto::cryp::SignerPrivateCtx pour une nouvelle génération de signature [SWS_CRYPT_50037]. L'appel s'effectue de manière synchrone, est déclaré comme noexcept et fournit un ara::core::Result<void> vide en cas d'initialisation réussie ou un code d'erreur en cas d'échec [SWS_CRYPT_50037].

En cas d'erreur, l'opération prend en charge la sémantique de rollback [SWS_CRYPT_50037]. Parmi les causes d'erreur définies issues de ara::crypto::CryptoErrc figurent :

• kUninitializedContext : le contexte n'a pas été initialisé au préalable par la fourniture d'une clé [SWS_CRYPT_50037].
• kEmptyKeySlot : un KeySlot configuré est actuellement vide [SWS_CRYPT_50037].
• kUsageViolation : les droits d'accès de la clé assignée ne comprennent pas kAllowSigGeneration [SWS_CRYPT_50037].
• kBusyResource : une ressource requise pour l'opération est occupée [SWS_CRYPT_50037].
• kUnsupported : le contexte ne prend pas en charge le streaming ou l'algorithme de signature requiert impérativement la spécification d'une valeur de contexte [SWS_CRYPT_50037].

Conformément à la spécification, la fonction est thread-safe ainsi qu'exception-safe [SWS_CRYPT_50037]. Si l'algorithme requiert une valeur de contexte spécifique, la variante surchargée Start(ReadOnlyMemRegion context) doit être utilisée à la place [SWS_CRYPT_50038]. Après un appel réussi de Start, les parties de message à signer peuvent être traitées de manière continue via Update [SWS_CRYPT_50039].

La méthode Start sert à l'initialisation synchrone du contexte ara::crypto::cryp::SignerPrivateCtx pour une nouvelle génération de signature avec fourniture d'une valeur de contexte ([SWS_CRYPT_50038]). Elle reçoit le paramètre context de type ReadOnlyMemRegion et renvoie un ara::core::Result<void>. La fonction est spécifiée comme noexcept=0, sans émission d'exceptions ainsi que déclarée comme sûre au regard des threads ([SWS_CRYPT_50038]).

En cas d'erreur, l'état du contexte est laissé inchangé via une sémantique de rollback ([SWS_CRYPT_50038]). Les causes d'erreur spécifiées sont :

• UninitializedContext : si le contexte n'a pas été initialisé préalablement par la fourniture d'une clé.
• ara::crypto::CryptoErrc::kUnsupported : si le contexte ne prend pas en charge le streaming ou si l'algorithme n'autorise aucune valeur de contexte.
• ara::crypto::CryptoErrc::kInvalidInputSize : si la taille de tampon de la valeur de contexte transmise est invalide.
• ara::crypto::CryptoErrc::kEmptyKeySlot : si un slot de clé configuré est actuellement vide.
• ara::crypto::CryptoErrc::kUsageViolation : si l'utilisation autorisée de la clé n'inclut pas la génération de signature (kAllowSig Generation).
• ara::crypto::CryptoErrc::kBusyResource : si une ressource requise est occupée.

Dans le déroulement de traitement typique, les données à signer devraient être transmises successivement via Update ([SWS_CRYPT_50039]) après un démarrage réussi. Question Q-7b821391730c9d38 (ouverte) Dans la mesure où le procédé cryptographique ne requiert aucune valeur de contexte, la surcharge sans paramètre Start() est disponible comme alternative ([SWS_CRYPT_50037]).

La méthode Update sert, dans [SWS_CRYPT_50039], à étendre de manière continue l'état interne d'un calcul de signature avec une section supplémentaire du message. L'appel s'effectue de manière synchrone et traite la zone mémoire data transmise de type ReadOnlyMemRegion. Comme résultat, la fonction fournit un ara::core::Result<void> qui ne contient aucune valeur en cas de traitement réussi ou, dans le cas contraire, encapsule un code d'erreur [SWS_CRYPT_50039].

En cas d'erreur, les valeurs de retour possèdent une sémantique de rollback [SWS_CRYPT_50039] :

• ara::crypto::CryptoErrc::kProcessingNotStarted : survient lorsque le calcul de signature n'a pas été initié au préalable par l'appel de la méthode Start() [SWS_CRYPT_50039].
• ara::crypto::CryptoErrc::kInvalidInputSize : est signalé si la taille des données d'entrée fournies n'est pas prise en charge par le contexte [SWS_CRYPT_50039].

En ce qui concerne la concurrence et la sécurité, la méthode est déclarée comme thread-safe ainsi qu'exception safe [SWS_CRYPT_50039]. En interaction avec le contexte de signature, le calcul exige impérativement que le déroulement ait été démarré avec Start(). La taille maximale admissible du tampon pour des appels individuels peut être consultée via GetMaximumChunkSize() [SWS_CRYPT_50042] ; cette valeur limite devrait représenter le plafond dont le dépassement entraîne kInvalidInputSize. Question Q-cf204a853a730365 (ouverte)