class ara::crypto::cryp::SignerPrivateCtx

Die Methode Cancel() dient dem synchronen Abbruch einer laufenden, noch nicht abgeschlossenen Streaming-Operation innerhalb der Klasse ara::crypto::cryp::SignerPrivateCtx, welche zuvor durch einen Aufruf von Start() initiiert wurde [SWS_CRYPT_50041]. Die rein virtuelle Schnittstelle virtual ara::core::Result<void> Cancel() noexcept = 0; ist im Header ara/crypto/cryp/signer_private_ctx.h deklariert, nimmt keine Übergabeparameter entgegen und signalisiert den erfolgreichen Abbruch über ein leeres ara::core::Result<void> [SWS_CRYPT_50041]. Für den Aufrufer ist die Methode als ausnahmesicher (exception safe) und nebenläufig threadsicher (thread-safe) spezifiziert [SWS_CRYPT_50041].

In Bezug auf die Aufrufreihenfolge und Fehlerbehandlung setzt Cancel() zwingend eine aktive Verarbeitung voraus: Wurde die Datenverarbeitung zuvor nicht durch einen Aufruf der Methode Start() eingeleitet, schlägt der Abbruch fehl und liefert den Fehlercode ara::crypto::CryptoErrc::kProcessingNotStarted mit definierter Rollback-Semantik zurück [SWS_CRYPT_50041]. Interpretation: Nach einem erfolgreichen Aufruf von Cancel() dürfte der Kontext wieder in einen ungestarteten Grundzustand zurückkehren, sodass ein neuer Signatur- oder Streaming-Vorgang begonnen werden kann. Frage Q-348fb3ae43e424c9 (offen)

Das Design folgt einem einheitlichen Prinzip für alle Streaming-Operationen im Kryptomodul. Vollkommen identische Signaturen und Fehlersemantiken existieren für verwandte Kontexte wie VerifierPublicCtx [SWS_CRYPT_50023], MessageAuthnCodeCtx [SWS_CRYPT_50027], SymmetricCipherCtx [SWS_CRYPT_50046], HashFunctionCtx [SWS_CRYPT_50058], DecryptorPrivateCtx [SWS_CRYPT_50069], AuthCipherCtx [SWS_CRYPT_50077] sowie EncryptorPublicCtx [SWS_CRYPT_50089].

Verwendung

Die Methode ara::crypto::cryp::SignerPrivateCtx::Finish schließt die Signaturerzeugung synchron ab und schreibt die berechnete Signatur direkt in den bereitgestellten Ausgabepuffer signature [SWS_CRYPT_50040]. Die Funktion erwartet als Übergabeparameter den beschreibbaren Speicherbereich signature (Typ ReadWriteMemRegion) und das gewünschte Format signatureFormat (Typ FormatId) [SWS_CRYPT_50040]. Als Rückgabewert liefert ara::core::Result<size_t> die tatsächliche Bytegröße der geschriebenen Signaturdaten; diese Datenmenge darf kleiner sein als die Kapazität des Zielpuffers [SWS_CRYPT_50040].

Fehlerbehandlung

Für alle auftretenden Fehlerfälle ist eine Rollback-Semantik spezifiziert [SWS_CRYPT_50040]. Folgende Fehlercodes können über das Ergebnis zurückgegeben werden:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Die Signaturerzeugung wurde zuvor nicht erfolgreich gestartet [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kInsufficientCapacity: Die Kapazität des übergebenen Ausgabepuffers signature ist zu gering [SWS_CRYPT_50040].
• ara::crypto::CryptoErrc::kUnsupportedFormat: Der Wert von signatureFormat ist unbekannt oder wird nicht unterstützt [SWS_CRYPT_50040].

Nebenläufigkeit und Einschränkungen

Die Methode ist als thread-safe und exception safe spezifiziert und darf keine Exceptions werfen (noexcept) [SWS_CRYPT_50040]. Ein gültiger Aufruf setzt zwingend voraus, dass der Erzeugungsvorgang im Kontext zuvor erfolgreich initiiert worden ist [SWS_CRYPT_50040].

Zusammenspiel

Das direkte funktionale Gegenstück zur Verifikation der erzeugten Signatur bildet die Methode ara::crypto::cryp::VerifierPublicCtx::Finish [SWS_CRYPT_50022]. Im Vergleich zu Kontexten für Hash- oder MAC-Berechnungen, bei denen Finish() nur die Berechnung finalisiert und das Zwischen- oder Endergebnis separat abgeholt wird [SWS_CRYPT_21115] [SWS_CRYPT_21116], schreibt SignerPrivateCtx::Finish die Signatur unmittelbar in den Puffer [SWS_CRYPT_50040].

Verwendung

Die virtuelle Methode SetKey der Klasse ara::crypto::cryp::SignerPrivateCtx (#include "ara/crypto/cryp/signer_private_ctx.h") konfiguriert den Signierkontext für die Nutzung eines bereitgestellten privaten Schlüssels [SWS_CRYPT_23515]. Als Parameter wird key vom Typ PrivateKey::Sptr als Quell-Schlüsselobjekt übergeben [SWS_CRYPT_23515]. Die Methode wird synchron ausgeführt und liefert ein ara::core::Result<void> zurück, welches im Erfolgsfall leer ist oder im Fehlerfall den aufgetretenen Fehlercode transportiert [SWS_CRYPT_23515].

Fehlerbehandlung

Tritt während der Konfiguration ein Fehler auf, greift eine Rollback-Semantik [SWS_CRYPT_23515]. Folgende Fehlercodes sind spezifiziert:

• ara::crypto::CryptoErrc::kIncompatibleObject: Das übergebene Schlüsselobjekt ist inkompatibel mit dem aktuellen Kontext [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUsageViolation: Die zulässige Verwendung des Schlüssels umfasst nicht die Signaturerzeugung (kAllowSig Generation) [SWS_CRYPT_23515].
• ara::crypto::CryptoErrc::kUnsupported: Der spezifische Kontext unterstützt ausschließlich das Setzen über einen KeySlot [SWS_CRYPT_23515].

Nebenläufigkeit und Einschränkungen

Die Schnittstelle ist als noexcept deklariert und spezifikationsgemäß sowohl als ausnahmesicher („exception safe“) als auch als thread-sicher („thread-safe“) klassifiziert [SWS_CRYPT_23515].

Zusammenspiel

In SignerPrivateCtx existiert alternativ die Überladung SetKey(KeySlot::Sptr), welche den Kontext so konfiguriert, dass der in einem KeySlot abgelegte Schlüssel erst zum Startzeitpunkt der Signaturberechnung herangezogen wird [SWS_CRYPT_50036]. Zur Prüfung von Signaturen dient auf Verifikationsseite das funktionale Gegenstück SetKey mit PublicKey::Sptr innerhalb von ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_24115].

Verwendung

Die Methode SetKey konfiguriert den Signierkontext [SWS_CRYPT_50036] für die Verwendung eines Schlüssels, der sich in dem übergebenen KeySlot::Sptr befindet. Der Schlüssel wird erst zu dem Zeitpunkt herangezogen, an dem die eigentliche Signaturberechnung gestartet wird [SWS_CRYPT_50036]. Der Aufruf erfolgt synchron, ist als noexcept deklariert und liefert ein ara::core::Result<void> zurück [SWS_CRYPT_50036].

Fehlerbehandlung

Schlägt die Konfiguration fehl, wird ein Fehler im Rückgabeobjekt übermittelt, wobei Rollback-Semantik gilt [SWS_CRYPT_50036]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Tritt auf, wenn der bereitgestellte keySlot nicht mit diesem Signierkontext kompatibel ist [SWS_CRYPT_50036].
• ara::crypto::CryptoErrc::kUnsupported: Wird gemeldet, falls der Kontext ausschließlich das direkte Setzen eines PrivateKey unterstützt [SWS_CRYPT_50036].

Nebenläufigkeit und Zusammenspiel

Die Schnittstelle gehört zur Klasse ara::crypto::cryp::SignerPrivateCtx und ist als thread-safe sowie exception-safe spezifiziert [SWS_CRYPT_50036]. Neben dieser slotbasierten Variante stellt SignerPrivateCtx auch eine Überladung bereit, die direkt ein PrivateKey::Sptr-Objekt entgegennimmt [SWS_CRYPT_23515]. Analoge Slot-Bindungen existieren für weitere kryptografische Kontexte, etwa zur Signaturprüfung mit KeySlot in VerifierPublicCtx [SWS_CRYPT_50018] oder zur Schlüsselableitung in KeyDerivationFunctionCtx [SWS_CRYPT_50010].

Die Methode Sign signiert eine Nachricht synchron in einem Einzelschritt gemäß [SWS_CRYPT_23512]. Sie nimmt die zu signierende Eingabenachricht (message), den Zielpuffer (signature), das gewünschte Signaturformat (signatureFormat) sowie optional einen Kontextwert (context) entgegen. Im Erfolgsfall liefert die Funktion über ara::core::Result<std::size_t> die tatsächliche Bytegröße der erzeugten Signatur zurück, welche kleiner als die Kapazität des Zielpuffers sein kann [SWS_CRYPT_23512].

Hinsichtlich Nebenläufigkeit und Exception-Sicherheit ist die Methode als noexcept deklariert, gilt als exception safe und ist explizit als thread-safe spezifiziert [SWS_CRYPT_23512].

Vor dem Aufruf muss der Kontext ordnungsgemäß mit einem Schlüsselwert initialisiert sein; andernfalls wird UninitializedContext gemeldet [SWS_CRYPT_23512]. Bezüglich der Eingabelänge steht Sign im Zusammenspiel mit [SWS_CRYPT_50042]: Über GetMaximumChunkSize kann die maximal unterstützte Puffergröße für die Einzelschrittverarbeitung ermittelt werden, um Fehlern wie ara::crypto::CryptoErrc::kInvalidInputSize vorzubeugen [SWS_CRYPT_23512] [SWS_CRYPT_50042].

Die Fehlerbehandlung sieht Rollback-Semantiken für spezifische Fehlercodes vor [SWS_CRYPT_23512]:

• ara::crypto::CryptoErrc::kInsufficientCapacity: Der Ausgabepuffer signature ist zu klein.
• ara::crypto::CryptoErrc::kUnsupported: Die Einzelschrittverarbeitung wird nicht unterstützt, oder die Kontextangabe context entspricht nicht den Vorgaben.
• ara::crypto::CryptoErrc::kUnsupportedFormat: Das angegebene FormatId ist unbekannt oder nicht unterstützt.
• ara::crypto::CryptoErrc::kUsageViolation: Die zulässige Schlüsselverwendung beinhaltet nicht kAllowSig Generation.
• ara::crypto::CryptoErrc::kEmptyKeySlot oder ara::crypto::CryptoErrc::kBusyResource: Der konfigurierte KeySlot ist leer bzw. eine erforderliche Ressource ist belegt.

Die parameterlose Methode Start initialisiert einen Kontext der Klasse ara::crypto::cryp::SignerPrivateCtx für eine neue Signaturerzeugung [SWS_CRYPT_50037]. Der Aufruf erfolgt synchron, ist als noexcept deklariert und liefert ein leeres ara::core::Result<void> bei erfolgreicher Initialisierung oder einen Fehlercode im Fehlerfall [SWS_CRYPT_50037].

Im Fehlerfall unterstützt die Operation Rollback-Semantik [SWS_CRYPT_50037]. Zu den definierten Fehlerursachen aus ara::crypto::CryptoErrc gehören:

• kUninitializedContext: Der Kontext wurde vorab nicht durch das Bereitstellen eines Schlüssels initialisiert [SWS_CRYPT_50037].
• kEmptyKeySlot: Ein konfigurierter Key-Slot ist aktuell leer [SWS_CRYPT_50037].
• kUsageViolation: Die Berechtigungen des zugewiesenen Schlüssels umfassen nicht kAllowSigGeneration [SWS_CRYPT_50037].
• kBusyResource: Eine für die Operation benötigte Ressource ist belegt [SWS_CRYPT_50037].
• kUnsupported: Der Kontext unterstützt kein Streaming oder der Signaturalgorithmus erfordert zwingend die Angabe eines Kontextwertes [SWS_CRYPT_50037].

Gemäß Spezifikation ist die Funktion thread-safe sowie exception safe [SWS_CRYPT_50037]. Erfordert der Algorithmus einen spezifischen Kontextwert, muss alternativ die überladene Variante Start(ReadOnlyMemRegion context) verwendet werden [SWS_CRYPT_50038]. Nach erfolgreichem Aufruf von Start können zu signierende Nachrichtenteile fortlaufend über Update verarbeitet werden [SWS_CRYPT_50039].

Die Methode Start dient der synchronen Initialisierung des Kontexts ara::crypto::cryp::SignerPrivateCtx für eine neue Signaturerzeugung unter Bereitstellung eines Kontextwerts ([SWS_CRYPT_50038]). Sie nimmt den Parameter context vom Typ ReadOnlyMemRegion entgegen und liefert ein ara::core::Result<void> zurück. Die Funktion ist als noexcept=0 spezifiziert, exception-safe sowie als threadsicher deklariert ([SWS_CRYPT_50038]).

Im Fehlerfall wird der Kontextzustand über eine Rollback-Semantik unverändert belassen ([SWS_CRYPT_50038]). Spezifizierte Fehlerursachen sind:

• UninitializedContext: wenn der Kontext nicht zuvor durch Bereitstellen eines Schlüssels initialisiert wurde.
• ara::crypto::CryptoErrc::kUnsupported: falls der Kontext kein Streaming unterstützt oder der Algorithmus keinen Kontextwert zulässt.
• ara::crypto::CryptoErrc::kInvalidInputSize: wenn die Puffergröße des übergebenen Kontextwerts ungültig ist.
• ara::crypto::CryptoErrc::kEmptyKeySlot: wenn ein konfigurierter Schlüssel-Slot derzeit leer ist.
• ara::crypto::CryptoErrc::kUsageViolation: falls die erlaubte Nutzung des Schlüssels nicht die Signaturerzeugung (kAllowSig Generation) beinhaltet.
• ara::crypto::CryptoErrc::kBusyResource: falls eine erforderliche Ressource belegt ist.

Im typischen Verarbeitungsablauf dürften die zu signierenden Daten nach erfolgreichem Start sukzessive über Update ([SWS_CRYPT_50039]) übergeben werden. Frage Q-7b821391730c9d38 (offen) Sofern das kryptografische Verfahren keinen Kontextwert erfordert, steht alternativ die parameterlose Überladung Start() bereit ([SWS_CRYPT_50037]).

Die Methode Update dient in [SWS_CRYPT_50039] dazu, den internen Zustand einer Signaturberechnung fortlaufend um einen weiteren Teilabschnitt der Nachricht zu erweitern. Der Aufruf erfolgt synchron und verarbeitet den übergebenen Speicherbereich data vom Typ ReadOnlyMemRegion. Als Ergebnis liefert die Funktion ein ara::core::Result<void>, das bei erfolgreicher Verarbeitung keinen Wert enthält oder andernfalls einen Fehlercode kapselt [SWS_CRYPT_50039].

Im Fehlerfall besitzen die Rückgabewerte eine Rollback-Semantik [SWS_CRYPT_50039]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Tritt auf, wenn die Signaturberechnung nicht zuvor durch den Aufruf der Methode Start() initiiert wurde [SWS_CRYPT_50039].
• ara::crypto::CryptoErrc::kInvalidInputSize: Wird gemeldet, falls die Größe der bereitgestellten Eingabedaten vom Kontext nicht unterstützt wird [SWS_CRYPT_50039].

Hinsichtlich der Nebenläufigkeit und Sicherheit ist die Methode als thread-safe sowie exception safe deklariert [SWS_CRYPT_50039]. Im Zusammenspiel mit dem Signierungskontext setzt die Berechnung zwingend voraus, dass der Ablauf mit Start() begonnen wurde. Die maximal zulässige Puffergröße für einzelne Aufrufe lässt sich über GetMaximumChunkSize() abfragen [SWS_CRYPT_50042]; dieser Grenzwert dürfte die Obergrenze darstellen, deren Überschreitung zu kInvalidInputSize führt. Frage Q-cf204a853a730365 (offen)