klasse ara::crypto::cryp::KeyAgreementPrivateCtx

De interface ara::crypto::cryp::KeyAgreementPrivateCtx dient voor het uitvoeren van cryptografische sleutelovereenkomstprocedures op basis van een lokale privésleutel en de openbare sleutel van een tegenpartij [SWS_CRYPT_21312]. Na toewijzing van de eigen sleutel en optionele parameters berekent de methode AgreeKey een gedeeld geheim en levert dit terug als een symmetrisch sleutelobject. Een centrale randvoorwaarde is de volledige initialisatie voorafgaand aan de uitvoering, aangezien ontbrekende parameters of ontbrekende rechten voor kAllowKeyAgreement leiden tot afbreken met bijbehorende foutcodes [SWS_CRYPT_21312]. Alle bewerkingen zijn daarbij thread-safe ontworpen.

meer ›

Context

De interface ara::crypto::cryp::KeyAgreementPrivateCtx dient in de module crypto van het Adaptive Platform voor het uitvoeren van asymmetrische sleutelovereenkomstprocedures (Key Agreement). De centrale verantwoordelijkheid ervan ligt in de berekening van een gedeelde symmetrische sleutel uit een lokale privésleutel en de openbare sleutel van een communicatiepartner [SWS_CRYPT_21312]. Als gespecialiseerde cryptocontext interageert de klasse met meerdere sleutel- en opslagabstracties: de eigen privésleutel kan hetzij direct als PrivateKey-object [SWS_CRYPT_21313] hetzij gerefereerd via een KeySlot [SWS_CRYPT_50053] worden gebonden. De tegenpartij draagt haar openbare sleutel bij in de vorm van een PublicKey, terwijl het resultaat als zelfstandig SymmetricKey-object beschikbaar wordt gesteld [SWS_CRYPT_21312]. Aanvullend kunnen algoritmespecifieke configuratieparameters als geheugenbereik of geheel getal worden doorgegeven [SWS_CRYPT_50051], [SWS_CRYPT_50052].

Contextdiagram: samenspel van KeyAgreementPrivateCtx met sleutels, sleutelposities en resultaatobject. Bronnen: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50053].

Levenscyclus

Levenscyclus en eigendomsverhoudingen van KeyAgreementPrivateCtx zijn gebaseerd op shared pointers; de specificatie stelt hiervoor de type-alias KeyAgreementPrivateCtx::Sptr beschikbaar [SWS_CRYPT_21301]. Interpretatie: de instantiëring zal vermoedelijk plaatsvinden via een bovenliggende factory van een CryptoProvider, aangezien de klasse een zuiver virtuele interface zonder constructorspecificatie vormt. Vraag Q-22dca518675fba51 (open) Na het aanmaken bevindt de instantie zich in een niet-bedrijfsklare basistoestand. Pas door de configuratie van een privésleutel via SetKey [SWS_CRYPT_21313], [SWS_CRYPT_50053] en de toewijzing van alle voor het gekozen schema vereiste parameters [SWS_CRYPT_50051], [SWS_CRYPT_50052] wordt de context geïnitialiseerd.

Wordt een sleutelberekening gestart voordat deze configuratiestappen zijn voltooid, dan mislukt de aanroep [SWS_CRYPT_21312]. Wat betreft gelijktijdigheid zijn alle memberfuncties gespecificeerd als thread-safe (thread-safe) en uitzonderingsveilig (exception safe) [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Aangezien de uitvoeringsfunctie AgreeKey als const is gedeclareerd [SWS_CRYPT_21312], kan dezelfde geïnitialiseerde context parallel worden gebruikt voor overeenkomsten met verschillende tegenpartijen.

Gebruikspad

Het praktische gebruik is onderverdeeld in een sequentiële opeenvolging van configuratie en berekening:

• Sleuteltoewijzing: eerst bindt de applicatie de eigen privésleutel aan de context. Dit gebeurt hetzij via SetKey(PrivateKey::Sptr) [SWS_CRYPT_21313] voor een geladen sleutelobject hetzij via SetKey(KeySlot::Sptr) [SWS_CRYPT_50053] voor een sleutelpositie waarvan de inhoud pas op het moment van de overeenkomst wordt geëvalueerd.
• Parameterdefinitie: indien het doelalgoritme aanvullende initialisatiegegevens vereist, worden deze via SetParameter als buffer ReadOnlyMemRegion [SWS_CRYPT_50051] of als 64-bits geheel getal std::uint64_t [SWS_CRYPT_50052] doorgegeven.
• Sleutelovereenkomst: met AgreeKey wordt het cryptografische algoritme uitgevoerd [SWS_CRYPT_21312]. De aanroepende component geeft de openbare sleutel van de tegenpartij (otherSideKey), de identifier van het gewenste doelalgoritme (targetAlgId) en de toegestane gebruiksvlaggen (allowedUsage) door.
• Overname van het resultaat: bij succesvolle voltooiing levert AgreeKey een SymmetricKey-object op dat het berekende gedeelde geheim bevat [SWS_CRYPT_21312].

Sequentiediagram: typisch verloop van de sleutelovereenkomst van de sleuteltoewijzing tot de aanmaak van de symmetrische sleutel. Bronnen: [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051].

Foutscenario's

Methoden van KeyAgreementPrivateCtx retourneren fouten via ara::core::Result en waarborgen rollback-semantiek [SWS_CRYPT_21312], [SWS_CRYPT_21313], [SWS_CRYPT_50051], [SWS_CRYPT_50052], [SWS_CRYPT_50053]. Typische foutscenario's omvatten:

• CryptoErrc::kUninitializedContext: treedt op bij AgreeKey indien vooraf geen sleutel is ingesteld of vereiste parameters ontbreken [SWS_CRYPT_21312].
• CryptoErrc::kIncompatibleObject: wordt gerapporteerd wanneer een doorgegeven PrivateKey of KeySlot niet past bij het type van de context [SWS_CRYPT_21313], [SWS_CRYPT_50053], of wanneer de sleutel van de tegenpartij otherSideKey incompatibel is [SWS_CRYPT_21312].
• CryptoErrc::kUsageViolation: geeft aan dat voor de privésleutel of de sleutel van de tegenpartij het recht kAllowKeyAgreement niet is verleend [SWS_CRYPT_21312], [SWS_CRYPT_21313].
• CryptoErrc::kUnsupported: wijst erop dat de contextimplementatie uitsluitend de telkens andere SetKey-variant ondersteunt [SWS_CRYPT_21313], [SWS_CRYPT_50053], of dat een aangevraagde parameternaam niet wordt ondersteund [SWS_CRYPT_50051], [SWS_CRYPT_50052].
• CryptoErrc::kInvalidArgument: ontstaat bij ongeldige waarden in SetParameter [SWS_CRYPT_50051], [SWS_CRYPT_50052] of ontoelaatbare allowedUsage-vlaggen voor de doelsleutel [SWS_CRYPT_21312].
• CryptoErrc::kUnknownIdentifier: wordt geactiveerd indien de identifier targetAlgId voor het doelalgoritme onbekend is [SWS_CRYPT_21312].
• CryptoErrc::kEmptyKeySlot en CryptoErrc::kBusyResource: worden door AgreeKey geretourneerd wanneer de geconfigureerde KeySlot op het tijdstip van uitvoering geen sleutel bevat of een benodigde resource bezet is [SWS_CRYPT_21312].