klasse ara::crypto::cryp::DecryptorPrivateCtx

De in ara/crypto/cryp/decryptor_private_ctx.h gedefinieerde methode Cancel van klasse ara::crypto::cryp::DecryptorPrivateCtx breekt een lopende streamingoperatie af die eerder via Start() is geïnitieerd en nog niet is voltooid [SWS_CRYPT_50069]. De aanroep accepteert geen overdrachtsparameters en levert als retourwaarde een ara::core::Result<void> [SWS_CRYPT_50069] op. Was het afbreken van de streamingverwerking succesvol, dan bevat het object een leeg resultaat; anders transporteert het een opgetreden fout [SWS_CRYPT_50069]. De zuiver virtuele interface is gedeclareerd als noexcept, kent volledige exception safety en is aangemerkt als thread-safe voor gelijktijdige toegang [SWS_CRYPT_50069].

Bij de foutafhandeling en de voorwaarden voor het verloop moet de exacte volgorde in acht worden genomen: als de gegevensverwerking niet vooraf is ingeleid door aanroep van de methode Start(), mislukt de operatie en retourneert deze de specifieke foutcode ara::crypto::CryptoErrc::kProcessingNotStarted met rollback-semantiek [SWS_CRYPT_50069]. De aanroeper moet er daarom voor zorgen dat er vóór het afbreken al een actieve operatie bestaat om deze fouttoestand te voorkomen [SWS_CRYPT_50069].

In samenspel met de gehele module-architectuur van crypt volgt Cancel een gestandaardiseerd ontwerppatroon voor toestandshoudende streamingprocessen. Dezelfde signatuur, retoursemantiek en foutafhandeling worden gedeeld door de verwante cryptografische contexten ara::crypto::cryp::VerifierPublicCtx [SWS_CRYPT_50023], ara::crypto::cryp::MessageAuthnCodeCtx [SWS_CRYPT_50027], ara::crypto::cryp::SignerPrivateCtx [SWS_CRYPT_50041], ara::crypto::cryp::SymmetricCipherCtx [SWS_CRYPT_50046], ara::crypto::cryp::HashFunctionCtx [SWS_CRYPT_50058], ara::crypto::cryp::AuthCipherCtx [SWS_CRYPT_50077] en ara::crypto::cryp::EncryptorPublicCtx [SWS_CRYPT_50089].

De synchrone methode Decrypt ontsleutelt cijfertekstdata in één enkele stap ([SWS_CRYPT_50070]). De invoerbuffer in geeft de cijfertekst door als ReadOnlyMemRegion, terwijl de uitvoerbuffer out van het type ReadWriteMemRegion de platte tekst opneemt ([SWS_CRYPT_50070]). Bij een succesvolle decryptie retourneert de functie via ara::core::Result<std::size_t> het daadwerkelijke aantal geschreven bytes, dat kleiner kan zijn dan de totale capaciteit van out ([SWS_CRYPT_50070]).

De interface is gespecificeerd als thread-safe en exception safe ([SWS_CRYPT_50070]). Vóór de aanroep moet de context zijn geïnitialiseerd door het toewijzen van een sleutel; anders mislukt de functie met UninitializedContext of bij een leeg KeySlot met ara::crypto::CryptoErrc::kEmptyKeySlot ([SWS_CRYPT_50070]). De sleutel moet compatibel zijn met het transformatie-algoritme (anders kIncompatibleObject) en de machtiging kAllowDataDecryption omvatten (anders kUsageViolation) ([SWS_CRYPT_50070]).

Om bufferoverschrijdingen te voorkomen, kan de maximaal benodigde capaciteit van de uitvoerbuffer vooraf worden opgevraagd met GetRequiredOutputBufferSize onder opgave van isFinal = true ([SWS_CRYPT_50159]). Als de capaciteit van out niet toereikend is, breekt de methode af met ara::crypto::CryptoErrc::kInsufficientCapacity ([SWS_CRYPT_50070]). De grootte van de invoerbuffer in moet bovendien in het bereik tussen GetMinimumChunkSize ([SWS_CRYPT_50160]) en GetMaximumChunkSize ([SWS_CRYPT_50071]) liggen, anders wordt ara::crypto::CryptoErrc::kInvalidInputSize geretourneerd ([SWS_CRYPT_50070]). Andere gespecificeerde fouten met rollback-semantiek zijn kUnsupported, kInvalidArgument en kBusyResource ([SWS_CRYPT_50070]).

De methode Finish sluit een ontsleutelingsproces in de context van ara::crypto::cryp::DecryptorPrivateCtx synchroon af [SWS_CRYPT_50068]. Deze verwerkt via de invoerbuffer in (ReadOnlyMemRegion) het laatste cijfertekstsegment en schrijft de resulterende platte-tekstgegevens in de uitvoerbuffer out (ReadWriteMemRegion) [SWS_CRYPT_50068]. Het werkelijk geschreven aantal bytes wordt als ara::core::Result<std::size_t> geretourneerd en mag kleiner uitvallen dan de totale capaciteit van de doelbuffer out [SWS_CRYPT_50068].

Voorafgaand aan de aanroep moet de gegevensverwerking dwingend zijn ingeleid met Start(), anders wordt de fout CryptoErrc::kProcessingNotStarted gemeld [SWS_CRYPT_50068]. De maximaal toegestane blokgrootte voor in kan via GetMaximumChunkSize() worden bepaald [SWS_CRYPT_50071]; bij een niet-passende invoerlengte mislukt de aanroep met CryptoErrc::kInvalidInputSize [SWS_CRYPT_50068]. Is out te klein, dan resulteert dit in CryptoErrc::kInsufficientCapacity, waarbij de benodigde buffergrootte via GetRequiredOutputBufferSize() kan worden opgevraagd [SWS_CRYPT_50068]. Verdere mogelijke fouten zijn CryptoErrc::kInvalidArgument bij ongeldige cijfertekstgegevens en CryptoErrc::kUnsupported indien stream-verwerking in de context niet wordt ondersteund [SWS_CRYPT_50068].

De bewerking is gespecificeerd als thread-safe en exception safe [SWS_CRYPT_50068]. Dankzij de toegekende rollback-semantiek blijft de verwerkingstoestand bij bufferfouten vermoedelijk ongewijzigd, zodat na vergroting van de buffer een herhaling mogelijk zou moeten zijn. Vraag Q-e2562509449aa32c (open)

Gebruik

De methode SetKey configureert een instantie van ara::crypto::cryp::DecryptorPrivateCtx voor het gebruik van een sleutel die in een meegegeven KeySlot is opgeslagen [SWS_CRYPT_50066]. Als parameter wordt een KeySlot::Sptr meegegeven, die een PrivateKey moet bevatten [SWS_CRYPT_50066]. De eigenlijke sleutel wordt pas gebruikt op het moment dat de decryptieoperatie wordt gestart [SWS_CRYPT_50066]. De functie werkt synchroon en meldt het resultaat terug via ara::core::Result<void> [SWS_CRYPT_50066].

Foutafhandeling

In geval van een fout wordt een bijbehorende foutcode in het ara::core::Result geretourneerd, waarbij een rollback-semantiek van toepassing is [SWS_CRYPT_50066]:

• ara::crypto::CryptoErrc::kIncompatibleObject: De ter beschikking gestelde KeySlot is niet compatibel met de context [SWS_CRYPT_50066].
• ara::crypto::CryptoErrc::kUnsupported: De context ondersteunt alleen het direct instellen van een PrivateKey en geen KeySlots [SWS_CRYPT_50066].

Gelijktijdigheid en wisselwerking

De interface is gedeclareerd als thread-safe (thread-safe) en uitzonderingsveilig (exception safe) [SWS_CRYPT_50066]. Aangezien de evaluatie van de sleutel pas bij het begin van de decryptie plaatsvindt, treedt een actualisering van de slotinhoud vermoedelijk vóór dit starttijdstip in werking. Vraag Q-ec258ea8b5a1d1c2 (open) Terwijl andere cryptografische contexten sleutels deels direct als instantie aannemen (bijvoorbeeld SignerPrivateCtx [SWS_CRYPT_23515]), volgt deze methode het patroon van vertraagde binding via sleutelslots, zoals dit onder meer ook wordt toegepast bij VerifierPublicCtx [SWS_CRYPT_50018] en KeyDerivationFunctionCtx [SWS_CRYPT_50010].

Gebruik

De methode SetKey configureert een instantie van ara::crypto::cryp::DecryptorPrivateCtx voor het gebruik van een concrete privésleutel voor gegevensontsleuteling [SWS_CRYPT_50157]. Als parameter wordt een instantie via PrivateKey::Sptr key doorgegeven. De retourwaarde is ara::core::Result<void>, waarmee de succesvolle toewijzing wordt bevestigd of een fout wordt geretourneerd. De aanroep wordt vermoedelijk synchroon uitgevoerd (interpretatie: de interface blokkeert tot de overname van de sleutel en retourneert geen asynchroon Future-object). Vraag Q-b8e9b5cb4174e2b2 (open)

Foutafhandeling

In geval van een fout waarborgt de implementatie een rollback-semantiek, zodat de contextstatus bij een fout ongewijzigd blijft [SWS_CRYPT_50157]. De volgende foutcodes kunnen optreden:

• ara::crypto::CryptoErrc::kIncompatibleObject: Het doorgegeven sleutelobject is niet compatibel met deze context [SWS_CRYPT_50157].
• ara::crypto::CryptoErrc::kUsageViolation: Het toegestane gebruik van de sleutel omvat niet gegevensontsleuteling (kAllowData Decryption) [SWS_CRYPT_50157].
• ara::crypto::CryptoErrc::kUnsupported: De context ondersteunt het direct instellen van een sleutelobject niet wanneer deze uitsluitend is ontworpen voor toewijzing via een KeySlot [SWS_CRYPT_50157].

Gelijktijdigheid en beperkingen

De interface is expliciet gespecificeerd als thread-safe en exception safe [SWS_CRYPT_50157]. Deze garandeert veilige uitvoering in gelijktijdige omgevingen en genereert geen C++-excepties (noexcept=0).

Samenspel

De procedure voor sleuteltoewijzing via SetKey wordt in het Adaptive Platform uniform toegepast over verschillende cryptografische contexten heen: terwijl verwante asymmetrische contexten zoals KeyAgreementPrivateCtx [SWS_CRYPT_21313], KeyDecapsulatorPrivateCtx [SWS_CRYPT_21413] en SignerPrivateCtx [SWS_CRYPT_23515] eveneens PrivateKey::Sptr gebruiken, bestaan er in andere contexten zoals KeyDerivationFunctionCtx [SWS_CRYPT_50010] of VerifierPublicCtx [SWS_CRYPT_50018] alternatieve varianten met KeySlot::Sptr.

De memberfunctie Start van de klasse ara::crypto::cryp::DecryptorPrivateCtx ([SWS_CRYPT_50067]) initialiseert de context synchroon voor een nieuwe decryptie. De aanroep accepteert geen parameters, gooit geen excepties (noexcept) en retourneert een ara::core::Result<void>, die bij succes leeg is ([SWS_CRYPT_50067]). Voor gelijktijdige toegangen is de methode gespecificeerd als thread-safe ([SWS_CRYPT_50067]).

Vóór de uitvoering moet een compatibele sleutel zijn ingesteld, aangezien Start de toestand en machtigingen daarvan controleert ([SWS_CRYPT_50067]). Als de operatie mislukt, treedt een rollback-semantiek in werking ([SWS_CRYPT_50067]). Relevante foutcodes zijn:

• ara::crypto::CryptoErrc::kUninitializedContext: Aan de context is nog geen sleutel toegewezen ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kEmptyKeySlot: Een geconfigureerd KeySlot is momenteel leeg ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kUsageViolation: De machtigingen van de sleutel staan geen datadecryptie toe ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kIncompatibleObject: Het sleuteltype is incompatibel met de transformatie ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kBusyResource: Een benodigde resource is bezet ([SWS_CRYPT_50067]).
• ara::crypto::CryptoErrc::kUnsupported: Streamverwerking wordt niet ondersteund door de context ([SWS_CRYPT_50067]).

In het totale systeem komt de methode overeen met de gestandaardiseerde levenscyclus van adaptieve cryptocontexten, zoals die vergelijkbaar wordt gebruikt bij de handtekeningverificatie ([SWS_CRYPT_50019]), het genereren van handtekeningen ([SWS_CRYPT_50037]) of de MAC-berekening ([SWS_CRYPT_22111]). Interpretatie: Een aanroep van Start is vermoedelijk dwingend vereist voorafgaand aan verdere verwerkingsstappen om de decryptor in een gedefinieerde begintoestand te brengen. Vraag Q-7d5a95305eb4626a (open)

Gebruik

De methode Update dient voor het ontsleutelen van een gegevensbuffer in de context van ara::crypto::cryp::DecryptorPrivateCtx [SWS_CRYPT_50158]. De synchrone aanroep neemt een cijfertekstsegment in de parameter in (ReadOnlyMemRegion) aan en schrijft de ontsleutelde gegevens in de buffer out (ReadWriteMemRegion) [SWS_CRYPT_50158]. Als resultaat wordt een ara::core::Result<std::size_t> geretourneerd die het daadwerkelijke aantal geschreven bytes bevat; deze waarde kan kleiner zijn dan de totale capaciteit van out [SWS_CRYPT_50158].

Interactie en bufferdimensionering

Vóór de uitvoering van Update moet de gegevensverwerking verplicht zijn geïnitieerd door de aanroep van Start() [SWS_CRYPT_50158]. De voor out benodigde minimumgrootte kan via GetRequiredOutputBufferSize() worden opgevraagd [SWS_CRYPT_50158]. Daarnaast kan de voor afzonderlijke Update-aanroepen maximaal verwerkbare invoergrootte via GetMaximumChunkSize() worden bepaald [SWS_CRYPT_50071].

Foutafhandeling en gelijktijdigheid

De interface is gespecificeerd als thread-safe en exception-safe [SWS_CRYPT_50158]. Alle foutgevallen bezitten rollback-semantiek en leveren specifieke foutcodes in ara::core::Result op [SWS_CRYPT_50158]:

• ara::crypto::CryptoErrc::kProcessingNotStarted: De verwerking is niet vooraf gestart door middel van Start() [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kInsufficientCapacity: De uitvoerbuffer out is te klein gedimensioneerd [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kInvalidInputSize: De grootte van de doorgegeven invoerbuffer is ongeldig [SWS_CRYPT_50158].
• ara::crypto::CryptoErrc::kUnsupported: Streamverwerking wordt niet ondersteund door de context [SWS_CRYPT_50158].