class ara::crypto::Serializable

Die Schnittstelle ara::crypto::Serializable definiert den einheitlichen Standard zum öffentlichen Exportieren kryptografischer Objekte in formatspezifische Byte-Sequenzen. Anwendungen ermitteln vorab über GetExportSize() die benötigte Puffergröße und führen die eigentliche Serialisierung anschließend über ExportPublicly() in einen bereitgestellten Puffer aus [SWS_CRYPT_10711]. Alle Operationen sind ausnahmesicher sowie thread-safe, wobei der Export von Schlüsseln zwingend die Berechtigung kAllowPlaintextExport voraussetzt und Fehler stets einer Rollback-Semantik unterliegen [SWS_CRYPT_50006].

mehr ›

Kontext

Die Schnittstelle ara::crypto::Serializable definiert den abstrakten Vertrag für kryptografische Objekte im Modul crypto, die in eine standardisierte Byte-Repräsentation überführt werden können. Als reine Schnittstelle kapselt sie die Fähigkeit, ein Objekt in ein durch einen Formatbezeichner (FormatId) spezifiziertes Ausgabeformat zu serialisieren [SWS_CRYPT_10711]. Zu den typischen Interaktionspartnern gehören Anwendungs- oder Plattformkomponenten, die kryptografische Artefakte wie Schlüssel oder Zertifikate persistent speichern, über Kommunikationskanäle übertragen oder im Klartext austauschen müssen. Die Schnittstelle stellt sicher, dass der Export kontrolliert und unter Berücksichtigung von Formaten sowie Sicherheitsbeschränkungen erfolgt.

Lebenszyklus

Da ara::crypto::Serializable ein rein virtuelles Interface mit rein virtuellen Methoden darstellt, verfügt die Klasse über keine eigene Instanziierungslogik. Die Lebensdauer und die Erzeugung hängen vollständig von den ableitenden konkreten Krypto-Klassen ab, welche die Schnittstelle implementieren. Beide spezifizierten Methoden der Schnittstelle, GetExportSize() [SWS_CRYPT_50006] sowie ExportPublicly() [SWS_CRYPT_10711], sind als const deklariert und verändern den internen Zustand des Objekts bei der Serialisierung nicht. Gemäß Spezifikation sind die Operationen ausnahmesicher (exception safe) und nebenläufigkeitssicher (thread-safe) ausgelegt [SWS_CRYPT_10711], [SWS_CRYPT_50006], sodass parallele Lesezugriffe auf dieselbe Objektinstanz zulässig sind.

Nutzungspfad

Der reguläre Ablauf eines Exports gliedert sich in eine zweistufige Sequenz aus Größenermittlung und eigentlicher Serialisierung. Um Pufferüberläufe oder fehlschlagende Allokationen zu vermeiden, fragt der Aufrufer vorab über die Methode GetExportSize() die exakt benötigte Puffergröße in Bytes für das gewünschte Zielformat ab [SWS_CRYPT_50006]. Nach erfolgreicher Rückmeldung stellt der Aufrufer einen beschreibbaren Speicherbereich vom Typ ReadWriteMemRegion bereit. Vermutlich wird dieser Speicherbereich in den meisten Implementierungen dynamisch anhand der ermittelten Bytezahl alloziert oder aus einem vorab reservierten Speicherpool bereitgestellt. Frage Q-0c04ba0a352f0a37 (offen)

Im anschließenden Schritt ruft die Anwendung ExportPublicly() auf und übergibt sowohl den bereitgestellten Puffer als auch die zuvor gewählte FormatId [SWS_CRYPT_10711]. Das Objekt serialisiert seine Nutzdaten in den übergebenen Speicherbereich und liefert im Erfolgsfall innerhalb des Rückgabetyps ara::core::Result<std::size_t> die tatsächlich geschriebene Anzahl an Bytes zurück [SWS_CRYPT_10711].

Sequenzdiagramm: Typische Aufrufreihenfolge zur Serialisierung eines Objekts über Größenabfrage und anschließenden Export. Quellen: [SWS_CRYPT_50006], [SWS_CRYPT_10711]

Fehlerszenarien

Die Operationen der Schnittstelle signalisieren Fehlerzustände über den Rückgabetyp ara::core::Result, wobei alle spezifizierten Fehler eine strikte Rollback-Semantik (rollback_semantics) garantieren [SWS_CRYPT_10711], [SWS_CRYPT_50006]. Scheitert ein Aufruf, verbleibt das Gesamtsystem in einem konsistenten Zustand. Folgende Fehlerfälle sind definiert:

• ara::crypto::CryptoErrc::kUnsupportedFormat: Wird sowohl von GetExportSize() [SWS_CRYPT_50006] als auch von ExportPublicly() [SWS_CRYPT_10711] zurückgegeben, wenn die angegebene FormatId für den konkreten Objekttyp nicht unterstützt wird.
• ara::crypto::CryptoErrc::kInsufficientCapacity: Tritt in ExportPublicly() auf, wenn die Kapazität des übergebenen ReadWriteMemRegion-Puffers für die serialisierten Daten nicht ausreicht [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUnsupported: Wird von ExportPublicly() gemeldet, falls der Export für das spezifische Objekt prinzipiell nicht unterstützt wird [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUsageViolation: Tritt bei ExportPublicly() auf, wenn es sich bei dem Objekt um einen Schlüssel handelt, dessen Verwendungsregeln einen Klartextexport nicht gestatten (die erlaubte Verwendung beinhaltet nicht kAllowPlaintextExport) [SWS_CRYPT_10711].