klasse ara::crypto::Formatter

De interface ara::crypto::Formatter maakt de thread-veilige conversie en serialisatie van cryptografische gegevens tussen ruwe, DER- en PEM-formaten mogelijk [SWS_CRYPT_50197]. Na vastlegging van het doelformaat en bepaling van de benodigde buffergrootte zet de methode Convert de brongegevens over naar de voorbereide uitvoerbuffer [SWS_CRYPT_50198]. Een essentiële voorwaarde voor een succesvolle uitvoering is een toereikend gedimensioneerd doelgeheugen evenals de formele overeenstemming van de invoergegevens met het geconfigureerde bronformaat.

meer ›

Context

De interface ara::crypto::Formatter definieert in module crypto de uniforme interface voor het formatteren, transformeren en serialiseren van cryptografische datastructuren. Haar hoofdtaak bestaat erin nuttige gegevens en cryptografische objecten te converteren tussen representaties zoals zuivere ruwe data (kFormatRawValueOnly), ASN.1-DER-coderingen (kFormatDerEncoded) evenals tekstuele PEM-formaten (kFormatPemEncoded) met inachtneming van een algoritme-identificatie (AlgId) [SWS_CRYPT_50197]. Hierbij fungeert de Formatter als schakel tussen cryptografische objecten en geheugenbuffers, door gegevens via ReadOnlyMemRegion in te lezen en in ReadWriteMemRegion uit te voeren [SWS_CRYPT_50198].

Levenscyclus

Aangezien ara::crypto::Formatter als puur virtuele interface is gedeclareerd, stelt zij voor referentiëring en levenscyclusbeheer de canonieke smart-pointer-typealias Sptr beschikbaar, die gedefinieerd is als std::shared_ptr<Formatter> [SWS_CRYPT_50191]. Concrete instanties van de interface worden in de praktijk vermoedelijk via fabrieksmethoden van bovenliggende cryptocomponenten beschikbaar gesteld. Vraag Q-99e96992d02b9c13 (open) Na aanmaak bevindt een Formatter zich eerst in een ongeconfigureerde begintoestand, voordat deze door configuratie-aanroepen wordt voorbereid op transformaties.

Met betrekking tot de uitvoeringsomgeving garandeert de interface volledige uitzonderingsveiligheid (exception safe) door het consequente gebruik van noexcept en de foutafhandeling via Result-typen [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Alle memberfuncties zijn bovendien gespecificeerd als thread-veilig (thread-safe) [SWS_CRYPT_50197], [SWS_CRYPT_50198], [SWS_CRYPT_50199]. Dit staat parallelle lezende en transformerende toegang van meerdere threads tot een gedeelde Formatter-instantie toe, zolang er geen concurrerende herconfiguraties plaatsvinden.

Gebruikspad

Het reguliere gebruik van ara::crypto::Formatter volgt een vaste volgorde van parametrering, capaciteitscontrole en transformatie:

1. Formaatconfiguratie: Via SetFormatConfiguration worden het verwachte invoerformaat (inputFormat), het gewenste uitvoerformaat (outputFormat) en de algoritme-identificatie (algId) van de te verwerken gegevens bindend vastgelegd [SWS_CRYPT_50197].
2. Groottebepaling: Voorafgaand aan de feitelijke conversie roept de applicatie GetExportSize aan om de exacte geheugengrootte in bytes te bepalen die het geserialiseerde object onder de huidige configuratie vereist [SWS_CRYPT_50199]. Dit maakt een nauwkeurig passende allocatie van het doelgeheugen mogelijk.
3. Gegevensconversie: Tot slot transformeert Convert de brongegevens uit een ReadOnlyMemRegion naar de doelbuffer ReadWriteMemRegion overeenkomstig de gemaakte configuratie [SWS_CRYPT_50198].

Sequentiediagram: Typische conversievolgorde vanaf de formaatselectie via de buffergroottebepaling tot aan de feitelijke transformatie. Bronnen: [SWS_CRYPT_50197], [SWS_CRYPT_50199], [SWS_CRYPT_50198]

Foutscenario's

Methoden van ara::crypto::Formatter signaleren fouttoestanden deterministisch via retourwaarden van het type ara::core::Result. Daarbij zijn voor mislukkende operaties duidelijke rollback-semantieken vastgelegd:

• Niet-ondersteunde formaten: Als de onderliggende implementatie het gespecificeerde transformatiepaar of de algoritme-identificatie niet ondersteunt, levert SetFormatConfiguration de foutcode ara::crypto::CryptoErrc::kUnsupportedFormat op [SWS_CRYPT_50197].
• Ongeldige invoergegevens: Wanneer de in de buffer overgedragen ruwe gegevens niet overeenkomen met het geconfigureerde formaat of syntactisch ongeldig zijn, mislukt Convert met ara::crypto::CryptoErrc::kInvalidArgument [SWS_CRYPT_50198].
• Ontoereikende doelbuffer: Als de gereedgestelde ReadWriteMemRegion te klein is voor het geserialiseerde resultaat, breekt Convert af met ara::crypto::CryptoErrc::kInsufficientCapacity [SWS_CRYPT_50198]. Dit probleem kan gericht worden voorkomen door voorafgaande bevraging via GetExportSize [SWS_CRYPT_50199].
• Ontbrekende voorafgaande configuratie: Voor GetExportSize zijn weliswaar geen gestandaardiseerde foutcodes vermeld [SWS_CRYPT_50199], maar er moet vermoedelijk verplicht vooraf een geldige configuratie via SetFormatConfiguration zijn ingesteld om een consistente groottebepaling of conversie te kunnen laten plaatsvinden. Vraag Q-e7cf4306bc7cfb49 (open)