class ara::crypto::cryp::VerifierPublicCtx

Verwendung und Semantik

Die Methode Cancel() bricht eine laufende Streaming-Operation ab, die zuvor durch Start() initiiert und noch nicht abgeschlossen wurde [SWS_CRYPT_50023]. Sie ist im Header ara/crypto/cryp/verifier_public_ctx.h als pure virtual Methode des Kontexts ara::crypto::cryp::VerifierPublicCtx definiert [SWS_CRYPT_50023]. Der Aufruf erfolgt synchron und ohne Argumente. Als Rückgabewert dient ein ara::core::Result<void>, welches im Erfolgsfall leer ist und den erfolgreichen Abbruch der Operation bestätigt [SWS_CRYPT_50023].

Fehlerbehandlung

Falls die Datenverarbeitung noch nicht durch den Aufruf der Methode Start() begonnen wurde, schlägt die Abbruchoperation fehl. In diesem Szenario liefert die Funktion ein Fehlerergebnis mit dem Fehlercode ara::crypto::CryptoErrc::kProcessingNotStarted unter Gewährleistung von Rollback-Semantik zurück [SWS_CRYPT_50023].

Nebenläufigkeit und Einschränkungen

Die Spezifikation weist die Methode als thread-sicher (thread-safe) und ausnahmesicher (exception safe) mit der Kennzeichnung noexcept aus [SWS_CRYPT_50023]. Interpretation: Nach dem erfolgreichen Abbruch dürfte der Kontext wieder in den Ausgangszustand vor Beginn der Verarbeitung zurückfallen, sodass ein erneuter Streaming-Vorgang begonnen werden kann. Frage Q-d80d09c8a8311bbc (offen)

Zusammenspiel im Modul crypt

Dieses einheitliche Abbruchmuster mit identischer Signatur und Fehlerbehandlung gilt konsistent für alle Streaming-Kontexte des Moduls crypt:

• MessageAuthnCodeCtx für Message Authentication Codes [SWS_CRYPT_50027],
• SignerPrivateCtx für die Erzeugung digitaler Signaturen [SWS_CRYPT_50041],
• SymmetricCipherCtx für symmetrische Verschlüsselung und Entschlüsselung [SWS_CRYPT_50046],
• HashFunctionCtx für kryptografische Hash-Operationen [SWS_CRYPT_50058],
• DecryptorPrivateCtx für asymmetrische Entschlüsselung [SWS_CRYPT_50069],
• AuthCipherCtx für authentifizierte Chiffrierung [SWS_CRYPT_50077] sowie
• EncryptorPublicCtx für asymmetrische Verschlüsselung [SWS_CRYPT_50089].

Die Methode Finish in ara::crypto::cryp::VerifierPublicCtx schließt eine Signaturprüfung ab und liefert das Verifikationsergebnis zurück [SWS_CRYPT_50022]. Sie nimmt über den Eingabepuffer signature (Typ ReadOnlyMemRegion) die zu prüfende Signatur sowie über signatureFormat (Typ FormatId) deren Format entgegen [SWS_CRYPT_50022]. Der Aufruf erfolgt synchron und ist gemäß Spezifikation thread-safe sowie exception safe deklariert [SWS_CRYPT_50022].

Als Rückgabewert dient ein ara::core::Result<bool> [SWS_CRYPT_50022]: Bei erfolgreicher Validierung der Signatur enthält das Ergebnis true, bei inhaltlich ungültiger Signatur false. Tritt hingegen ein Verarbeitungsfehler auf, wird ein entsprechender Fehlercode zurückgegeben [SWS_CRYPT_50022]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Die Operation wurde zuvor nicht erfolgreich gestartet (Rollback-Semantik) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidInputSize: Die Puffergröße von signature ist ungültig (Rollback-Semantik) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kUnsupportedFormat: Das angegebene Format signatureFormat wird nicht unterstützt (Rollback-Semantik) [SWS_CRYPT_50022].
• ara::crypto::CryptoErrc::kInvalidArgument: Die Signatur entspricht nicht dem spezifizierten Format (Rollback-Semantik) [SWS_CRYPT_50022].

Im kryptografischen Ablauf bildet diese Funktion das Gegenstück zur Signaturerzeugung via ara::crypto::cryp::SignerPrivateCtx::Finish [SWS_CRYPT_50040], welche eine Signatur in einen Ausgabepuffer schreibt. Sämtliche gemeldeten Fehler besitzen Rollback-Semantik [SWS_CRYPT_50022], sodass der Kontextzustand bei einem Scheitern konsistent bleibt.

Die Methode SetKey konfiguriert eine Instanz von VerifierPublicCtx für die Verwendung eines konkreten öffentlichen Schlüssels zur Signaturprüfung ([SWS_CRYPT_24115]). Über den Parameter key wird ein Zeiger vom Typ PublicKey::Sptr übergeben. Der Aufruf erfolgt synchron und gibt ein ara::core::Result<void> zurück, das im Erfolgsfall leer ist oder einen spezifischen Fehlercode kapselt.

Die Operation ist laut Spezifikation threadsicher und ausnahmesicher (exception safe) ausgelegt ([SWS_CRYPT_24115]). Tritt während der Schlüsselbindung ein Fehler auf, greift für alle Fehlerfälle eine Rollback-Semantik, sodass der Kontext in einem konsistenten Zustand verbleibt:

• CryptoErrc::kIncompatibleObject: Der übergebene Schlüssel ist mit dem Signaturprüfungskontext inkompatibel ([SWS_CRYPT_24115]).
• CryptoErrc::kUsageViolation: Die Berechtigungen des Schlüssels erlauben keine Signaturprüfung (Fehlen des Nutzungsflags für Signaturverifikation) ([SWS_CRYPT_24115]).
• ara::crypto::CryptoErrc::kUnsupported: Die Kontextimplementierung unterstützt ausschließlich das Binden eines Schlüssels über einen KeySlot ([SWS_CRYPT_24115]).

Im kryptografischen Workflow bildet SetKey das öffentliche Gegenstück zu SignerPrivateCtx::SetKey ([SWS_CRYPT_23515]). Sofern ein Kontext die direkte Schlüsselübergabe via PublicKey::Sptr nicht erlaubt oder Schlüssel in gesicherten Slots verwaltet werden, steht alternativ die Überladung mittels KeySlot::Sptr zur Verfügung ([SWS_CRYPT_50018]).

Verwendung

Die Methode SetKey der Klasse ara::crypto::cryp::VerifierPublicCtx konfiguriert den Verifikationskontext für die Nutzung eines Schlüssels, der in einem übergebenen KeySlot hinterlegt ist [SWS_CRYPT_50018]. Der Schlüssel wird zu dem Zeitpunkt herangezogen, an dem die Signaturprüfung gestartet wird [SWS_CRYPT_50018].

Als Parameter dient ein Smart Pointer keySlot vom Typ KeySlot::Sptr, welcher einen öffentlichen Schlüssel enthält [SWS_CRYPT_50018]. Die Funktion arbeitet synchron und gibt ein ara::core::Result<void> zurück, um einen erfolgreichen Abschluss oder Fehler anzuzeigen [SWS_CRYPT_50018].

Fehlerbehandlung und Semantik

Die Operation ist als noexcept und exception safe spezifiziert [SWS_CRYPT_50018]. Tritt ein Fehler auf, greift eine Rollback-Semantik [SWS_CRYPT_50018]:

• ara::crypto::CryptoErrc::kIncompatibleObject: Der bereitgestellte KeySlot ist mit diesem Kontext inkompatibel [SWS_CRYPT_50018].
• ara::crypto::CryptoErrc::kUnsupported: Der Kontext unterstützt ausschließlich das direkte Setzen eines PublicKey [SWS_CRYPT_50018].

Nebenläufigkeit und Zusammenspiel

Die Methode ist thread-safe spezifiziert [SWS_CRYPT_50018]. Als Alternative zum KeySlot bietet VerifierPublicCtx eine Überladung, um einen PublicKey direkt zu setzen [SWS_CRYPT_24115]. Eine entsprechende Schlüsselkonfiguration über einen KeySlot existiert analog auch in anderen Kontexten wie SignerPrivateCtx [SWS_CRYPT_50036] oder MessageAuthnCodeCtx [SWS_CRYPT_50026].

Verwendung

Die synchrone Methode Start() der Schnittstelle ara::crypto::cryp::VerifierPublicCtx ([SWS_CRYPT_50019]) initialisiert den Kontext für eine neue kryptografische Signaturprüfung im Streaming-Betrieb. Die Funktion nimmt keine Übergabeparameter entgegen, ist als noexcept deklariert und gibt ein ara::core::Result<void> zurück, das im Erfolgsfall leer ist.

Fehlerbehandlung und Rollback

Tritt bei der Ausführung ein Fehler auf, greift die Rollback-Semantik ([SWS_CRYPT_50019]), wodurch der Kontext in einem konsistenten Zustand verbleibt. Mögliche Fehlerursachen sind:

• UninitializedContext: Dem Kontext wurde vorab kein kryptografischer Schlüssel zugewiesen.
• ara::crypto::CryptoErrc::kUsageViolation: Der zugewiesene Schlüssel ist nicht für die Signaturprüfung (kAllowSig Verification) freigegeben.
• ara::crypto::CryptoErrc::kEmptyKeySlot: Ein für die Verifikation konfigurierter KeySlot ist gegenwärtig leer.
• ara::crypto::CryptoErrc::kUnsupported: Der Kontext unterstützt kein Streaming oder das Verfahren setzt zwingend einen Kontextwert voraus.
• ara::crypto::CryptoErrc::kBusyResource: Eine für die Operation benötigte Ressource ist derzeit belegt.

Nebenläufigkeit und Zusammenspiel

Obwohl die Spezifikation die Methode als threadsicher ausweist ([SWS_CRYPT_50019]), dürfte ein paralleler Aufruf auf derselben Kontextinstanz während einer laufenden Verifikation die bestehende Operation zurücksetzen oder an belegten Ressourcen scheitern. Frage Q-af5e08ff9d905a29 (offen)

Nach erfolgreicher Initialisierung werden die Nachrichtenteile sequenziell über Update() ([SWS_CRYPT_50021]) übergeben. Eine laufende Streaming-Operation kann bei Bedarf vorzeitig mit Cancel() ([SWS_CRYPT_50023]) abgebrochen werden. Falls der Algorithmus zwingend einen Kontextwert verlangt, muss stattdessen die überladene Funktion Start(ReadOnlyMemRegion context) ([SWS_CRYPT_50020]) aufgerufen werden.

Verwendung

Die Funktion Start initialisiert gemäß [SWS_CRYPT_50020] einen Verifikationskontext der Klasse ara::crypto::cryp::VerifierPublicCtx für eine neue Signaturprüfung. Als Eingabeparameter nimmt sie context vom Typ ReadOnlyMemRegion entgegen, der einen anwendungsspezifischen Kontextwert bereitstellt. Als Alternative ohne Kontextdaten existiert die Überladung [SWS_CRYPT_50019]. Der Rückgabewert ist ara::core::Result<void>; Interpretation: Da weder Callbacks noch Zukunfts-Objekte definiert sind, dürfte der Aufruf rein synchron abgewickelt werden. Frage Q-4e10cdb1a4343a3a (offen)

Fehlerbehandlung

Im Fehlerfall liefert die Funktion ein ara::core::Result mit einem passenden Fehlercode aus ara::crypto::CryptoErrc, wobei eine Rollback-Semantik spezifiziert ist [SWS_CRYPT_50020]:

• kUninitializedContext: Der Kontext wurde noch nicht durch Zuweisen eines Schlüssels initialisiert.
• kEmptyKeySlot: Ein konfigurierter KeySlot ist gegenwärtig leer.
• kUsageViolation: Die erlaubte Verwendung des zugewiesenen Schlüssels umfasst nicht kAllowSigVerification.
• kInvalidInputSize: Die Puffergröße des übergebenen Kontextwerts ist für den Algorithmus ungültig.
• kUnsupported: Der Kontext unterstützt kein Streaming oder der Algorithmus unterstützt das Setzen eines Kontextwerts nicht.
• kBusyResource: Eine erforderliche Ressource ist belegt.

Nebenläufigkeit und Einschränkungen

Gemäß [SWS_CRYPT_50020] ist die Methode als thread-safe sowie exception-safe eingestuft. Sie wirft keine Ausnahmen (noexcept).

Zusammenspiel

Nach erfolgreicher Ausführung von Start kann die Eingabenachricht über wiederholte Aufrufe von Update schrittweise übermittelt werden [SWS_CRYPT_50021]. Ein laufender Streaming-Vorgang, der durch Start eingeleitet wurde, kann bei Bedarf über Cancel vorzeitig abgebrochen werden [SWS_CRYPT_50023].

Verwendung

Die Methode Update() dient dazu, den Kontext zur Signaturprüfung schrittweise mit einem weiteren Teil der Eingabenachricht zu aktualisieren [SWS_CRYPT_50021]. Als Parameter wird ein Speicherbereich data vom Typ ReadOnlyMemRegion übergeben. Die Funktion liefert ein ara::core::Result<void> zurück; Interpretation: Aufgrund dieses Rückgabetyps dürfte die Verarbeitung synchron erfolgen. Frage Q-f98391030b3b4684 (offen)

Fehlerbehandlung

Im Fehlerfall wird ein entsprechender Fehlercode mit Rollback-Semantik zurückgegeben [SWS_CRYPT_50021]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: Die Signaturprüfung wurde nicht zuvor durch Aufruf der Methode Start() initiiert [SWS_CRYPT_50021].
• ara::crypto::CryptoErrc::kInvalidInputSize: Die Größe der bereitgestellten Daten in data wird nicht unterstützt [SWS_CRYPT_50021].

Nebenläufigkeit und Zusammenspiel

Die Operation ist in der Spezifikation als thread-safe und exception safe eingestuft [SWS_CRYPT_50021]. Vor dem Aufruf muss zwingend die Initialisierung via Start() erfolgt sein [SWS_CRYPT_50021]. Um zu verhindern, dass kInvalidInputSize auftritt, kann die maximal zulässige Puffergröße für einzelne Aufrufe über die Methode GetMaximumChunkSize() desselben Kontexts abgefragt werden [SWS_CRYPT_50025]. Das komplementäre Gegenstück zur nachrichtenweisen Signaturerzeugung stellt Update() in SignerPrivateCtx dar [SWS_CRYPT_50039].

Verwendung

Die Methode Verify des Kontexts ara::crypto::cryp::VerifierPublicCtx dient dazu, die Signatur einer bereitgestellten Nachricht in einem einzigen Aufruf zu verifizieren [SWS_CRYPT_24112]. Als Parameter werden der Nachrichtenpuffer message, die Signatur signature sowie das Format signatureFormat übergeben [SWS_CRYPT_24112]. Der Rückgabewert ara::core::Result<bool> enthält bei erfolgreicher Prüfung true, bei Nichtübereinstimmung false oder einen Fehlercode [SWS_CRYPT_24112]. Interpretation: Aufgrund des synchronen Ergebnistyps dürfte der Prüfvorgang blockierend im aufrufenden Thread ablaufen. Frage Q-671054c6e2b581c6 (offen)

Fehlerbehandlung und Nebenläufigkeit

Die Funktion ist als exception safe und thread-safe spezifiziert [SWS_CRYPT_24112]. Im Fehlerfall greift für die Fehlercodes eine Rollback-Semantik [SWS_CRYPT_24112]. Mögliche Fehlerursachen umfassen:

• UninitializedContext, wenn der Kontext nicht mit einem Schlüssel initialisiert wurde [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kEmptyKeySlot bei leerem Schlüssel-Slot oder kUsageViolation, wenn dem Schlüssel das Recht kAllowSig Verification fehlt [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kInvalidInputSize bei unzulässiger Puffergröße [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kUnsupportedFormat oder kInvalidArgument bei fehlerhaftem oder inkompatiblem Signaturformat [SWS_CRYPT_24112],
• ara::crypto::CryptoErrc::kBusyResource, falls benötigte Ressourcen belegt sind [SWS_CRYPT_24112].

Zusammenspiel

Die maximale Puffergröße für Einzelaufrufe kann über GetMaximumChunkSize() abgefragt werden [SWS_CRYPT_50025]. Verlangt der Algorithmus zwingend einen Kontextwert, wird ara::crypto::CryptoErrc::kUnsupported zurückgegeben [SWS_CRYPT_24112]; in diesem Fall ist die Überladung mit zusätzlichem context-Parameter zu wählen [SWS_CRYPT_50024]. Für Prüfungen von Message Authentication Codes existiert abgrenzend ara::crypto::cryp::MessageAuthnCodeCtx::Verify [SWS_CRYPT_50031].

Die synchrone Methode Verify prüft die digitale Signatur einer übergebenen Nachricht unter Berücksichtigung eines benutzerdefinierten Kontextwerts in einem einzigen Aufruf ([SWS_CRYPT_50024]). Als Eingabeparameter erwartet die Methode die Puffer message, context und signature jeweils als ReadOnlyMemRegion sowie das Format der Signatur über signatureFormat ([SWS_CRYPT_50024]). Der Rückgabewert ist ein ara::core::Result<bool>: Er enthält true bei erfolgreicher Verifikation, false bei fehlerhafter Signatur oder einen entsprechenden Fehlercode ([SWS_CRYPT_50024]).

Im Fehlerfall greift eine Rollback-Semantik ([SWS_CRYPT_50024]). Spezifische Fehlercodes umfassen unter anderem:

• UninitializedContext, wenn der Verifikationskontext noch nicht mit einem Schlüsselwert initialisiert wurde ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kInvalidInputSize bei unzulässiger Puffergröße ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupported, falls der gewählte Signaturalgorithmus die Angabe eines Kontextwerts nicht unterstützt ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUnsupportedFormat bzw. ara::crypto::CryptoErrc::kInvalidArgument, wenn das angegebene Signaturformat nicht unterstützt wird oder die Signatur nicht dem Format entspricht ([SWS_CRYPT_50024]),
• ara::crypto::CryptoErrc::kUsageViolation, wenn die erlaubte Schlüsselverwendung nicht kAllowSigVerification einschließt, sowie ara::crypto::CryptoErrc::kEmptyKeySlot und ara::crypto::CryptoErrc::kBusyResource ([SWS_CRYPT_50024]).

Die Methode ist als const noexcept deklariert, gilt als ausnahmesicher und ist als thread-safe spezifiziert ([SWS_CRYPT_50024]). Im Zusammenspiel mit dem Kontext kann die maximale Puffergröße für Einzelaufrufe über GetMaximumChunkSize ermittelt werden ([SWS_CRYPT_50025]). Für Verifikationen ohne Kontext steht die alternative Überladung von Verify zur Verfügung ([SWS_CRYPT_24112]).