Key Manager (KeyM)

De functie KeyM_Init dient voor de initialisatie van de Key Management-module ([SWS_KeyM_00043]). De aanroep geschiedt synchroon en is gedefinieerd als niet-re-entrant ([SWS_KeyM_00043]). Als enige overdrachtsparameter wordt ConfigPtr verwacht, die een pointer naar de configuratiedataset voor VARIANT-POST-BUILD vormt; de functie heeft geen retourwaarde ([SWS_KeyM_00043]).

Met betrekking tot de interactie met andere modulefuncties vormt KeyM_Init een dwingende voorwaarde: Bij geactiveerde ontwikkelingsdetectie controleren alle overige functies van de Key Manager of de module vooraf via KeyM_Init is geïnitialiseerd en nog niet door middel van KeyM_Deinit is gede-initialiseerd ([SWS_KeyM_00144]). Wordt een modulefunctie in niet-geïnitialiseerde status aangeroepen, dan meldt de Key Manager de ontwikkelingsfout KEYM_E_UNINIT ([SWS_KeyM_00144]).

Aangezien KeyM_Init als niet-re-entrant is gespecificeerd ([SWS_KeyM_00043]), mag de functie in de systeeminitialisatiefase slechts eenmalig en met uitsluiting van gelijktijdige aanroepen worden uitgevoerd. De module is na succesvolle uitvoering beschikbaar via het headerbestand KeyM.h ([SWS_KeyM_00043]).

De functie KeyM_Deinit dient ertoe om de module Key Manager weer terug te zetten naar de niet-geïnitialiseerde toestand ([SWS_KeyM_00047]).

Gebruik en aanroepcontext

De aanroep van KeyM_Deinit vindt synchroon plaats en is gespecificeerd als niet re-entrant (Non Reentrant). De functie heeft service-ID 0x02, accepteert geen parameters en levert geen retourwaarde op ([SWS_KeyM_00047]).

Gelijktijdigheid en wisselwerking

Vanwege de niet-re-entrantie mag KeyM_Deinit niet concurrent aan zichzelf of in strijd met lopende operaties worden aangeroepen. Na uitvoering van deze de-initialisatie bevindt de module zich in de niet-geïnitialiseerde toestand. Als ontwikkelingsfouten zijn ingeschakeld, controleert de Key Manager bij elke daaropvolgende functieaanroep of de module vooraf via KeyM_Init() is geïnitialiseerd en nog niet middels KeyM_Deinit() is gede-initialiseerd; anders wordt de ontwikkelingsfout KEYM_E_UNINIT gemeld ([SWS_KeyM_00144]).

De synchrone functie KeyM_Start dient ertoe bewerkingen voor sleutelactualisering in de Key Manager vrij te geven ([SWS_KeyM_00050]). Deze is optioneel en is alleen beschikbaar als de configuratieparameter KeyMCryptoKeyStartFinalizeFunctionEnabled op true is geconfigureerd (AUTOSAR_SWS_KeyManager p. 35). De functie wordt beschikbaar gesteld via KeyM.h en verwacht via StartType de uit te voeren bedrijfsmodus en via Request Data en Request Data Length aanvullende aanvraaggegevens zoals een handtekening.

Antwoordgegevens worden geretourneerd via de uitvoerbuffer Response Data. De parameter Response Data Length fungeert daarbij als in- en uitvoerparameter: Vóór de aanroep definieert deze het maximaal in de buffer beschikbare aantal bytes, na de uitvoering bevat deze de daadwerkelijk geschreven gegevenslengte ([SWS_KeyM_00050]).

Foutafhandeling en retourwaarden:

• E_OK: Startbewerking succesvol uitgevoerd; sleutelactualiseringen zijn nu toegestaan.
• E_NOT_OK: Startbewerking niet geaccepteerd.
• KEYM_E_PARAMETER_MISMATCH: Doorgegeven parameters komen niet overeen met de verwachte waarden.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Een doorgegeven parametergrootte komt niet overeen met de verwachte grootte.

De functie is gespecificeerd als niet-re-entrant (Non Reentrant) ([SWS_KeyM_00050]). Aangezien er geen module-interne vergrendelingen zijn beschreven, dient de oproepende instantie vermoedelijk te zorgen voor een gecoördineerde, geserialiseerde uitvoering. Vraag Q-82276b712a8dd170 (open)

De synchrone functie KeyM_Prepare dient ter voorbereiding van een sleutelactualisering (Key Update Operation) en verzendt de vereiste informatie naar de sleutelserver of initieert de onderhandeling over een gedeeld geheim voor sleutelafleiding [SWS_KeyM_00051]. De functie heeft het service-ID 0x05, is gedeclareerd via de header KeyM.h en is uitsluitend beschikbaar wanneer de configuratieparameter Key MCrypto Key Prepare Function Enabled op TRUE is ingesteld [SWS_KeyM_00051].

Bij de aanroep moeten de volgende buffers en lengtespecificaties worden doorgegeven [SWS_KeyM_00051]:

• Request Data en Request Data Length: Invoergegevens en de lengte daarvan voor de aanvraag [SWS_KeyM_00051].
• Response Data: Pointer naar de buffer voor opname van de uitvoergegevens [SWS_KeyM_00051].
• Response Data Length: In-/uitvoerparameter die vóór de aanroep de maximaal beschikbare buffergrootte aangeeft en bij terugkeer het daadwerkelijk geschreven aantal bytes bevat [SWS_KeyM_00051].

Wordt de aanroep met E_OK bevestigd, dan is de service geaccepteerd en wordt deze intern verwerkt; de uiteindelijke resultaten worden vervolgens via een callback beschikbaar gesteld [SWS_KeyM_00051]. Faalt de acceptatie, dan retourneert de functie E_NOT_OK bij interne fouten, KEYM_E_PARAMETER_MISMATCH bij afwijkende parameterwaarden of KEYM_E_KEY_CERT_SIZE_MISMATCH bij niet-passende groottespecificaties [SWS_KeyM_00051].

Aangezien KeyM_Prepare als niet-re-entrant (Non Reentrant) is gespecificeerd, mogen er geen gelijktijdige of geneste aanroepen plaatsvinden [SWS_KeyM_00051].

De functie KeyM_Finalize sluit actualiseringsprocessen voor sleutels af en brengt de sleuteloperatie terug naar de rusttoestand (idle-modus) [SWS_KeyM_00053]. Deze wordt typisch gebruikt in combinatie met een voorafgaande KeyM_Start-operatie. Na de aanroep accepteert de module geen verdere voorbereidings- of actualiseringsoperaties (Prepare/Update) totdat via KeyM_Start een nieuw proces wordt geïnitieerd [SWS_KeyM_00053]. Daarnaast wordt het geactualiseerde sleutelmateriaal gepersisteerd en door de aanroep van Csm_KeySetValid in de geldige toestand gebracht [SWS_KeyM_00053].

Gebruik en gelijktijdigheid: KeyM_Finalize is niet-re-entrant (Non Reentrant) en werkt asynchroon [SWS_KeyM_00053]. Interpretatie: Wegens het ontbreken van re-entrantie dient de aanroep typisch in de taakcontext plaats te vinden. Vraag Q-895ebec2d0d2e635 (open) De interface is alleen beschikbaar wanneer de configuratieparameter KeyMCryptoKeyStartFinalizeFunctionEnabled op TRUE is ingesteld, en is gedeclareerd via KeyM.h [SWS_KeyM_00053].

Parameters en retourwaarden: Via RequestDataPtr en RequestDataLength worden aanvraagspecifieke gegevens doorgegeven. Antwoordgegevens worden beschikbaar gesteld via ResponseDataPtr; ResponseMaxDataLength dient bij binnenkomst als buffergrootte en levert bij synchrone terugkeer het daadwerkelijke aantal bytes op [SWS_KeyM_00053]. Wordt de operatie geaccepteerd en intern verwerkt, dan retourneert de functie E_OK (de resultaten volgen asynchroon via callback) en blijft ResponseMaxDataLength onaangeroerd [SWS_KeyM_00053].

Foutafhandeling: In geval van een fout signaleert KeyM_Finalize het mislukken via specifieke retourwaarden [SWS_KeyM_00053]:

• E_NOT_OK: Bewerking wegens een interne fout niet geaccepteerd.
• KEYM_E_BUSY: KeyM is bezig met andere opdrachten; validatie kan nog niet worden uitgevoerd.
• KEYM_E_PARAMETER_MISMATCH: Parameters komen niet overeen met de verwachte waarde.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Parametergrootte komt niet overeen.

Gebruik

De synchrone functie KeyM_SetCertificate draagt certificaatgegevens over aan de sleutelbeheermodule om een certificaat tijdelijk op te slaan [SWS_KeyM_00057]. Deze verwacht als invoerparameters de identificatie van het certificaat CertId (type KeyM_CertificateIdType) en de pointer CertificateDataPtr (type const KeyM_CertDataType*), die verwijst naar de beschikbaar te stellen certificaatstructuur [SWS_KeyM_00057]. De interface wordt gedeclareerd via de header KeyM.h en heeft het service-ID 0x0a [SWS_KeyM_00057].

Retourwaarden en foutafhandeling

De retourwaarde van het type Std_ReturnType geeft informatie over de acceptatie van de gegevens [SWS_KeyM_00057]:

• E_OK: Het certificaat is succesvol geaccepteerd [SWS_KeyM_00057].
• E_NOT_OK: Het certificaat kon niet worden ingesteld [SWS_KeyM_00057].
• KEYM_E_PARAMETER_MISMATCH: De doorgegeven parameters komen niet overeen met de verwachte waarden [SWS_KeyM_00057].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: De grootte van de doorgegeven certificaatgegevens wijkt af van de verwachte grootte [SWS_KeyM_00057].

Gelijktijdigheid en beperkingen

De functie is geclassificeerd als niet-re-entrant (Non Reentrant) [SWS_KeyM_00057]. Concurrerende aanroepen moeten daarom aan de zijde van de oproepende instantie worden gesynchroniseerd of uitgesloten. Aangezien de specificatie expliciet voorziet in een tijdelijke opslag, blijven de doorgegeven certificaatgegevens vermoedelijk eerst in het vluchtige geheugen van de module aanwezig voordat permanente opslag of verificatie plaatsvindt. Vraag Q-c35c4b02344d5bc9 (open)

Gebruik

De synchrone functie KeyM_GetCertificate dient ertoe de certificaatgegevens voor een opgegeven certificaatidentificatie beschikbaar te stellen [SWS_KeyM_00058]. De oproeper geeft via de parameter CertId de identifier van het gewenste certificaat door en via de inout-parameter CertificateDataPtr een pointer naar de certificaatdatastructuur. De oproeper is er verantwoordelijk voor de buffer beschikbaar te stellen waarnaar de pointer in de structuur verwijst [SWS_KeyM_00058]. Voorafgaand aan de oproep moet in de structuur de maximale lengte van deze buffer zijn aangegeven; bij succesvolle teruggave (E_OK) bevat het lengteveld de werkelijke lengte van de beschikbaar gestelde certificaatgegevens [SWS_KeyM_00058].

Foutafhandeling

De functie signaleert het slagen of specifieke fouten via de returnwaarde van het type Std_ReturnType [SWS_KeyM_00058]:

• E_OK: Certificaatgegevens zijn beschikbaar en zijn met succes doorgegeven.
• KEYM_E_PARAMETER_MISMATCH: De meegegeven certificaat-ID (CertId) is ongeldig.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: De beschikbaar gestelde buffer is te klein voor het certificaat.
• KEYM_E_KEY_CERT_EMPTY: Er zijn geen certificaatgegevens aanwezig, omdat het certificaatslot leeg is.
• KEYM_E_KEY_CERT_READ_FAIL: Het certificaat kan niet beschikbaar worden gesteld, omdat de toegang is geweigerd.
• E_NOT_OK: De bewerking is vanwege een interne fout niet geaccepteerd.

Gelijktijdigheid en beperkingen

De functie is gespecificeerd als niet-re-entrant (Non Reentrant) en is beschikbaar via het headerbestand KeyM.h [SWS_KeyM_00058]. Oproepers moeten daarom waarborgen dat parallelle oproepen van de functie onderling worden gesynchroniseerd.

De functie KeyM_VerifyCertificates dient voor de asynchrone controle van twee intern opgeslagen en geparseerde certificaten ten opzichte van elkaar conform [SWS_KeyM_00059]. Daarbij wordt gevalideerd of het via CertId gereferentieerde onderliggende certificaat is ondertekend door het met CertUpperId gereferentieerde bovenliggende certificaat.

Aangezien de service als niet re-entrant (Non Reentrant) is gedefinieerd, mag deze niet concurrent voor overlappende handelingen worden aangeroepen [SWS_KeyM_00059]. De uitvoering vindt asynchroon op de achtergrond plaats: een retourwaarde van E_OK geeft enkel de succesvolle acceptatie van de controleopdracht aan. Het eigenlijke controleresultaat wordt aan de aanroeper meegedeeld via de geconfigureerde callbackfunctie KeyMCertificateVerifyCallbackNotificationFunc, mits deze geldig is geconfigureerd [SWS_KeyM_00153].

Wordt het verzoek niet geaccepteerd, dan levert de functie specifieke retourwaarden voor foutafhandeling [SWS_KeyM_00059]:

• KEYM_E_BUSY: De Key Manager is bezet met andere taken; de validatie kan op dit moment nog niet worden gestart.
• KEYM_E_PARAMETER_MISMATCH: Minstens één doorgegeven certificaat-ID is ongeldig.
• KEYM_E_KEY_CERT_EMPTY: Een van de gereferentieerde certificaatslots is leeg.
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Het bovenliggende certificaat (CertUpperId) is niet geldig.
• E_NOT_OK: De opdracht is afgewezen vanwege een interne fout.

De functie KeyM_VerifyCertificate dient voor de asynchrone verificatie van een certificaat dat eerder via KeyM_SetCertificate() beschikbaar is gesteld [SWS_KeyM_00060]. De controle vindt plaats aan de hand van de doorgegeven certificaatidentificatie CertId ten opzichte van reeds in de Key Manager opgeslagen certificaten van andere certificaat-ID's [SWS_KeyM_00060]. De declaratie is beschikbaar via het headerbestand KeyM.h [SWS_KeyM_00060].

Oproepsemantiek en returnwaarden

Een returnwaarde van E_OK bevestigt dat het verificatieverzoek met succes is geaccepteerd en de bewerking op de achtergrond wordt uitgevoerd [SWS_KeyM_00060]. Als de opdracht niet kan worden aangenomen, volgt de terugmelding synchroon via specifieke foutcodes [SWS_KeyM_00060]:

• E_NOT_OK: De bewerking is vanwege een interne fout afgewezen [SWS_KeyM_00060].
• KEYM_E_BUSY: De module KeyM is momenteel bezet met andere taken, waardoor de validatie nog niet kan worden uitgevoerd [SWS_KeyM_00060].
• KEYM_E_PARAMETER_MISMATCH: de meegegeven CertId is ongeldig [SWS_KeyM_00060].
• KEYM_E_KEY_CERT_EMPTY: Ten minste een van de benodigde certificaatslots is leeg [SWS_KeyM_00060].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Een bovenliggend certificaat in de vertrouwensketen is ongeldig [SWS_KeyM_00060].

Gelijktijdigheid en asynchronie

Aangezien KeyM_VerifyCertificate als niet-re-entrant (Non Reentrant) is gespecificeerd, moet de oproeper waarborgen dat er geen gelijktijdige of onderbrekende oproepen plaatsvinden [SWS_KeyM_00060]. Na succesvolle aanname van de controleopdracht (teruggave E_OK) wordt het resultaat van de achtergrondbewerking doorgegeven aan de geconfigureerde callbackfunctie KeyMCertificateVerifyCallbackNotificationFunc, mits deze van een geldige functienaam is voorzien [SWS_KeyM_00153].

De functie KeyM_VerifyCertificateChain dient voor de asynchrone verificatie van een certificaat ten opzichte van een keten van doorgegeven certificaten [SWS_KeyM_00061]. Als parameters worden de identificatie van het laatste certificaat van de keten (CertId), een pointer naar de conform de PKI-volgorde gesorteerde certificatenarray (certChainData) alsmede het aantal certificaten (NumberOfCertificates) doorgegeven [SWS_KeyM_00061]. Voorafgaand aan de aanroep moet het te controleren certificaat via KeyM_SetCertificate() zijn geregistreerd, en het rootcertificaat moet ofwel in de lijst zijn opgenomen of al aan een van de andere certificaten zijn toegewezen [SWS_KeyM_00061].

De functie is niet re-entrant (Non Reentrant) en wordt via het headerbestand KeyM.h beschikbaar gesteld [SWS_KeyM_00061]. De volgende synchrone retourwaarden geven de status van de acceptatie van de opdracht aan [SWS_KeyM_00061]:

• E_OK: De controleopdracht is geaccepteerd en wordt op de achtergrond uitgevoerd [SWS_KeyM_00061].
• E_NOT_OK: De opdracht is afgewezen vanwege een interne fout [SWS_KeyM_00061].
• KEYM_E_BUSY: De module is bezet met andere opdrachten; de validatie kan nog niet worden uitgevoerd [SWS_KeyM_00061].
• KEYM_E_PARAMETER_MISMATCH: De doorgegeven certificaat-ID is ongeldig [SWS_KeyM_00061].
• KEYM_E_KEY_CERT_EMPTY: Een van de benodigde certificaatslots is leeg [SWS_KeyM_00061].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Een bovenliggend certificaat in de vertrouwensketen is ongeldig [SWS_KeyM_00061].

Werd de opdracht met E_OK geaccepteerd, dan vindt de evaluatie op de achtergrond plaats. Indien KeyMCertificateVerifyCallbackNotificationFunc is geconfigureerd met een geldige functie, meldt KeyM het eindresultaat van de verificatieoperatie via deze callbackfunctie terug aan de aanroepende applicatie [SWS_KeyM_00061] [SWS_KeyM_00153].

Gebruik en aanroepcontext

De synchrone functie KeyM_CertElementGet dient voor het uitlezen van de gegevens van een specifiek certificaatelement uit een certificaatslot naar een door de oproeper beschikbaar gestelde buffer [SWS_KeyM_00063]. Deze wordt toegepast wanneer aan de in de certificaatconfiguratie opgeslagen objectidentificatie (OID) precies één enkel element is toegewezen [SWS_KeyM_00063].

De oproeper geeft de certificaatidentificatie CertId, de elementidentificatie CertElementId en een pointer naar de doelbuffer CertElementData door [SWS_KeyM_00063]. De parameter CertElementDataLength dient als gecombineerde invoer- en uitvoerwaarde: vóór de oproep moet deze de maximale buffergrootte bevatten. In geval van succes (E_OK) wordt deze overschreven met de werkelijke lengte van de geschreven gegevens; in geval van een fout stelt de functie de gereferentieerde waarde terug op nul [SWS_KeyM_00063].

Foutafhandeling en retourwaarden

De functie meldt de uitvoeringsstatus via de volgende returnwaarden [SWS_KeyM_00063]:

• E_OK: Het element is gevonden en met succes naar de buffer gekopieerd [SWS_KeyM_00063].
• E_NOT_OK: De elementgegevens zijn niet gevonden [SWS_KeyM_00063].
• KEYM_E_PARAMETER_MISMATCH: Ongeldige CertId of CertElementId [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: De beschikbaar gestelde buffer is te klein voor de gegevens van het element [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_EMPTY: Voor het opgegeven slot bestaan geen gegevens, het slot is leeg [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_INVALID: Het certificaat is ongeldig of is nog niet geverifieerd [SWS_KeyM_00063].

Concurrency

De functie is gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_KeyM_00063]. Bij gelijktijdige oproepen vanuit verschillende taken of contexten is daarom vermoedelijk synchronisatie aan de zijde van de oproeper vereist. Vraag Q-238a3e53ce0e3a45 (open)

De synchrone functie KeyM_CertificateElementGetByIndex dient voor het gericht uitlezen van gegevens van een certificaatelement aan de hand van een zero-based index (0..N), wanneer er voor een elementtype meerdere invoeren aanwezig zijn [SWS_KeyM_91014]. Deze vormt daarmee een alternatief met directe toegang voor de sequentiële iteratie.

Gebruik en parameters

De aanroeper geeft de certificaat-ID CertId, de element-ID CertElementId en de gewenste Index door [SWS_KeyM_91014]. Bovendien moet de aanroeper het geheugen voor CertElementDataPtr alloceren en via CertElementDataLengthPtr de maximaal beschikbare buffergrootte doorgeven. Bij een succesvolle terugkeer wordt CertElementDataLengthPtr overschreven met de werkelijke lengte van de gekopieerde gegevens [SWS_KeyM_91014].

Retourwaarden en foutafhandeling

De functie signaleert het resultaat via specifieke Std_ReturnType-retourwaarden [SWS_KeyM_91014]:

• E_OK: Het element is gevonden en succesvol naar de doelbuffer gekopieerd.
• KEYM_E_PARAMETER_MISMATCH: Ongeldige CertId, ongeldige CertElementId of de doorgegeven Index ligt buiten het geldige bereik.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: De gereedgestelde buffer is te klein voor het certificaatelement.
• KEYM_E_KEY_CERT_EMPTY: Het opgegeven certificaat bevat geen gegevens respectievelijk is leeg.
• KEYM_E_CERT_INVALID: Het certificaat is ongeldig of de verificatie was niet succesvol.
• E_NOT_OK: Het uitlezen van de elementgegevens is mislukt.

Concurrency

Volgens de specificatie is de service geclassificeerd als niet-re-entrant (Non Reentrant) [SWS_KeyM_91014]. Aanroepen mogen daarom niet onbeschermd gelijktijdig worden uitgevoerd.

De synchrone interface KeyM_CertificateElementGetCount bepaalt het totale aantal gegevenselementen dat voor een specifiek certificaatelement is opgeslagen en schrijft het resultaat in de buffer CountPtr [SWS_KeyM_91015].

Gebruik en parameters

De functie wordt gedeclareerd via de header KeyM.h en heeft de service-ID 0x1c [SWS_KeyM_91015]. Deze verwerkt de volgende parameters:

• CertId (IN): Unieke ID van het op te vragen certificaat ([SWS_KeyM_91015]).
• CertElementId (IN): Bepaalt het concrete element binnen het certificaat ([SWS_KeyM_91015]).
• CountPtr (OUT): Pointer naar de buffer van het type uint16, waarin het aantal beschikbare gegevenselementen wordt gekopieerd ([SWS_KeyM_91015]).

Foutafhandeling en retourwaarden

De retourwaarde van het type Std_ReturnType verschaft informatie over het resultaat van de uitvoering [SWS_KeyM_91015]:

• E_OK: De telwaarde is succesvol in de buffer geschreven ([SWS_KeyM_91015]).
• E_NOT_OK: De telwaarde kon niet ter beschikking worden gesteld ([SWS_KeyM_91015]).
• KEYM_E_PARAMETER_MISMATCH: De certificaat-ID (CertId) of de element-ID (CertElementId) is ongeldig of ligt buiten het toegestane bereik ([SWS_KeyM_91015]).

Gelijktijdigheid en wisselwerking

De uitvoering is synchroon, maar geclassificeerd als niet-re-entrant (Non Reentrant), zodat gelijktijdige aanroepen moeten worden gecoördineerd [SWS_KeyM_91015]. Terwijl aan certificaatelementen typisch slechts één enkel gegevenselement is toegewezen, kunnen in bepaalde gevallen meerdere gegevenselementen achter elkaar aanwezig zijn [SWS_KeyM_91015]. Het vastgestelde totale aantal dient als basis om de afzonderlijke elementen vervolgens gericht via KeyM_CertificateElementGetByIndex() uit te lezen, wat functioneel vergelijkbaar is met de iteratieve benadering met KeyM_CertElementGetFirst en KeyM_CertElementGetNext [SWS_KeyM_91015].

De synchrone functie KeyM_CertElementGetFirst dient er conform [SWS_KeyM_00064] toe de iteratieve extractie van certificaatgegevens in te leiden. Deze leest het bovenste element van het via CertElementId geadresseerde certificaatelement uit het certificaat CertId uit en initialiseert de iteratorconstructie CertElementIterator voor opeenvolgende oproepen van KeyM_CertElementGetNext().

Bij de oproep moeten de volgende parameter- en geheugenvereisten conform [SWS_KeyM_00064] in acht worden genomen:

• CertElementIterator: Pointer naar een door de oproeper gealloceerde en beheerde structuur; deze mag door de applicatie noch worden vernietigd noch worden gewijzigd zolang niet alle gegevens via KeyM_CertElementGetNext() zijn opgehaald.
• CertElementData: Pointer naar een door de oproeper beschikbaar gestelde uitvoerbuffer, waarin bij succesvol aantreffen (E_OK) de payload wordt gekopieerd.
• CertElementDataLength: Geeft als invoer de maximale lengte van de databuffer door en wordt bij teruggave van E_OK overschreven met de werkelijk geschreven datalengte.

Wat betreft gelijktijdigheid is de service volgens [SWS_KeyM_00064] re-entrant, maar dan met betrekking tot precies één iterator (“Reentrant for one iterator”).

In geval van een fout differentieert de functie via specifieke returnwaarden conform [SWS_KeyM_00064]: E_NOT_OK geeft aan dat er geen elementgegevens zijn gevonden (de iterator mag daarna niet voor verdere oproepen worden gebruikt). KEYM_E_PARAMETER_MISMATCH signaleert een ongeldige certificaat- of element-ID, KEYM_E_KEY_CERT_SIZE_MISMATCH een te kleine databuffer, KEYM_E_KEY_CERT_EMPTY een leeg certificaat zonder beschikbare gegevens en KEYM_E_CERT_INVALID een ongeldig of niet succesvol geverifieerd certificaat.

De synchrone functie KeyM_CertElementGetNext (service-ID 0x11, beschikbaar gesteld via KeyM.h) dient voor het doorlopend uitlezen van verdere gegevens uit een certificaatelement, indien daarin meerdere records sequentieel zijn opgeslagen [SWS_KeyM_00065]. Als dwingende oproepvoorwaarde vereist de specificatie dat vooraf ten minste eenmaal de functie KeyM_CertElementGetFirst() is opgeroepen [SWS_KeyM_00065].

De geheugengebieden voor alle parameters moeten door de oproepende applicatie beschikbaar worden gesteld [SWS_KeyM_00065]:

• CertElementIterator: Pointer naar een gealloceerde iteratorstructuur, die door de applicatie tijdens het doorlopen noch mag worden gewijzigd noch mag worden vernietigd totdat alle elementen volledig zijn uitgelezen [SWS_KeyM_00065].
• CertElementData: Pointer naar de uitvoerbuffer, waarin de functie bij succesvolle uitvoering de payload kopieert [SWS_KeyM_00065].
• CertElementDataLength: Geeft bij de oproep de maximale capaciteit van de databuffer door en wordt bij succesvolle teruggave overschreven met de werkelijke lengte van de gekopieerde gegevens [SWS_KeyM_00065].

Levert de oproep E_OK op, dan is het volgende element gevonden, naar de buffer geschreven en de iterator dienovereenkomstig verdergezet [SWS_KeyM_00065]. Bij E_NOT_OK konden geen verdere elementgegevens worden gevonden; in dit geval mag de iterator voor geen verdere oproepen meer worden gebruikt [SWS_KeyM_00065]. Foutsituaties worden via specifieke returnwaarden gemeld: KEYM_E_KEY_CERT_SIZE_MISMATCH geeft een te klein gedimensioneerde databuffer aan, KEYM_E_PARAMETER_MISMATCH een ongeldige certificaat- of element-ID, KEYM_E_KEY_CERT_EMPTY een leeg certificaat en KEYM_E_CERT_INVALID een ongeldig of niet succesvol geverifieerd certificaat [SWS_KeyM_00065].

Met betrekking tot gelijktijdigheid is de synchrone functie gespecificeerd als re-entrant voor telkens één iterator [SWS_KeyM_00065].

De synchrone functie KeyM_CertGetStatus dient ertoe de status van een certificaat op te vragen en via een uitvoerparameter beschikbaar te stellen [SWS_KeyM_00066]. De declaratie van de functie is toegankelijk via het headerbestand KeyM.h, en aan de service is de hexadecimale service-ID 0x12 toegewezen [SWS_KeyM_00066].

Voor de oproep worden de volgende parameters gebruikt [SWS_KeyM_00066]:

• CertId (IN): Bevat de identifier van het op te vragen certificaat en wordt met het datatype KeyM_CertificateIdType doorgegeven [SWS_KeyM_00066].
• Status (OUT): Pointer naar het geheugengebied van het type KeyM_CertificateStatusType, waarin de functie de vastgestelde status van het certificaat schrijft [SWS_KeyM_00066].

De returnwaarde van het type Std_ReturnType informeert over de afloop van het opvragen van de status [SWS_KeyM_00066]:

• E_OK: De certificaatstatus is met succes vastgesteld en beschikbaar gesteld [SWS_KeyM_00066].
• E_NOT_OK: Het beschikbaar stellen van de status is momenteel niet mogelijk [SWS_KeyM_00066]. Dit treedt bijvoorbeeld op wanneer een ongeldige certificaat-ID wordt doorgegeven, gedocumenteerd met de foutcode KEYM_E_PARAMETER_MISMATCH [SWS_KeyM_00066].

Wat betreft uitvoering en gelijktijdigheid gedraagt de interface zich zuiver synchroon en is deze gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_KeyM_00066]. Gelijktijdige oproepen over meerdere uitvoeringscontexten heen zijn derhalve niet toegestaan. Aanvullende invoer- en uitvoerparameters zijn voor deze interface niet voorzien [SWS_KeyM_00066].

De functie KeyM_MainFunction dient als periodieke hoofdfunctie voor de Classic-AUTOSAR-module KeyM [SWS_KeyM_00074]. Conform de specificatie beschikt de functie over service-ID 0x19 in hexadecimale weergave alsmede de signatuur void KeyM_MainFunction (void) [SWS_KeyM_00074]. Aanroepende instanties geven zodoende geen invoerparameters door en ontvangen geen retourwaarde [SWS_KeyM_00074].

Voor de timing is vastgelegd dat de functie periodiek volgens een gedefinieerd tijdsinterval moet worden aangeroepen [SWS_KeyM_00074]. Als interfacebestand is het headerbestand SchM_KeyM.h gedeclareerd [SWS_KeyM_00074]. Hieruit vloeit de interpretatie voort: door de beschikbaarstelling via SchM_KeyM.h vindt de regelmatige aanroep van de functie vermoedelijk plaats in de context van de basissoftwarescheduler (SchM) [SWS_KeyM_00074]. Vraag Q-761ff71812bda3c2 (open) Bovendien dient de cyclische triggering vermoedelijk voor de interne verwerking van tijdsafhankelijke processen in de module KeyM.

Wat betreft foutafhandeling en foutgedrag zijn voor deze service geen retourcodes, foutconstanten of meldingen aan DET of DEM gedocumenteerd in het specificatie-element [SWS_KeyM_00074]. Aangezien er geen invoerparameters bestaan, vervalt ook een controle van overdrachtswaarden bij de aanroep [SWS_KeyM_00074].

Gebruik en aanroepcontext

De functie KeyM_MainBackgroundFunction heeft de signatuur void KeyM_MainBackgroundFunction(void) en is gespecificeerd onder de service-ID 0x1a [SWS_KeyM_00075]. Ze accepteert geen overdrachtsparameters en retourneert geen retourwaarde aan de aanroeper [SWS_KeyM_00075]. Voor integratie wordt de interface via het headerbestand SchM_KeyM.h gedeclareerd en beschikbaar gesteld [SWS_KeyM_00075].

De aanroep geschiedt door een preemptief besturingssysteem op de achtergrond zodra er geen overige taakbewerking voor afhandeling wacht [SWS_KeyM_00075]. Het primaire doel van deze functie is het bieden van een niet-kritische achtergrondcontext voor tijdrovende, synchrone bewerkingen van de module KeyM, zoals bijvoorbeeld beschreven voor de uitvoering van KeyM_KH_Update() [SWS_KeyM_00075].

Gelijktijdigheid en foutafhandeling

Aangezien de functie in de achtergrondcontext van een preemptief besturingssysteem wordt uitgevoerd, kan deze vermoedelijk op elk moment worden onderbroken door willekeurige reguliere taken met een hogere prioriteit. Vraag Q-a2394a51ba63467f (open) Voor deze achtergrondservice specificeert de standaard noch specifieke foutcodes noch meldingen aan de DET of DEM [SWS_KeyM_00075]. Bovendien worden in de gegeven gegevensstatus geen bijzondere re-entrantie-eigenschappen of vaste volgordevoorwaarden met betrekking tot andere modulefuncties voorgeschreven [SWS_KeyM_00075].

De synchrone en niet-re-entrante functie KeyM_KH_Start wordt via de header KeyM_Externals.h gedeclareerd [SWS_KeyM_00067]. Wanneer de configuratieparameters KeyMCryptoKeyStartFinalizeFunctionEnabled en KeyMCryptoKeyHandlerStartFinalizeEnabled op TRUE zijn ingesteld, wordt deze direct bij een oproep van KeyM_Start uitgevoerd [SWS_KeyM_00067].

Via de parameter StartType wordt de uitvoeringsmodus van de sleutelbewerking vastgelegd. Middels RequestData en RequestDataLength ontvangt de functie verzoekspecifieke begeleidende gegevens zoals bijvoorbeeld signaturen. De oproeper geeft via de invoer-/uitvoerparameter ResponseDataLength de maximaal in de buffer ResponseData beschikbare bytehoeveelheid door; in geval van succes meldt de functie daarlangs het werkelijk geschreven aantal responsbytes terug [SWS_KeyM_00067].

Als retourwaarde levert de functie een status van het type Std_ReturnType [SWS_KeyM_00067]:

• E_OK: De startbewerking was succesvol. Alleen door deze returnwaarde wisselt de Key Manager naar de actieve toestand, zodat aansluitende sleutelactualisaties (Key Updates) zijn toegestaan.
• E_NOT_OK: De startbewerking is niet geaccepteerd.
• KEYM_E_PARAMETER_MISMATCH: Een doorgegeven parameter komt niet overeen met de verwachte waarde.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Een opgegeven parametergrootte past niet bij de verwachte grootte.

Aangezien KeyM_KH_Start als niet-re-entrant is gedefinieerd, mogen oproepen voor parallelle sleutelbewerkingen niet gelijktijdig plaatsvinden [SWS_KeyM_00067].

Gebruik en aanroepcontext

De functie KeyM_KH_Prepare wordt via het headerbestand KeyM_Externals.h gedeclareerd en dient voor de voorbereiding van een sleutelbeheerbewerking [SWS_KeyM_00068]. Deze wordt direct bij de oproep van KeyM_Prepare gestart, wanneer de beide configuratieparameters KeyMCryptoKeyPrepareFunctionEnabled en KeyMCryptoKeyHandlerPrepareEnabled elk op TRUE zijn ingesteld [SWS_KeyM_00068]. De uitvoering verloopt synchroon en is gespecificeerd als niet-re-entrant [SWS_KeyM_00068].

De gegevensoverdracht vindt plaats via vier parameters [SWS_KeyM_00068]:

• RequestData: Invoergegevens die samen met het verzoek worden doorgegeven [SWS_KeyM_00068].
• RequestDataLength: Lengte van de gegevens in de array RequestData [SWS_KeyM_00068].
• ResponseDataPtr: Pointer naar de buffer voor de door de functie geretourneerde responsgegevens, die ongewijzigd worden doorgegeven aan de oproeper van Key_Prepare [SWS_KeyM_00068].
• ResponseDataLength: Invoer- en uitvoerparameter; geeft bij de oproep het maximaal in de buffer beschikbare aantal bytes door en levert na terugkeer de werkelijk geschreven bytehoeveelheid terug [SWS_KeyM_00068].

Retourwaarden en foutgedrag

De functie levert als resultaat de statuswaarde Std_ReturnType terug [SWS_KeyM_00068]:

• E_OK: De service is geaccepteerd en wordt intern verder verwerkt; resultaten worden via een callback verzonden [SWS_KeyM_00068].
• E_NOT_OK: De service is vanwege een interne fout niet geaccepteerd [SWS_KeyM_00068].
• KEYM_E_PARAMETER_MISMATCH: Een parameter komt niet overeen met de verwachte waarde [SWS_KeyM_00068].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: De grootte van een parameter is niet passend [SWS_KeyM_00068].

Gebruik en delegering

De functie KeyM_KH_Finalize wordt via het headerbestand KeyM_Externals.h gedeclareerd en fungeert als gebruikersspecifieke key-handler [SWS_KeyM_00070]. Wanneer in de configuratie zowel KeyMCryptoKeyStartFinalizeFunctionEnabled als KeyMCryptoKeyHandlerStartFinalizeEnabled op TRUE zijn ingesteld, voert KeyM_Finalize() geen zelfstandige bewerking uit, maar delegeert de verwerking direct aan deze handlerfunctie [SWS_KeyM_00070].

Aanroepcontext en parameters

De oproep van KeyM_KH_Finalize vindt synchroon plaats, maar is geclassificeerd als niet-re-entrant (Non Reentrant) en vereist een beschermde oproepcontext [SWS_KeyM_00070]. De gegevensoverdracht vindt plaats via de volgende parameters:

• RequestData en RequestDataLength: Pointer naar de met het verzoek doorgegeven invoergegevens alsmede de lengte van de data-array [SWS_KeyM_00070].
• ResponseData: Buffer voor de door de functie beschikbaar gestelde uitvoergegevens [SWS_KeyM_00070].
• ResponseDataLength: Een in/out-parameter die bij de oproep de maximaal in de responsbuffer beschikbare bytehoeveelheid voorschrijft en bij terugkeer het werkelijk geschreven aantal bytes bevat [SWS_KeyM_00070].

Retourwaarden en foutafhandeling

Het bewerkingsresultaat wordt via Std_ReturnType geretourneerd [SWS_KeyM_00070]:

• E_OK: De bewerking is geaccepteerd en wordt intern verder verwerkt; de resultaten worden via een callback beschikbaar gesteld [SWS_KeyM_00070]. Interpretatie: Hoewel de functie-interface als synchroon is gedefinieerd, zal de daadwerkelijke afhandeling vermoedelijk op de achtergrond worden voortgezet. Vraag Q-02c4aac040570c03 (open)
• E_NOT_OK: De bewerking is vanwege een interne fout niet geaccepteerd [SWS_KeyM_00070].
• KEYM_E_BUSY: De Key Manager is bezet met andere taken, waardoor de validatie momenteel niet kan worden uitgevoerd [SWS_KeyM_00070].
• KEYM_E_PARAMETER_MISMATCH: Een parameter komt niet overeen met de verwachte waarde [SWS_KeyM_00070].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: De doorgegeven parametergrootte voldoet niet aan de specificaties [SWS_KeyM_00070].

De callbackfunctie KeyM_CryptoKeyUpdateCallbackNotification() stelt de applicatie ervan op de hoogte dat een actualisatie van een cryptografische sleutel is voltooid ([SWS_KeyM_00077]). De functie wordt beschikbaar gesteld via KeyM_Externals.h, is synchroon en re-entrant en heeft geen returnwaarde ([SWS_KeyM_00077]).

Parameter

• Result: Draagt informatie over het resultaat van de actualisatiebewerking over via het type KeyM_ResultType ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataLength: Geeft de lengte van de resulterende gegevens van deze bewerking aan ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataPtr: Pointer naar de gegevens van het resultaat ([SWS_KeyM_00077]).

Interactie en bufferbeheer

De oproep van KeyM_CryptoKeyUpdateCallbackNotification() vindt plaats door KeyM_Update() zodra de key-handler terugkeert en het bewerkingstype KEYM_KH_UPDATE_FINISH oplevert ([SWS_KeyM_00093]). Daarbij worden de resultaatgegevens uit KeyM_KH_Update::ResultDataPtr gekopieerd naar de buffer die bij de oproep van KeyM_Update() is doorgegeven, en de returnwaarde van de key-handler wordt overgenomen ([SWS_KeyM_00093]).

Voor zover KeyM_Update() de verrichting met E_OK heeft geaccepteerd, mag de oproepende functie de buffer ResultDataPtr onder geen beding wijzigen totdat de callbacknotificatie KeyM_CryptoKeyUpdateCallbackNotification() heeft plaatsgevonden ([SWS_KeyM_00156]). Dezelfde bufferpointer wordt in de callback als ResultDataPtr met de daarin gekopieerde bewerkingsresultaten doorgegeven ([SWS_KeyM_00156]).

De callback-functie KeyM_CryptoKeyFinalizeCallbackNotification stelt de applicatie op de hoogte van de voltooiing van een sleutelfinalisatiebewerking [SWS_KeyM_00079]. Deze is gespecificeerd als synchroon en re-entrant, heeft geen retourwaarde en wordt gedeclareerd via het headerbestand KeyM_Externals.h [SWS_KeyM_00079].

De interface geeft bij de aanroep de volgende parameters door aan de applicatie [SWS_KeyM_00079]:

• Result (type KeyM_ResultType): Geeft het resultaat en statusinformatie van de voltooide bewerking door [SWS_KeyM_00079].
• Result Data Length (type uint16): Geeft de lengte aan van de resulterende gegevens van deze bewerking [SWS_KeyM_00079].
• Result Data Ptr (type const uint8*): Pointer naar de buffer met de resultaatgegevens, die eerder aan de servicefunctie ter beschikking is gesteld [SWS_KeyM_00079].

Wat de configuratie betreft, wordt de callback-functie alleen aangeroepen en benodigd wanneer de configuratieparameter KeyMCryptoKeyStartFinalizeFunctionEnabled op TRUE is ingesteld [SWS_KeyM_00079]. Specifieke DET- of DEM-foutmeldingen zijn voor deze callback-functie niet gedefinieerd. Vermoedelijk implementeert de applicatie deze callback om de asynchrone resultaten van een eerder geïnitieerde sleutelfinalisatie te ontvangen. Vraag Q-6d9e4e062b008832 (open)

Gebruik en parameters

De callback-functie KeyM_CryptoKeyVerifyCallbackNotification informeert de applicatie over de voltooiing van een verificatiebewerking voor een cryptografische sleutel door de module KeyM [SWS_KeyM_00081]. Interpretatie: Aangezien het element volgens de specificatie via de header KeyM_Externals.h beschikbaar is en dient voor de notificatie van de applicatie, zal de implementatie vermoedelijk plaatsvinden door de toepassende softwarecomponent, terwijl de aanroep wordt uitgevoerd door de key manager [SWS_KeyM_00081]. Vraag Q-e88e332a7d2cac40 (open)

Voor de aanroep zijn vier zuivere invoerparameters gedefinieerd [SWS_KeyM_00081]:

• Result (KeyM_ResultType): Geeft het resultaat van de voltooide verificatie door [SWS_KeyM_00081].
• KeyId (uint32): Duidt de sleutel-ID aan waarvoor de verificatie is gestart [SWS_KeyM_00081].
• ResultDataLength (uint16): Bevat de lengte van de resulterende resultaatgegevens, indien aanwezig [SWS_KeyM_00081].
• ResultDataPtr (const uint8*): Wijst naar de gegevens van het verificatieresultaat [SWS_KeyM_00081].

Gelijktijdigheid en beperkingen

De functie heeft geen retourwaarde (void) en noch uitgangs-, noch in-/uitgangsparameters [SWS_KeyM_00081]. De aanroep is synchroon en re-entrant uitgevoerd [SWS_KeyM_00081]. Specifieke foutcodes en DET- of DEM-meldingen zijn voor deze callback niet gespecificeerd; status- en foutinformatie worden uitsluitend via de parameter Result aan de applicatie doorgegeven [SWS_KeyM_00081].

Gebruik en semantiek

De callback-functie KeyM_ServiceCertificateCallbackNotification wordt aangeroepen door de certificaat-submodule van de KeyM om de applicatie op de hoogte te stellen van de voltooiing van een certificaatservicebewerking [SWS_KeyM_00147]. De voorafgaande certificaatbewerking verloopt asynchroon en voert bij beëindiging deze callback uit om de resultaten naar de applicatie over te brengen [SWS_KeyM_00149].

Via de functieparameters worden alle relevante resultaatgegevens overgedragen [SWS_KeyM_00147]:

• CertId: Identifier van het certificaat waarvoor de bewerking is geïnitieerd.
• Result: Type KeyM_ResultType met de status resp. het resultaat van de bewerking.
• ResultDataLength: Lengte van de resultaatgegevens, voor zover aanwezig.
• ResultDataPtr: Pointer naar de resultaatgegevens.

De functie zelf heeft geen retourwaarde (void) en vertoont een synchrone uitvoeringssemantiek [SWS_KeyM_00147].

Configuratie en beperkingen

De callback wordt beschikbaar gesteld via de header KeyM_Externals.h, maar is alleen beschikbaar als de configuratieparameter KeyMServiceCertificateFunctionEnabled op TRUE is ingesteld [SWS_KeyM_00147]. De daadwerkelijke naam van de meldingsfunctie kan worden aangepast via de configuratieparameter KeyMServiceCertificateCallbackNotificationFunc [SWS_KeyM_00147].

Gelijktijdigheid en foutafhandeling

Volgens de specificatie is de functie geclassificeerd als re-entrant [SWS_KeyM_00147]. Fout- of successtatussen van de voorafgaande asynchrone bewerking worden gesignaleerd via de overdrachtsparameter Result; specifieke DET- of DEM-meldingen zijn voor deze callback-interface in de payload niet gedefinieerd [SWS_KeyM_00147].

Gebruik

De callbackfunctie KeyM_CertificateVerifyCallbackNotification dient ertoe de applicatie op de hoogte te stellen van de voltooiing van een certificaatverificatie [SWS_KeyM_00073]. De declaratie is beschikbaar via de header KeyM_Externals.h, waarbij de functienaam via de configuratieparameter KeyMCertificateVerifyCallbackNotificationFunc kan worden geconfigureerd [SWS_KeyM_00073].

Bij de oproep worden twee invoerparameters doorgegeven [SWS_KeyM_00073]:

• CertId (type KeyM_CertificateIdType): Identifier van het geverifieerde certificaat [SWS_KeyM_00073].
• Result (type KeyM_CertificateStatusType): Bevat informatie over het resultaat van de verificatiebewerking [SWS_KeyM_00073].

De functie retourneert als statuswaarde van het type Std_ReturnType de waarde E_OK [SWS_KeyM_00073].

Uitvoering en foutafhandeling

De uitvoering van de notificatie is gedefinieerd als synchroon en re-entrant [SWS_KeyM_00073]. Specifieke foutcodes, afwijkende returnwaarden of meldingen aan DET of DEM zijn voor deze callback niet voorzien [SWS_KeyM_00073]. Interpretatie: De applicatiezijde-implementatie zal vermoedelijk thread-safe ontworpen moeten zijn om gelijktijdige oproepen voor verschillende certificaten zonder neveneffecten te verwerken. Vraag Q-6bf5313c425fe1a8 (open)

Gebruik

Het gegevenstype KeyM_CertElementIteratorType is conform [SWS_KeyM_00042] gedefinieerd als structuur (Structure) en wordt beschikbaar gesteld via het headerbestand KeyM.h. Volgens de specificatie dient dit type om te itereren over een reeks elementen van een certificaat ([SWS_KeyM_00042]). Aangezien de concrete inhoud van de gegevensstructuur uitdrukkelijk als implementatiespecifiek is vastgelegd ([SWS_KeyM_00042]), dienen gebruikers het type vermoedelijk te beschouwen als een opake iteratiestatus en niet direct toegang te zoeken tot interne structuurvelden. Vraag Q-81b5deb7dcdf2812 (open)

Hantering en beperkingen

Uit de specificatie vloeien de volgende praktische randvoorwaarden voor het gebruik voort:

• Implementatiespecifieke opbouw: Aangezien de velden van KeyM_CertElementIteratorType fabrikantspecifiek worden geïmplementeerd ([SWS_KeyM_00042]), hangt de interne geheugenlayout af van de betreffende BSW-realisatie.
• Statusbeheer: Interpretatie: Een instantie van de structuur dient vermoedelijk door de oproepende instantie te worden gealloceerd als iteratorcontext en te worden doorgegeven aan de bijbehorende functies voor het traverseren van certificaatelementen, om de voortgang bij de controle of extractie van certificaatvelden te volgen. Vraag Q-5ddb438001abe656 (open)
• Gelijktijdigheid: Vermoedelijk is een iteratorinstantie zonder externe synchronisatie niet gelijktijdig bruikbaar over meerdere taken heen wanneer parallelle toegangen tot hetzelfde certificaat plaatsvinden. Vraag Q-6b4b8b1cdc35f021 (open)

Het enumeratietype KeyM_ServiceCertificateType wordt beschikbaar gesteld via de header Rte_KeyM_Type.h en specificeert de door de key-server aangevraagde certificaatservicebewerking en de aard van de met de functie overgedragen informatie [SWS_KeyM_00039]. De declaratie in het RTE-headerbestand duidt er vermoedelijk op dat het type vooral wordt toegepast bij de gegevensuitwisseling tussen softwarecomponenten en de Key-Manager-module. Vraag Q-37ed693ea3eda646 (open)

De volgende gestandaardiseerde bewerkingscodes zijn gedefinieerd voor het certificaatbeheer [SWS_KeyM_00039]:

• KEYM_SERVICE_CERT_REQUEST_CSR (0x01): De key-server verzoekt de key-client om een certificaat resp. een certificaataanvraag (CSR) te genereren [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_SIGNED_CSR (0x02): De server retourneert een eerder ontvangen, inmiddels door de certificeringsinstantie (CA) ondertekend certificaat [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_ROOT (0x03) en KEYM_SERVICE_CERT_UPDATE_ROOT (0x04): Aanmaken van een nieuw of bijwerken van een bestaand rootcertificaat [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_INTERMEDIATE (0x05) en KEYM_SERVICE_CERT_UPDATE_INTERMEDIATE (0x06): Toevoegen of bijwerken van een tussenliggend certificaat (CA-certificaat) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_CRL (0x07): Beschikbaar stellen of bijwerken van een certificaatintrekkingslijst (CRL) [SWS_KeyM_00039].

Als wezenlijke voorwaarde vereist KEYM_SERVICE_CERT_SET_INTERMEDIATE dat vóór het instellen van een tussenliggend certificaat het bijbehorende rootcertificaat al opgeslagen moet zijn om een succesvolle verificatie te waarborgen [SWS_KeyM_00039]. Voor projectspecifieke uitbreidingen voorziet de specificatie in het gereserveerde waardebereik van 0x80 tot 0x9F [SWS_KeyM_00039].

Het opsommingstype KeyM_CertificateStatusType representeert het resultaat van certificaatcontroles en geeft de actuele verificatie- en verwerkingsstatus van een certificaat in de Key Manager weer [SWS_KeyM_91003]. Het type wordt via de header Rte_KeyM_Type.h beschikbaar gesteld en dient ertoe dat aanroepers de toestand of specifieke foutoorzaken van een certificaatverificatie gedifferentieerd kunnen evalueren [SWS_KeyM_91003].

De enumeratiewaarden dekken zowel reguliere tussen- en succestoestanden als nauwkeurige foutbeelden af [SWS_KeyM_91003]:

• KEYM_CERTIFICATE_VALID (0x00): het certificaat is succesvol geparseerd en geverifieerd [SWS_KeyM_91003].
• KEYM_CERTIFICATE_INVALID (0x01): het certificaat is ongeldig vanwege een niet nader gespecificeerde fout [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_PARSED (0x02): het certificaat is tot nu toe nog niet geparseerd [SWS_KeyM_91003].
• KEYM_CERTIFICATE_PARSED_NOT_VALIDATED (0x03): het certificaat is geparseerd, maar nog niet gevalideerd [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_AVAILABLE (0x04): er is geen certificaat ingesteld [SWS_KeyM_91003].
• Foutspecifieke controleresultaten: mislukte geldigheidsduur (KEYM_E_CERTIFICATE_VALIDITY_PERIOD_FAIL, 0x05), foutieve handtekening (KEYM_E_CERTIFICATE_SIGNATURE_FAIL, 0x06), ongeldige vertrouwensketen (KEYM_E_CERTIFICATE_INVALID_CHAIN_OF_TRUST, 0x07), ongeldig type (KEYM_E_CERTIFICATE_INVALID_TYPE, 0x08), foutief formaat (KEYM_E_CERTIFICATE_INVALID_FORMAT, 0x09), ongeldige inhoud (KEYM_E_CERTIFICATE_INVALID_CONTENT, 0x0A) en intrekking resp. ongeldig geldigheidsbereik (KEYM_E_CERTIFICATE_REVOKED, 0x0B) [SWS_KeyM_91003].

Aanroepers dienen de status vóór het gebruik van cryptografische sleutels te controleren; bewerkingen mogen typisch alleen dan op een certificaat voortbouwen wanneer de status expliciet KEYM_CERTIFICATE_VALID aangeeft. Aangezien het type via Rte_KeyM_Type.h wordt gedeclareerd, zal het vermoedelijk hoofdzakelijk worden gebruikt in gestandaardiseerde service-interfaces en poorten voor interactie tussen KeyM en applicatie-SWC's. Vraag Q-f3ca10ee673798df (open)

Gebruik en structuur

Het gegevenstype KeyM_CertificateElementType is gespecificeerd als byte-array met het elementtype uint8 en dient volgens de specificatie als een voldoende groot geheugengebied voor het opslaan van gegevens van een certificaatelement [SWS_KeyM_91004]. De beschikbaarstelling en declaratie van het gegevenstype vindt voor de module KeyM plaats via het headerbestand Rte_KeyM_Type.h [SWS_KeyM_91004].

Configuratie en variantvorming

De vorm van het gegevenstype is onderhevig aan een configuratieafhankelijke naams- en groottevariatie, die wordt afgeleid van de geconfigureerde parameters van de module [SWS_KeyM_91004]:

• Naampatroon: De concrete typenaam wordt elementspecifiek gegenereerd volgens het schema KeyM_CertificateElementType_{KeyMCertificate}_{KeyMCertificateElement}, waarbij de tijdelijke aanduidingen overeenkomen met de geconfigureerde korte namen SHORT-NAME van de respectieve instanties van certificaat en certificaatelement [SWS_KeyM_91004].
• Array-grootte: Het aantal uint8-elementen wordt bepaald door de configuratieparameter KeyMCertificateElementMaxLength, zodat de array voldoende opslagruimte biedt voor de ruwe gegevens van het betreffende element [SWS_KeyM_91004].

Beperkingen en aannames

Aangezien de definitie in Rte_KeyM_Type.h beschikbaar wordt gesteld, zal het type vermoedelijk primair worden gebruikt als een gestandaardiseerde buffer op de interfaces naar softwarecomponenten voor de uitwisseling van certificaatinhoud [SWS_KeyM_91004]. Vraag Q-994f8ac6772de3c1 (open) De maximaal te verwerken gegevenslengte blijft daarbij statisch gebonden aan de tijdens configuratietijd gedefinieerde maximale lengte [SWS_KeyM_91004].

Gebruik en typedefinitie

Het gegevenstype KeyM_CryptoKeyDataType is gedefinieerd als pointertype naar uint8* en dient als byte-pointer voor invoer- of uitvoergegevens binnen de module KeyM [SWS_KeyM_91012]. De typedefinitie wordt via het headerbestand Rte_KeyM_Type.h beschikbaar gesteld [SWS_KeyM_91012].

Beperkingen en geheugenbeheer

Bij het gebruik van KeyM_CryptoKeyDataType als pointer naar bytebuffers moeten specifieke randvoorwaarden in acht worden genomen:

• Interpretatie: Aangezien het type als eenvoudige byte-pointer (uint8*) is gespecificeerd [SWS_KeyM_91012], is vermoedelijk de respectieve oproeper verantwoordelijk voor de allocatie, dimensionering en geldigheid van het gerefereerde geheugen. Vraag Q-07c167f400cbfb9c (open)
• Interpretatie: Bij de overdracht als uitvoerbuffer moet er vermoedelijk voor worden gezorgd dat het gerefereerde geheugengebied groot genoeg is voor de op te nemen sleutel- resp. cryptogegevens om buffer overflows te voorkomen. Vraag (open)
• Interpretatie: Voor gelijktijdige toegang tot de gerefereerde buffer zullen vermoedelijk aanvullende synchronisatiemaatregelen door de aanroepende software nodig zijn, aangezien het type zelf geen synchronisatiemechanisme biedt. Vraag (open)

Integratie

Oproepers die cryptografische sleutel- of certificaatgegevens overdragen aan of ontvangen van KeyM-interfaces, voegen Rte_KeyM_Type.h in om toegang te krijgen tot de getypeerde pointerdefinitie van KeyM_CryptoKeyDataType [SWS_KeyM_91012].

Het enumeratietype KeyM_ResultType specificeert het resultaat van asynchrone functies van de module KeyM voor sleutel- en certificaatbeheer [SWS_KeyM_91008]. Het type wordt via het headerbestand Rte_KeyM_Type.h bereitgesteld en dient voor de terugmelding over de uitkomst van een opgevraagde asynchrone werkopdracht [SWS_KeyM_91008].

Het waardebereik omvat gestandaardiseerde status- en foutcodes voor een gedifferentieerde evaluatie door aanroepers [SWS_KeyM_91008]:

• KEYM_RT_OK (0x00): De sleutelbeheerbewerking is succesvol voltooid [SWS_KeyM_91008].
• KEYM_RT_NOT_OK (0x01): Tijdens de sleutelbeheerbewerking is een algemene fout opgetreden [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_INVALID (0x02): De gereferentieerde sleutel of het certificaat is ongeldig en kan niet voor de bewerking worden gebruikt [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_WRITE_FAIL (0x03): Het schrijven van de sleutel of het certificaat naar het beoogde doelgeheugen is mislukt [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_UPDATE_FAIL (0x04): Algemene fout bij het bijwerken van een sleutel of certificaat, die niet door een specifiekere code kon worden gepreciseerd [SWS_KeyM_91008].
• KEYM_RT_CERT_INVALID_CHAIN_OF_TRUST (0x05): De certificaatverificatie is mislukt vanwege een ongeldige vertrouwensketen [SWS_KeyM_91008].

Aanroepers van asynchrone KeyM-functies moeten dit retourtype evalueren om bij fouten gericht te kunnen reageren op ongeldige vertrouwensketens, geheugentoegangsfouten of onjuist sleutelmateriaal [SWS_KeyM_91008].

De structuur KeyM_CertDataType wordt in de module KeyM gebruikt voor de overdracht en uitwisseling van certificaatgegevens via interfacefuncties [SWS_KeyM_00041]. De typedefinitie is beschikbaar via het headerbestand KeyM.h [SWS_KeyM_00041].

De structuur bundelt twee essentiële elementen [SWS_KeyM_00041]:

• certDataLength: Element van het type uint32 dat de lengte van de certificaatgegevens aangeeft [SWS_KeyM_00041].
• certData: Element van het type VoidPtr dat als pointer direct verwijst naar de certificaatgegevens in een lokaal gegevensbereik van de oproepende instantie [SWS_KeyM_00041].

Aangezien certData verwijst naar geheugenbereiken in de lokale context van de oproepende instantie [SWS_KeyM_00041], berust het bufferbeheer bij de oproepende instantie. Interpretatie: De oproepende instantie dient vermoedelijk te waarborgen dat het gereferentieerde geheugen geldig blijft gedurende de gehele uitvoeringsduur van de betreffende interfacefunctie en ten minste het in certDataLength aangegeven aantal bytes omvat. Vraag Q-7da9d5ed0975ddbd (open) Bovendien mag worden vermoed dat bij een lengte groter dan nul een geldige pointer ongelijk aan NULL moet worden doorgegeven om foutieve geheugentoegangen binnen de interfacefunctie te voorkomen.