class ara::crypto::Formatter

Die Schnittstelle ara::crypto::Formatter ermöglicht die threadsichere Konvertierung und Serialisierung kryptografischer Daten zwischen Roh-, DER- und PEM-Formaten [SWS_CRYPT_50197]. Nach Festlegung des Zielformats und Ermittlung der benötigten Puffergröße überführt die Methode Convert die Quelldaten in den vorbereiteten Ausgabepuffer [SWS_CRYPT_50198]. Wesentliche Voraussetzung für eine erfolgreiche Ausführung ist ein ausreichend dimensionierter Zielspeicher sowie die formale Übereinstimmung der Eingabedaten mit dem konfigurierten Quellformat.

mehr ›

Kontext

Die Schnittstelle ara::crypto::Formatter definiert im Modul crypto das einheitliche Interface für die Formatierung, Transformation und Serialisierung kryptografischer Datenstrukturen. Ihre Hauptaufgabe besteht darin, Nutzdaten und kryptografische Objekte zwischen Repräsentationen wie reinen Rohdaten (kFormatRawValueOnly), ASN.1-DER-Codierungen (kFormatDerEncoded) sowie textuellen PEM-Formaten (kFormatPemEncoded) unter Berücksichtigung einer Algorithmenkennung (AlgId) zu konvertieren [SWS_CRYPT_50197]. Hierbei agiert der Formatter als Bindeglied zwischen kryptografischen Objekten und Speicherpuffern, indem er Daten über ReadOnlyMemRegion einliest und in ReadWriteMemRegion ausgibt [SWS_CRYPT_50198].

Lebenszyklus

Da ara::crypto::Formatter als rein virtuelle Schnittstelle deklariert ist, stellt sie zur Referenzierung und Lebenszyklusverwaltung den kanonischen Smart-Pointer-Typalias Sptr bereit, der als std::shared_ptr<Formatter> definiert ist [SWS_CRYPT_50191]. Konkrete Instanzen des Interfaces dürften in der Praxis über Fabrikmethoden übergeordneter Krypto-Komponenten bereitgestellt werden. Frage Q-99e96992d02b9c13 (offen) Nach der Erzeugung befindet sich ein Formatter zunächst in einem unkonfigurierten Ausgangszustand, bevor er durch Konfigurationsaufrufe für Wandlungen vorbereitet wird.

Hinsichtlich der Ausführungsumgebung garantiert die Schnittstelle vollständige Ausnahme-Sicherheit (exception safe) durch den konsequenten Einsatz von noexcept und die Fehlerbehandlung über Result-Typen [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Sämtliche Mitgliedsfunktionen sind zudem als threadsicher (thread-safe) spezifiziert [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Dies erlaubt den parallelen lesenden und transformierenden Zugriff mehrerer Threads auf eine geteilte Formatter-Instanz, solange keine konkurrierenden Rekonfigurationen stattfinden.

Nutzungspfad

Die reguläre Verwendung von ara::crypto::Formatter folgt einer festen Abfolge aus Parametrierung, Kapazitätsprüfung und Transformation:

1. Formatkonfiguration: Über SetFormatConfiguration werden das erwartete Eingabeformat (inputFormat), das gewünschte Ausgabeformat (outputFormat) sowie die Algorithmenkennung (algId) der zu verarbeitenden Daten verbindlich festgelegt [SWS_CRYPT_50197].
2. Größenermittlung: Vor der eigentlichen Konvertierung ruft die Anwendung GetExportSize auf, um die exakte Speichergröße in Bytes zu ermitteln, die das serialisierte Objekt unter der aktuellen Konfiguration benötigt [SWS_CRYPT_50199]. Dies ermöglicht die passgenaue Allokation des Zielspeichers.
3. Datenkonvertierung: Abschließend transformiert Convert die Quelldaten aus einer ReadOnlyMemRegion in den Zielpuffer ReadWriteMemRegion entsprechend der getroffenen Konfiguration [SWS_CRYPT_50198].

Sequenzdiagramm: Typische Konvertierungsabfolge von der Formatauswahl über die Puffergrößenermittlung bis zur eigentlichen Transformation. Quellen: [SWS_CRYPT_50197], [SWS_CRYPT_50199], [SWS_CRYPT_50198]

Fehlerszenarien

Methoden von ara::crypto::Formatter signalisieren Fehlerzustände deterministisch über Rückgabewerte vom Typ ara::core::Result. Dabei sind für fehlschlagende Operationen klare Rollback-Semantiken hinterlegt:

• Nicht unterstützte Formate: Unterstützt die zugrundeliegende Implementierung das spezifizierte Wandlungspaar oder die Algorithmenkennung nicht, liefert SetFormatConfiguration den Fehlercode ara::crypto::CryptoErrc::kUnsupportedFormat [SWS_CRYPT_50197].
• Ungültige Eingabedaten: Wenn die im Puffer übergebenen Rohdaten nicht dem konfigurierten Format entsprechen oder syntaktisch ungültig sind, schlägt Convert mit ara::crypto::CryptoErrc::kInvalidArgument fehl [SWS_CRYPT_50198].
• Unzureichender Zielpuffer: Ist die bereitgestellte ReadWriteMemRegion zu klein für das serialisierte Ergebnis, bricht Convert mit ara::crypto::CryptoErrc::kInsufficientCapacity ab [SWS_CRYPT_50198]. Dieses Problem lässt sich durch vorherige Abfrage über GetExportSize [SWS_CRYPT_50199] gezielt verhindern.
• Fehlende Vorkonfiguration: Für GetExportSize sind zwar keine standardisierten Fehlercodes aufgeführt [SWS_CRYPT_50199], jedoch muss vermutlich zwingend vorab eine gültige Konfiguration über SetFormatConfiguration etabliert worden sein, damit eine konsistente Größenbestimmung oder Konvertierung erfolgen kann. Frage Q-e7cf4306bc7cfb49 (offen)