Crypto Driver (Crypto)

De functie Crypto_Init dient voor de initialisatie van de Crypto Driver conform [SWS_Crypto_91000]. De interface is in de header Crypto.h gedeclareerd en heeft service-ID 0x00 [SWS_Crypto_91000].

Voor de aanroep en de interfaceparameters zijn de volgende eigenschappen gespecificeerd:

• Configuratiepointer: Via de invoerparameter configPtr van het type const Crypto_ConfigType* wordt een pointer naar de geselecteerde configuratiestructuur doorgegeven [SWS_Crypto_91000].
• Retourwaarde: De functie heeft geen retourwaarde (void); er bestaan noch in-/uitvoerparameters noch afzonderlijke uitvoerparameters [SWS_Crypto_91000].
• Uitvoeringsgedrag: De initialisatieroutine wordt synchroon uitgevoerd (Synchronous) [SWS_Crypto_91000].
• Re-entrantie: De functie is gedefinieerd als niet-re-entrant (Non Reentrant) [SWS_Crypto_91000]. Parallelle of overlappende aanroepen zijn niet toegestaan.

Vanwege de classificatie als niet-re-entrant en aangezien de specificatie geen specifieke foutcodes retourneert, vindt de aanroep vermoedelijk centraal plaats tijdens de opstartfase van de ECU vóór alle andere drivertoegangen (interpretatie). Vraag Q-008bb5a45b823891 (open) De aanroeper is er vermoedelijk bovendien voor verantwoordelijk dat de gerefereerde configuratiestructuur in het geheugen permanent geldig blijft (interpretatie). Vraag Q-6271a86fad440121 (open)

De functie Crypto_ProcessJob voert de in parameter job geconfigureerde cryptografische primitieve uit op het door objectId gerefereerde Crypto Driver Object [SWS_Crypto_91003]. De aanroep is re-entrant en werkt afhankelijk van de jobconfiguratie synchroon of asynchroon [SWS_Crypto_91003]. Via de pointer naar Crypto_JobType worden zowel configuratiegegevens voor de primitieve als buffers voor de resultaatgegevens doorgegeven [SWS_Crypto_91003].

Vóór de daadwerkelijke uitvoering van een job controleert de driver de sleutel-identifiers op geldigheid: vallen job->cryptoKeyId of eventueel job->targetCryptoKeyId buiten het toegestane bereik, dan meldt de functie de fout CRYPTO_E_PARAM_HANDLE aan de DET en retourneert E_NOT_OK [SWS_Crypto_00217]. Dit geldt ook voor de service CRYPTO_KEYDERIVE (job->jobPrimitiveInfo->primitiveInfo->service), voor zover job->targetCryptoKeyId ongeldig is [SWS_Crypto_00202].

Naast E_OK en E_NOT_OK signaleren specifieke foutcodes het mislukken van de aanvraag [SWS_Crypto_91003]:

• CRYPTO_E_BUSY, wanneer het driver-object bezet is of de wachtrij ervan vol is [SWS_Crypto_91003],
• sleutelgerelateerde fouten zoals CRYPTO_E_KEY_NOT_VALID, CRYPTO_E_KEY_SIZE_MISMATCH, CRYPTO_E_KEY_READ_FAIL, CRYPTO_E_KEY_WRITE_FAIL, CRYPTO_E_KEY_NOT_AVAILABLE of CRYPTO_E_KEY_EMPTY [SWS_Crypto_91003],
• CRYPTO_E_JOB_CANCELED bij het afbreken van een synchrone job [SWS_Crypto_91003] evenals
• CRYPTO_E_ENTROPY_EXHAUSTED bij onvoldoende entropie van een random number generator; hierbij meldt de functie tevens de runtimefout CRYPTO_E_RE_ENTROPY_EXHAUSTED [SWS_Crypto_00141], [SWS_Crypto_91003].

Gebruik

De synchrone functie Crypto_CancelJob verwijdert een meegegeven job uit de wachtrij en breekt de verwerking ervan zo mogelijk af [SWS_Crypto_00122]. Bij de aanroep worden de identifier van het Crypto Driver Object (objectId) en een pointer naar de jobconfiguratie (job) doorgegeven [SWS_Crypto_00122].

De retourwaarden signaleren het resultaat van de afbreekpoging:

• E_OK: Het verzoek was succesvol en de job is verwijderd [SWS_Crypto_00122]. Als er geen fout in de driver is opgetreden en de job momenteel niet wordt verwerkt, retourneert de service eveneens E_OK zonder verdere acties [SWS_Crypto_00214].
• E_NOT_OK: het verzoek is mislukt, omdat de job niet kon worden verwijderd [SWS_Crypto_00122].
• CRYPTO_E_JOB_CANCELED: De job is afgebroken, maar wordt verder uitgevoerd; er worden geen resultaten aan de applicatie teruggemeld [SWS_Crypto_00122]. Dit geldt wanneer de driver foutloos werkt, maar de job (bijvoorbeeld wegens hardwarebeperkingen) niet kan afbreken [SWS_Crypto_00183].

Gelijktijdigheid en beperkingen

De interface is re-entrant voor verschillende instanties, maar mag niet gelijktijdig voor hetzelfde Crypto Driver Object worden aangeroepen [SWS_Crypto_00122].

De synchrone functie Crypto_KeyElementSet dient ertoe de ruwe gegevens van een bepaald sleutelelement voor een via cryptoKeyId geïdentificeerde sleutel in de crypto-driver in te stellen [SWS_Crypto_91004].

Parameters en retourwaarden

Via keyElementId wordt het doelsleutelelement geadresseerd, terwijl keyPtr naar de databuffer en keyLength naar de bytegrootte daarvan verwijst [SWS_Crypto_91004]. Bij een succesvolle toewijzing retourneert de interface E_OK [SWS_Crypto_91004].

Foutafhandeling

Treedt er bij de verwerking een fout op, dan levert de functie specifieke retourwaarden [SWS_Crypto_91004]:

• CRYPTO_E_BUSY: Het bijbehorende Crypto Driver Object is bezet.
• CRYPTO_E_KEY_WRITE_FAIL: De schrijftoegang tot het sleutelelement is geweigerd.
• CRYPTO_E_KEY_NOT_AVAILABLE: Het opgevraagde sleutelelement of de sleutel is niet beschikbaar.
• CRYPTO_E_KEY_SIZE_MISMATCH: De doorgegeven datalengte komt niet overeen met de grootte van het sleutelelement.
• E_NOT_OK: De aanvraag is om overige redenen mislukt.

Concurrency

De functie is gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_Crypto_91004]. Interpretatie: aanroepers zijn er vermoedelijk verantwoordelijk voor parallelle aanroepen onderling te synchroniseren om inconsistenties van gegevens in de driver te voorkomen. Vraag Q-d7ef7a774052a212 (open)

De synchrone functie Crypto_KeySetValid dient ertoe de toestand van een via de identifier cryptoKeyId gespecificeerde sleutel op geldig in te stellen ([SWS_Crypto_91014]). De interface is beschikbaar via het headerbestand Crypto.h en heeft service-ID 0x05 ([SWS_Crypto_91014]).

Bij gebruik zijn de volgende parameters en retourwaarden gedefinieerd ([SWS_Crypto_91014]):

• Invoerparameters: Via cryptoKeyId (type uint32) wordt de identifier van de sleutel meegegeven waarvan de toestand op geldig moet worden ingesteld ([SWS_Crypto_91014]). Aanvullende invoer- of uitvoerparameters ontbreken ([SWS_Crypto_91014]).
• Retourwaarde: Een statuscode van het type Std_ReturnType informeert over het resultaat van het verzoek ([SWS_Crypto_91014]):
  • E_OK: het verzoek was succesvol ([SWS_Crypto_91014]).
  • E_NOT_OK: het verzoek is mislukt ([SWS_Crypto_91014]).
  • CRYPTO_E_BUSY: De uitvoering is mislukt omdat het verantwoordelijke Crypto Driver Object bezet is ([SWS_Crypto_91014]).

Wat betreft concurrency is de functie gespecificeerd als niet re-entrant („Non Reentrant”) ([SWS_Crypto_91014]). Interpretatie: Aanroepers moeten parallelle aanroepen over taken heen vermoedelijk extern coördineren om conflicten te vermijden, en moeten bij ontvangst van CRYPTO_E_BUSY voorzien in een herhaling van de aanroep op een later tijdstip. Vraag Q-32d775a9e61e5731 (open)

Gebruik en semantiek

De synchrone functie Crypto_KeySetInvalid zet de status van een door cryptoKeyId geïdentificeerde sleutel op ongeldig [SWS_Crypto_91020]. De functie is gedefinieerd in het headerbestand Crypto.h en wordt via de service-ID 0x15 aangesproken [SWS_Crypto_91020]. Als enige overdrachtsparameter dient de invoerwaarde cryptoKeyId (type uint32), die de unieke identifier van de doelsleutel bevat; in-/uitvoer- en uitvoerparameters zijn niet aanwezig [SWS_Crypto_91020].

Foutafhandeling en retourwaarden

Het resultaat van de functie-uitvoering wordt gesignaleerd via de retourwaarde van het type Std_ReturnType [SWS_Crypto_91020]:

• E_OK: Het verzoek was succesvol en de sleutelstatus is op ongeldig gezet [SWS_Crypto_91020].
• E_NOT_OK: Het uitvoeren van het verzoek is mislukt [SWS_Crypto_91020].
• CRYPTO_E_BUSY: Het verzoek is mislukt, omdat het verantwoordelijke crypto-driverobject (Crypto Driver Object) momenteel bezet is [SWS_Crypto_91020].

Gelijktijdigheid en beperkingen

De interface is gespecificeerd als niet-re-entrant (Non Reentrant) [SWS_Crypto_91020]. Een gelijktijdige of onderbrekende aanroep is daarom niet toegestaan. Omdat de functie synchroon wordt uitgevoerd, keert deze pas na voltooiing van de statuswijziging respectievelijk na vaststelling van de fout terug naar de aanroeper [SWS_Crypto_91020].

De synchrone en re-entrante functie Crypto_KeyElementGet dient ertoe een door keyElementId geïdentificeerd sleutelelement uit de sleutel cryptoKeyId uit te lezen en in het geheugengebied resultPtr op te slaan [SWS_Crypto_91006]. De interface wordt via de header Crypto.h ter beschikking gesteld en heeft service-ID 0x06 [SWS_Crypto_91006]. Bij de aanroep geeft de aanroeper via de in-outparameter resultLengthPtr de buffergrootte door of, bij geconfigureerde deeltoegang, de gewenste leesgrootte; na afronding van de uitvoering slaat de driver daar de daadwerkelijk gekopieerde hoeveelheid gegevens op [SWS_Crypto_91006].

Bij succes retourneert de functie E_OK [SWS_Crypto_91006]. Mislukt de bewerking, dan signaleert deze dit via specifieke foutcodes: CRYPTO_E_BUSY bij een bezet crypto-driverobject, CRYPTO_E_KEY_NOT_AVAILABLE indien het sleutelelement niet beschikbaar is, CRYPTO_E_KEY_READ_FAIL bij geweigerde leestoegang, CRYPTO_E_KEY_EMPTY bij een ongeïnitialiseerd bronelement evenals generiek E_NOT_OK [SWS_Crypto_91006].

Hoewel de interface als re-entrant is gespecificeerd, wijst de specificatie erop dat bij directe mapping van het sleutelelement in het flashgeheugen merkbare latenties tijdens de synchrone uitvoering kunnen optreden [SWS_Crypto_91006]. Interpretatie: vanwege deze potentiële vertragingen is de aanroep vermoedelijk primair in de taakcontext en niet binnen tijdkritische interrupt-service-routines doelmatig. Vraag Q-ff4e2843b9aad46d (open)

De synchrone functie Crypto_KeyGetStatus dient voor het opvragen van de actuele toestand van een specifieke sleutel binnen de crypto-driver [SWS_Crypto_91019]. Ze wordt beschikbaar gesteld via de header Crypto.h en heeft de service-ID 0x14 [SWS_Crypto_91019].

Gebruik en parameters

De aanroep verloopt synchroon en verwacht twee parameters [SWS_Crypto_91019]:

• cryptoKeyId: De identifier van de sleutel waarvan de status moet worden bepaald.
• keyStatusPtr: Pointer naar het geheugengebied van het type Crypto_KeyStatusType waarnaar de toestand wordt geretourneerd.

Als retourwaarde levert de interface Std_ReturnType op. Bij een succesvolle uitvoering wordt E_OK gemeld, terwijl in het geval van een fout E_NOT_OK wordt geretourneerd [SWS_Crypto_91019].

Gelijktijdigheid en beperkingen

De functie is gedeclareerd als niet-re-entrant (Non Reentrant) [SWS_Crypto_91019]. Aanroepers moeten er daarom voor zorgen dat gelijktijdige aanroepen door bovenliggende synchronisatiemechanismen worden vermeden. Specifieke DET-foutmeldingen worden niet vermeld; vermoedelijk leidt een foutieve aanroep zoals een ongeldige pointer of een ongeldige ID direct tot het retourneren van E_NOT_OK [SWS_Crypto_91019]. Vraag Q-5703fab02905e91a (open)

De synchrone functie Crypto_KeyElementCopy dient voor het kopiëren van een sleutelelement naar een ander sleutelelement binnen dezelfde crypto-driver [SWS_Crypto_00148]. Meegegeven worden de identifiers van de bronsleutel (cryptoKeyId) en het bronsleutelelement (keyElementId) evenals van de doelsleutel (targetCryptoKeyId) en het doelsleutelelement (targetKeyElementId) [SWS_Crypto_00148].

Wat betreft het tijdsgedrag dient men er rekening mee te houden dat er bij rechtstreeks in het flashgeheugen gemapte sleutelelementen door de synchrone uitvoering grotere vertragingen bij de functieaanroep kunnen optreden [SWS_Crypto_00148]. Met het runtimegedrag moet daarom met name in tijdkritische contexten rekening worden gehouden.

De functie is ontworpen als re-entrant, maar expliciet niet voor dezelfde cryptoKeyId [SWS_Crypto_00148]. Gelijktijdige aanroepen met een identieke bronsleutel moeten daarom door de aanroeper worden gesynchroniseerd of uitgesloten.

Bij succes retourneert de functie E_OK [SWS_Crypto_00148]. Bij fouten signaleert de retourwaarde de specifieke oorzaak [SWS_Crypto_00148]:

• CRYPTO_E_BUSY: Het crypto-driverobject is bezet [SWS_Crypto_00148].
• CRYPTO_E_KEY_NOT_AVAILABLE: Het opgevraagde sleutelelement van minstens één sleutel is niet beschikbaar [SWS_Crypto_00148].
• CRYPTO_E_KEY_READ_FAIL of CRYPTO_E_KEY_WRITE_FAIL: Het uitlezen van het bron- resp. schrijven van het doelelement is niet toegestaan [SWS_Crypto_00148].
• CRYPTO_E_KEY_SIZE_MISMATCH: De groottes van de sleutelelementen zijn niet compatibel met elkaar [SWS_Crypto_00148].
• CRYPTO_E_KEY_EMPTY: Het bronsleutelelement is niet geïnitialiseerd [SWS_Crypto_00148].
• E_NOT_OK: Het verzoek is algemeen mislukt [SWS_Crypto_00148].

De synchrone functie Crypto_KeyElementCopyPartial dient voor het gedeeltelijk kopiëren van data van een bronsleutelelement naar een doelsleutelelement binnen dezelfde crypto-driver [SWS_Crypto_91015]. Via de parameters keyElementSourceOffset en keyElementCopyLength wordt het te kopiëren fragment van het bronelement (cryptoKeyId, keyElementId) vastgelegd, terwijl keyElementTargetOffset de startpositie in het doelelement (targetCryptoKeyId, targetKeyElementId) bepaalt. Bij een foutloze verificatie voert de driver de kopieerbewerking synchroon uit en retourneert E_OK [SWS_Crypto_00209].

Voorafgaand aan de uitvoering valideert de driver de buffer- en driverstatussen:

• Als de crypto-driver niet is geïnitialiseerd en ontwikkelingsfoutdetectie is geactiveerd, meldt de functie CRYPTO_E_UNINIT aan de DET en retourneert E_NOT_OK [SWS_Crypto_00205].
• Als de totale lengte van het bronsleutelelement kleiner is dan keyElementSourceOffset + keyElementCopyLength, mislukt de aanroep met CRYPTO_E_KEY_SIZE_MISMATCH [SWS_Crypto_00207].
• Biedt de maximale buffer van het doelsleutelelement minder ruimte dan keyElementTargetOffset + keyElementCopyLength, dan wordt eveneens CRYPTO_E_KEY_SIZE_MISMATCH gemeld [SWS_Crypto_00208].
• Andere gespecificeerde foutwaarden zijn onder meer CRYPTO_E_BUSY (driver-object bezet), CRYPTO_E_KEY_EMPTY (ongeïnitialiseerd bronelement), CRYPTO_E_KEY_NOT_AVAILABLE evenals lees- of schrijftoegangsfouten (CRYPTO_E_KEY_READ_FAIL, CRYPTO_E_KEY_WRITE_FAIL) [SWS_Crypto_91015].

De functie is re-entrant, maar mag niet gelijktijdig voor dezelfde sleutel-ID cryptoKeyId worden aangeroepen [SWS_Crypto_91015]. Als een sleutelelement direct in het flashgeheugen is opgeslagen, kan de synchrone uitvoering tot merkbare vertragingen leiden [SWS_Crypto_91015].

Gebruik

De synchrone functie Crypto_KeyCopy kopieert een sleutel inclusief al zijn sleutelelementen naar een doelsleutel binnen dezelfde crypto-driver [SWS_Crypto_00155]. De toewijzing vindt plaats via de invoerparameters cryptoKeyId voor de bronsleutel en targetCryptoKeyId voor de doelsleutel [SWS_Crypto_00155]. Een succesvolle kopieerbewerking wordt bevestigd met E_OK [SWS_Crypto_00155].

Concurrency en runtimegedrag

De interface is ontworpen als re-entrant, maar mag niet gelijktijdig voor dezelfde cryptoKeyId worden uitgevoerd [SWS_Crypto_00155]. Aangezien de uitvoering synchroon verloopt, kunnen er bij sleutelelementen die direct in het flashgeheugen zijn opgeslagen, merkbare tijdsvertragingen tijdens de aanroep optreden [SWS_Crypto_00155].

Foutafhandeling

In geval van een fout levert de functie specifieke retourwaarden van het type Std_ReturnType [SWS_Crypto_00155]:

• CRYPTO_E_BUSY: Het bijbehorende Crypto Driver Object is bezet [SWS_Crypto_00155].
• CRYPTO_E_KEY_NOT_AVAILABLE: Ten minste één van de opgevraagde sleutels is niet beschikbaar [SWS_Crypto_00155].
• CRYPTO_E_KEY_READ_FAIL: Het uitlezen van het bronsleutelelement is niet toegestaan [SWS_Crypto_00155].
• CRYPTO_E_KEY_WRITE_FAIL: Het beschrijven van het doelsleutelelement is niet toegestaan [SWS_Crypto_00155].
• CRYPTO_E_KEY_SIZE_MISMATCH: De groottes van de sleutelelementen zijn niet onderling compatibel [SWS_Crypto_00155].
• CRYPTO_E_KEY_EMPTY: Het sleutelelement van de bronsleutel is niet geïnitialiseerd [SWS_Crypto_00155].
• E_NOT_OK: Het uitvoeren van het verzoek is mislukt [SWS_Crypto_00155].

De synchrone functie Crypto_KeyElementIdsGet dient ertoe informatie op te vragen over welke sleutelelementen in een gegeven sleutel beschikbaar zijn [SWS_Crypto_00160]. Via de invoerparameter cryptoKeyId wordt de identifier van de sleutel doorgegeven waarvan de beschikbare element-ID’s moeten worden geëxporteerd [SWS_Crypto_00160]. De vastgestelde identifiers worden opgeslagen in de array waarnaar door de pointer keyElementIdsPtr wordt gerefereerd [SWS_Crypto_00160].

Het beheer van de buffergrootte vindt plaats via de in- en uitgangsparameter keyElementIdsLengthPtr: bij de aanroep moet deze parameter de beschikbaar gestelde grootte van de buffer keyElementIdsPtr bevatten [SWS_Crypto_00160]. Na beëindiging van de bewerking wordt daarin het werkelijke aantal aanwezige sleutelelementen opgeslagen [SWS_Crypto_00160].

Als retourwaarde levert de service E_OK bij een succesvolle bevraging of E_NOT_OK indien het verzoek is mislukt [SWS_Crypto_00160]. Als het verantwoordelijke crypto-driverobject op het moment van de aanroep bezig is, wordt de foutcode CRYPTO_E_BUSY geretourneerd [SWS_Crypto_00160].

Wat betreft concurrency is de functie re-entrant, maar deze mag niet gelijktijdig voor dezelfde cryptoKeyId worden aangeroepen [SWS_Crypto_00160]. De declaratie is via de header Crypto.h beschikbaar [SWS_Crypto_00160].

De synchrone functie Crypto_RandomSeed (service-ID 0x0d) dient conform [SWS_Crypto_91013] voor het genereren en actualiseren van de interne seed-status van een sleutel met behulp van een beschikbaar gestelde entropiebron. De functiedeclaratie is opgenomen in het headerbestand Crypto.h.

Gebruik en aanroepparameters

Naast de initiële generatie kan de functie volgens [SWS_Crypto_91013] ook worden gebruikt om de seed-status met nieuwe entropie te actualiseren. De synchrone aanroep vereist daarbij drie invoerparameters:

• cryptoKeyId: Geeft de identifier door van de sleutel waarvoor een nieuwe seed moet worden gegenereerd.
• seedPtr: Bevat een pointer naar het geheugengebied met de gegevens voor het voeden van de seed.
• seedLength: Definieert de lengte van de doorgegeven seed-gegevens in bytes.

Retourwaarden en foutafhandeling

Als retourwaarde meldt Crypto_RandomSeed een status van het type Std_ReturnType volgens [SWS_Crypto_91013]:

• E_OK: Het verzoek is met succes uitgevoerd.
• E_NOT_OK: Het verzoek is mislukt.
• CRYPTO_E_KEY_NOT_VALID: De uitvoering mislukt omdat de sleutelstatus van de door cryptoKeyId geïdentificeerde sleutel zich in de status “invalid” bevindt.

Gelijktijdigheid en beperkingen

Conform [SWS_Crypto_91013] is de functie gespecificeerd als re-entrant, echter uitdrukkelijk niet voor dezelfde cryptoKeyId. Parallelle aanroepen voor dezelfde sleutel moeten daarom aan de aanroeperszijde worden voorkomen.

Gebruik

De via het headerbestand Crypto.h ter beschikking gestelde functie Crypto_KeyGenerate genereert nieuw sleutelmateriaal en actualiseert de sleutel die via de identifier cryptoKeyId wordt geadresseerd [SWS_Crypto_91007]. De functie werkt volledig synchroon en is gedefinieerd onder de service-ID 0x07 [SWS_Crypto_91007]. Andere parameters bestaan er naast de sleutel-identifier niet [SWS_Crypto_91007].

Gelijktijdigheid en beperkingen

Met betrekking tot concurrency is Crypto_KeyGenerate gespecificeerd als re-entrant, echter uitdrukkelijk met de beperking dat dit niet geldt voor dezelfde cryptoKeyId [SWS_Crypto_91007]. Worden er meerdere verzoeken voor dezelfde sleutel ingediend, dan moeten deze aan de zijde van de aanroeper worden gesynchroniseerd om driverconflicten te voorkomen.

Retourwaarden en foutafhandeling

Via de retourwaarde van het basistype Std_ReturnType ontvangt de aanroeper gedetailleerde feedback over succes of specifieke foutoorzaken van de bewerking [SWS_Crypto_91007]:

• E_OK: De sleutelgeneratie is succesvol uitgevoerd [SWS_Crypto_91007].
• CRYPTO_E_BUSY: Het verzoek is mislukt, omdat het verantwoordelijke Crypto Driver Object momenteel bezet is [SWS_Crypto_91007].
• CRYPTO_E_KEY_EMPTY: De generatie is mislukt, omdat een vereist bronsleutelelement niet geïnitialiseerd is [SWS_Crypto_91007].
• CRYPTO_E_KEY_NOT_VALID: De bewerking is mislukt, omdat de sleutelstatus van de door cryptoKeyId gerefereerde sleutel als ongeldig is gemarkeerd [SWS_Crypto_91007].
• E_NOT_OK: Het verzoek tot sleutelgeneratie is om overige redenen mislukt [SWS_Crypto_91007].

De synchrone functie Crypto_KeyDerive leidt uit de sleutelelementen van een bronsleutel (cryptoKeyId) een nieuwe cryptografische sleutel af en slaat deze op in het sleutelelement met ID 1 van de doelsleutel (targetCryptoKeyId) [SWS_Crypto_91008]. De bronsleutel moet de vereiste sleutelelementen voor wachtwoord en salt bevatten; het aantal iteraties wordt via het sleutelelement CRYPTO_KE_KEYDERIVATION_ITERATIONS opgegeven [SWS_Crypto_91008].

Aanroep en gelijktijdigheid

De interface is re-entrant, maar mag niet gelijktijdig voor dezelfde cryptoKeyId worden aangeroepen [SWS_Crypto_91008]. Aanroepers moeten er daarom voor zorgen dat parallelle afleidingsprocessen op verschillende bronsleutels opereren.

Retourwaarden en foutafhandeling

De functie signaleert het resultaat via gedefinieerde retourwaarden van het type Std_ReturnType [SWS_Crypto_91008]:

• E_OK: Sleutelafleiding succesvol uitgevoerd.
• E_NOT_OK: Afleiding mislukt. Ligt de parameter targetCryptoKeyId buiten het geldige bereik, dan meldt de functie bij geactiveerde ontwikkelingsdetectie bovendien CRYPTO_E_PARAM_HANDLE aan de DET [SWS_Crypto_00180].
• CRYPTO_E_BUSY: het verantwoordelijke Crypto Driver Object is bezet [SWS_Crypto_91008].
• CRYPTO_E_KEY_EMPTY: Een benodigd bronsleutelelement is niet geïnitialiseerd [SWS_Crypto_91008].
• CRYPTO_E_KEY_NOT_VALID: De toestand van de door cryptoKeyId gerefereerde sleutel is ongeldig [SWS_Crypto_91008].

Gebruik

De synchrone functie Crypto_KeyExchangeCalcPubVal berekent de publieke waarde voor een sleuteluitwisselingsprotocol en slaat deze op op de opslaglocatie van publicValuePtr ([SWS_Crypto_91009]). De aanroeper geeft via cryptoKeyId de identifier door van de sleutel die voor het protocol moet worden gebruikt. Via de in- en uitgangsparameter publicValueLengthPtr moet bij de aanroep de buffergrootte van het ter beschikking gestelde geheugen worden doorgegeven; na afronding van de uitvoering wordt daar de daadwerkelijke lengte van de berekende publieke waarde opgeslagen ([SWS_Crypto_91009]).

Foutafhandeling en retourwaarden

De functie retourneert E_OK bij een succesvolle uitvoering. Treedt er een fout op, dan wordt E_NOT_OK of een specifieke foutcode geretourneerd ([SWS_Crypto_91009]):

• CRYPTO_E_BUSY: Het verzoek mislukt, omdat het Crypto Driver Object bezet is.
• CRYPTO_E_KEY_EMPTY: Het verzoek mislukt, omdat het bron-sleutelelement niet geïnitialiseerd is.
• CRYPTO_E_KEY_NOT_VALID: Het verzoek mislukt, omdat de status van de via cryptoKeyId gerefereerde sleutel ongeldig is.

Gelijktijdigheid en systeemintegratie

Volgens [SWS_Crypto_91009] is de functie re-entrant, maar niet voor dezelfde cryptoKeyId. Wanneer de crypto-driver voor interne doeleinden zoals Crypto_KeyExchangeCalcPubVal services van een random number generator (RNG) nodig heeft, moet het eerste Crypto Driver Object (objectnummer 0) voor dit doel zijn geconfigureerd ([SWS_Crypto_00224]).

De synchrone functie Crypto_KeyExchangeCalcSecret dient voor de berekening van een gedeeld geheim (Shared Secret Key) voor een sleuteluitwisselingsprotocol [SWS_Crypto_91010]. Deze verwerkt het sleutelmateriaal van de via cryptoKeyId gespecificeerde sleutel samen met de via partnerPublicValuePtr doorgegeven publieke waarde van de partner, waarvan het aantal bytes via partnerPublicValueLength wordt opgegeven [SWS_Crypto_91010]. Het berekende gedeelde geheim wordt direct als sleutelelement binnen dezelfde sleutel opgeslagen [SWS_Crypto_91010].

Als retourwaarde levert de functie de status via Std_ReturnType [SWS_Crypto_91010]:

• E_OK: De berekening en opslag van het geheim zijn succesvol afgerond [SWS_Crypto_91010].
• E_NOT_OK: Het verzoek is mislukt [SWS_Crypto_91010].
• CRYPTO_E_BUSY: De uitvoering is mislukt, omdat het verantwoordelijke Crypto Driver Object bezet is [SWS_Crypto_91010].
• CRYPTO_E_KEY_EMPTY: Het bronsleutelelement is niet-geïnitialiseerd [SWS_Crypto_91010].
• CRYPTO_E_KEY_NOT_VALID: De toestand van de door cryptoKeyId gerefereerde sleutel is ongeldig [SWS_Crypto_91010].

De interface is geïmplementeerd als re-entrant, maar mag niet gelijktijdig voor dezelfde cryptoKeyId worden aangeroepen [SWS_Crypto_91010]. Aanroepers moeten er daarom voor zorgen dat gelijktijdige aanroepen met een identieke sleutel-ID worden vermeden en dat het gerefereerde sleutelmateriaal vooraf geïnitialiseerd en in een geldige status is, om foutsituaties te voorkomen [SWS_Crypto_91010].

De functie Crypto_MainFunction dient voor de cyclische afhandeling van in de wachtrij geplaatste cryptografische opdrachten in de job-wachtrijen van de crypto-driver [SWS_Crypto_91012]. Voorwaarde voor de inzet ervan is dat in de module de asynchrone opdrachtverwerking is geconfigureerd en dat er passende opdrachtwachtrijen aanwezig zijn [SWS_Crypto_91012].

Aanroep en semantiek

De functie heeft de signatuur void Crypto_MainFunction(void) en is gespecificeerd met de service-ID 0x0c [SWS_Crypto_91012]. Ze accepteert geen invoerparameters en levert geen retourwaarde op. De interface wordt beschikbaar gesteld via de header SchM_Crypto.h [SWS_Crypto_91012]. Dit laat de interpretatie toe dat de cyclische aanroep volgens plan wordt getriggerd door de BSW-scheduler (Schedule Manager) in de context van een periodieke taak van het besturingssysteem.

Gelijktijdigheid en beperkingen

De aanroep is strikt gebonden aan de configuratie van asynchrone jobwachtrijen [SWS_Crypto_91012]. Aangezien de specificatie geen re-entrantie voor Crypto_MainFunction aangeeft, dient de functie vermoedelijk als niet-re-entrant te worden behandeld; parallelle aanroepen vanuit meerdere threads of taken moeten daarom worden vermeden. Vraag Q-038d384305c8c5c3 (open)

Foutafhandeling

In de specificatie zijn voor deze functie geen specifieke foutcodes of DET-vermeldingen opgenomen [SWS_Crypto_91012]. Omdat de functie geen retourwaarden levert, worden eventuele fouten tijdens de asynchrone verwerking vermoedelijk via statusopvragingen of via de terugmeldingskanalen van de respectievelijke jobs doorgegeven aan bovenliggende lagen. Vraag (open)