klasse ara::crypto::Serializable

De interface ara::crypto::Serializable definieert de uniforme standaard voor het publiek exporteren van cryptografische objecten naar formatspecifieke bytesequenties. Applicaties bepalen vooraf via GetExportSize() de benodigde buffergrootte en voeren de feitelijke serialisatie vervolgens via ExportPublicly() uit naar een beschikbaar gestelde buffer [SWS_CRYPT_10711]. Alle operaties zijn exception-safe en thread-safe, waarbij de export van sleutels dwingend de bevoegdheid kAllowPlaintextExport vereist en fouten altijd onderworpen zijn aan een rollback-semantiek [SWS_CRYPT_50006].

meer ›

Context

De interface ara::crypto::Serializable definieert het abstracte contract voor cryptografische objecten in de module crypto die kunnen worden omgezet naar een gestandaardiseerde byterepresentatie. Als zuivere interface kapselt zij het vermogen in om een object te serialiseren naar een uitvoerformaat dat door een formaat-identifier (FormatId) wordt gespecificeerd [SWS_CRYPT_10711]. Tot de typische interactiepartners behoren applicatie- of platformcomponenten die cryptografische artefacten zoals sleutels of certificaten persistent moeten opslaan, over communicatiekanalen moeten verzenden of in platte tekst moeten uitwisselen. De interface waarborgt dat de export gecontroleerd en met inachtneming van formaten en beveiligingsbeperkingen plaatsvindt.

Levenscyclus

Omdat ara::crypto::Serializable een puur virtuele interface met puur virtuele methoden is, beschikt de klasse niet over een eigen instantiëringslogica. De levensduur en het aanmaken hangen volledig af van de afgeleide concrete crypto-klassen die de interface implementeren. Beide gespecificeerde methoden van de interface, GetExportSize() [SWS_CRYPT_50006] en ExportPublicly() [SWS_CRYPT_10711], zijn gedeclareerd als const en veranderen de interne toestand van het object tijdens de serialisatie niet. Volgens de specificatie zijn de operaties uitzonderingsveilig (exception safe) en concurrency-veilig (thread-safe) ontworpen [SWS_CRYPT_10711], [SWS_CRYPT_50006], zodat parallelle leestoegangen tot dezelfde objectinstantie zijn toegestaan.

Gebruikspad

Het reguliere verloop van een export is opgedeeld in een tweestapssequentie van groottebepaling en feitelijke serialisatie. Om bufferoverstromingen of mislukkende allocaties te voorkomen, vraagt de aanroeper vooraf via de methode GetExportSize() de exact benodigde buffergrootte in bytes voor het gewenste doelformaat op [SWS_CRYPT_50006]. Na een succesvolle terugmelding stelt de aanroeper een beschrijfbaar geheugengebied van het type ReadWriteMemRegion beschikbaar. Vermoedelijk wordt dit geheugengebied in de meeste implementaties dynamisch gealloceerd op basis van het vastgestelde aantal bytes of beschikbaar gesteld vanuit een vooraf gereserveerde geheugenpool. Vraag Q-0c04ba0a352f0a37 (open)

In de daaropvolgende stap roept de applicatie ExportPublicly() aan en geeft daarbij zowel de beschikbaar gestelde buffer als de eerder gekozen FormatId [SWS_CRYPT_10711] door. Het object serialiseert zijn nuttige data naar het overgedragen geheugengebied en retourneert bij succes binnen het retourtype ara::core::Result<std::size_t> het daadwerkelijk geschreven aantal bytes [SWS_CRYPT_10711].

Sequentiediagram: Typische aanroepvolgorde voor het serialiseren van een object via een groottevraag en aansluitende export. Bronnen: [SWS_CRYPT_50006], [SWS_CRYPT_10711]

Foutscenario's

De operaties van de interface signaleren fouttoestanden via het retourtype ara::core::Result, waarbij alle gespecificeerde fouten een strikte rollback-semantiek (rollback_semantics) garanderen [SWS_CRYPT_10711], [SWS_CRYPT_50006]. Mislukt een aanroep, dan blijft het totale systeem in een consistente toestand. De volgende foutgevallen zijn gedefinieerd:

• ara::crypto::CryptoErrc::kUnsupportedFormat: Wordt zowel door GetExportSize() [SWS_CRYPT_50006] als door ExportPublicly() [SWS_CRYPT_10711] geretourneerd wanneer de opgegeven FormatId niet wordt ondersteund voor het concrete objecttype.
• ara::crypto::CryptoErrc::kInsufficientCapacity: Treedt op in ExportPublicly() wanneer de capaciteit van de overgedragen ReadWriteMemRegion-buffer niet toereikend is voor de geserialiseerde data [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUnsupported: Wordt door ExportPublicly() gemeld indien de export voor het specifieke object principieel niet wordt ondersteund [SWS_CRYPT_10711].
• ara::crypto::CryptoErrc::kUsageViolation: Treedt op bij ExportPublicly() wanneer het bij het object om een sleutel gaat waarvan de gebruiksregels een export in platte tekst niet toestaan (het toegestane gebruik bevat niet kAllowPlaintextExport) [SWS_CRYPT_10711].