Crypto Driver (Crypto)

Die Funktion Crypto_Init dient der Initialisierung des Crypto Drivers gemäß [SWS_Crypto_91000]. Die Schnittstelle ist im Header Crypto.h deklariert und besitzt die Service-ID 0x00 [SWS_Crypto_91000].

Für den Aufruf und die Schnittstellenparameter sind folgende Eigenschaften spezifiziert:

• Konfigurationszeiger: Über den Eingangsparameter configPtr vom Typ const Crypto_ConfigType* wird ein Zeiger auf die ausgewählte Konfigurationsstruktur übergeben [SWS_Crypto_91000].
• Rückgabewert: Die Funktion besitzt keinen Rückgabewert (void); es existieren weder Ein-/Ausgabeparameter noch separate Ausgabeparameter [SWS_Crypto_91000].
• Ausführungsverhalten: Die Initialisierungsroutine wird synchron ausgeführt (Synchronous) [SWS_Crypto_91000].
• Reentranz: Die Funktion ist als nicht reentrant (Non Reentrant) definiert [SWS_Crypto_91000]. Parallele oder überlappende Aufrufe sind unzulässig.

Aufgrund der Einstufung als nicht reentrant und da die Spezifikation keine spezifischen Fehlercodes zurückgibt, dürfte der Aufruf typischerweise zentral während der Startphase des Steuergeräts vor allen anderen Treiberzugriffen erfolgen (Interpretation). Frage Q-008bb5a45b823891 (offen) Der Aufrufer dürfte zudem dafür zuständig sein, dass die referenzierte Konfigurationsstruktur im Speicher dauerhaft gültig bleibt (Interpretation). Frage Q-6271a86fad440121 (offen)

Die Funktion Crypto_ProcessJob führt das im Parameter job konfigurierte kryptografische Primitiv auf dem durch objectId referenzierten Crypto Driver Object aus [SWS_Crypto_91003]. Der Aufruf ist reentrant und arbeitet abhängig von der Job-Konfiguration synchron oder asynchron [SWS_Crypto_91003]. Über den Zeiger auf Crypto_JobType werden sowohl Konfigurationsdaten für das Primitiv als auch Puffer für die Ergebnisdaten übergeben [SWS_Crypto_91003].

Vor der eigentlichen Ausführung eines Jobs prüft der Treiber die Schlüsselbezeichner auf Gültigkeit: Liegen job->cryptoKeyId oder gegebenenfalls job->targetCryptoKeyId außerhalb des zulässigen Bereichs, meldet die Funktion den Fehler CRYPTO_E_PARAM_HANDLE an das DET und gibt E_NOT_OK zurück [SWS_Crypto_00217]. Dies gilt auch für den Dienst CRYPTO_KEYDERIVE (job->jobPrimitiveInfo->primitiveInfo->service), sofern job->targetCryptoKeyId ungültig ist [SWS_Crypto_00202].

Neben E_OK und E_NOT_OK signalisieren spezifische Fehlercodes das Scheitern der Anforderung [SWS_Crypto_91003]:

• CRYPTO_E_BUSY, wenn das Treiber-Objekt belegt oder dessen Warteschlange voll ist [SWS_Crypto_91003],
• schlüsselbezogene Fehler wie 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 oder CRYPTO_E_KEY_EMPTY [SWS_Crypto_91003],
• CRYPTO_E_JOB_CANCELED bei Abbruch eines synchronen Jobs [SWS_Crypto_91003] sowie
• CRYPTO_E_ENTROPY_EXHAUSTED bei unzureichender Entropie eines Zufallsgenerators; hierbei meldet die Funktion zusätzlich den Laufzeitfehler CRYPTO_E_RE_ENTROPY_EXHAUSTED [SWS_Crypto_00141], [SWS_Crypto_91003].

Verwendung

Die synchrone Funktion Crypto_CancelJob entfernt einen übergebenen Job aus der Warteschlange und bricht dessen Verarbeitung nach Möglichkeit ab [SWS_Crypto_00122]. Beim Aufruf werden der Bezeichner des Crypto Driver Objects (objectId) sowie ein Zeiger auf die Jobkonfiguration (job) übergeben [SWS_Crypto_00122].

Die Rückgabewerte signalisieren das Ergebnis des Abbruchversuchs:

• E_OK: Die Anforderung war erfolgreich und der Job wurde entfernt [SWS_Crypto_00122]. Liegt kein Fehler im Treiber vor und wird der Job derzeit nicht verarbeitet, liefert der Dienst ebenfalls E_OK ohne weitere Aktionen zurück [SWS_Crypto_00214].
• E_NOT_OK: Die Anforderung ist fehlgeschlagen, da der Job nicht entfernt werden konnte [SWS_Crypto_00122].
• CRYPTO_E_JOB_CANCELED: Der Job wurde abgebrochen, wird jedoch weiter ausgeführt; es werden keine Ergebnisse an die Anwendung zurückgemeldet [SWS_Crypto_00122]. Dies gilt, wenn der Treiber fehlerfrei arbeitet, den Job jedoch (beispielsweise aufgrund von Hardware-Einschränkungen) nicht abbrechen kann [SWS_Crypto_00183].

Nebenläufigkeit und Einschränkungen

Die Schnittstelle ist reentrant für unterschiedliche Instanzen, darf jedoch nicht zeitgleich für dasselbe Crypto Driver Object aufgerufen werden [SWS_Crypto_00122].

Die synchrone Funktion Crypto_KeyElementSet dient dazu, die Rohdaten eines bestimmten Schlüsselelements für einen über cryptoKeyId identifizierten Schlüssel im Krypto-Treiber zu setzen [SWS_Crypto_91004].

Parameter und Rückgabewerte

Über keyElementId wird das Ziel-Schlüsselelement adressiert, während keyPtr auf den Datenpuffer und keyLength auf dessen Bytegröße verweist [SWS_Crypto_91004]. Bei erfolgreicher Zuweisung gibt die Schnittstelle E_OK zurück [SWS_Crypto_91004].

Fehlerbehandlung

Tritt bei der Verarbeitung ein Fehler auf, liefert die Funktion spezifische Rückgabewerte [SWS_Crypto_91004]:

• CRYPTO_E_BUSY: Das zugehörige Crypto-Driver-Objekt ist belegt.
• CRYPTO_E_KEY_WRITE_FAIL: Der Schreibzugriff auf das Schlüsselelement wurde verweigert.
• CRYPTO_E_KEY_NOT_AVAILABLE: Das angeforderte Schlüsselelement oder der Schlüssel ist nicht verfügbar.
• CRYPTO_E_KEY_SIZE_MISMATCH: Die übergebene Datenlänge stimmt nicht mit der Größe des Schlüsselelements überein.
• E_NOT_OK: Die Anfrage ist aus sonstigen Gründen fehlgeschlagen.

Nebenläufigkeit

Die Funktion ist als nicht reentrant (Non Reentrant) spezifiziert [SWS_Crypto_91004]. Interpretation: Aufrufer dürften dafür zuständig sein, parallele Aufrufe gegeneinander zu synchronisieren, um Dateninkonsistenzen im Treiber zu verhindern. Frage Q-d7ef7a774052a212 (offen)

Die synchrone Funktion Crypto_KeySetValid dient dazu, den Zustand eines über die Kennung cryptoKeyId spezifizierten Schlüssels auf gültig zu setzen ([SWS_Crypto_91014]). Die Schnittstelle ist über die Header-Datei Crypto.h verfügbar und besitzt die Service-ID 0x05 ([SWS_Crypto_91014]).

Bei der Verwendung sind folgende Parameter und Rückgabewerte definiert ([SWS_Crypto_91014]):

• Eingabeparameter: Über cryptoKeyId (Typ uint32) wird die Kennung des Schlüssels übergeben, dessen Zustand auf gültig gesetzt werden soll ([SWS_Crypto_91014]). Zusätzliche Ein- oder Ausgabeparameter existieren nicht ([SWS_Crypto_91014]).
• Rückgabewert: Ein Statuscode vom Typ Std_ReturnType informiert über das Resultat der Anforderung ([SWS_Crypto_91014]):
  • E_OK: Die Anforderung war erfolgreich ([SWS_Crypto_91014]).
  • E_NOT_OK: Die Anforderung ist fehlgeschlagen ([SWS_Crypto_91014]).
  • CRYPTO_E_BUSY: Die Ausführung schlug fehl, da das zuständige Crypto-Driver-Objekt belegt ist ([SWS_Crypto_91014]).

Hinsichtlich der Nebenläufigkeit ist die Funktion als nicht reentrant („Non Reentrant“) spezifiziert ([SWS_Crypto_91014]). Interpretation: Aufrufer dürften parallele Aufrufe über Tasks hinweg extern koordinieren müssen, um Konflikte zu vermeiden, und sollten bei Erhalt von CRYPTO_E_BUSY eine Wiederholung des Aufrufs zu einem späteren Zeitpunkt vorsehen. Frage Q-32d775a9e61e5731 (offen)

Verwendung und Semantik

Die synchrone Funktion Crypto_KeySetInvalid setzt den Status eines durch cryptoKeyId identifizierten Schlüssels auf ungültig [SWS_Crypto_91020]. Die Funktion ist in der Header-Datei Crypto.h definiert und wird über die Service-ID 0x15 angesprochen [SWS_Crypto_91020]. Als einziger Übergabeparameter dient der Eingabewert cryptoKeyId (Typ uint32), welcher den eindeutigen Bezeichner des Zielschlüssels enthält; Ein-/Ausgabe- sowie Ausgabeparameter sind nicht vorhanden [SWS_Crypto_91020].

Fehlerbehandlung und Rückgabewerte

Das Ergebnis der Funktionsausführung wird über den Rückgabewert vom Typ Std_ReturnType signalisiert [SWS_Crypto_91020]:

• E_OK: Die Anforderung war erfolgreich und der Schlüsselstatus wurde auf ungültig gesetzt [SWS_Crypto_91020].
• E_NOT_OK: Die Durchführung der Anforderung ist fehlgeschlagen [SWS_Crypto_91020].
• CRYPTO_E_BUSY: Die Anforderung schlug fehl, da das zuständige Krypto-Treiberobjekt (Crypto Driver Object) derzeit belegt ist [SWS_Crypto_91020].

Nebenläufigkeit und Einschränkungen

Die Schnittstelle ist als nicht reentrant (Non Reentrant) spezifiziert [SWS_Crypto_91020]. Ein nebenläufiger oder unterbrechender Aufruf ist daher unzulässig. Da die Funktion synchron ausgeführt wird, kehrt sie erst nach Abschluss der Statusänderung bzw. nach Feststellung des Fehlers zum Aufrufer zurück [SWS_Crypto_91020].

Die synchrone und reentrante Funktion Crypto_KeyElementGet dient dazu, ein durch keyElementId identifiziertes Schlüsselelement aus dem Schlüssel cryptoKeyId auszulesen und im Speicherbereich resultPtr abzulegen [SWS_Crypto_91006]. Die Schnittstelle wird über den Header Crypto.h bereitgestellt und besitzt die Service-ID 0x06 [SWS_Crypto_91006]. Beim Aufruf übergibt der Aufrufer über den In-Out-Parameter resultLengthPtr die Puffergröße oder bei konfiguriertem Teilzugriff die gewünschte Lesegröße; nach Abschluss der Ausführung hinterlegt der Treiber dort die tatsächlich kopierte Datenmenge [SWS_Crypto_91006].

Im Erfolgsfall liefert die Funktion E_OK zurück [SWS_Crypto_91006]. Schlägt die Operation fehl, signalisiert sie dies über spezifische Fehlercodes: CRYPTO_E_BUSY bei belegtem Crypto-Treiberobjekt, CRYPTO_E_KEY_NOT_AVAILABLE falls das Schlüsselelement nicht verfügbar ist, CRYPTO_E_KEY_READ_FAIL bei verweigertem Lesezugriff, CRYPTO_E_KEY_EMPTY bei einem uninitialisierten Quellelement sowie generisch E_NOT_OK [SWS_Crypto_91006].

Obwohl die Schnittstelle als reentrant spezifiziert ist, weist die Spezifikation darauf hin, dass bei direktem Mapping des Schlüsselelements in den Flash-Speicher spürbare Latenzen während der synchronen Ausführung auftreten können [SWS_Crypto_91006]. Interpretation: Aufgrund dieser potenziellen Verzögerungen dürfte der Aufruf primär im Task-Kontext und nicht innerhalb zeitkritischer Interrupt-Service-Routinen zweckmäßig sein. Frage Q-ff4e2843b9aad46d (offen)

Die synchrone Funktion Crypto_KeyGetStatus dient dem Abfragen des aktuellen Zustands eines spezifischen Schlüssels innerhalb des Crypto-Treibers [SWS_Crypto_91019]. Sie wird über den Header Crypto.h bereitgestellt und führt die Service-ID 0x14 [SWS_Crypto_91019].

Verwendung und Parameter

Der Aufruf erfolgt synchron und erwartet zwei Parameter [SWS_Crypto_91019]:

• cryptoKeyId: Der Bezeichner des Schlüssels, dessen Status ermittelt werden soll.
• keyStatusPtr: Zeiger auf den Speicherbereich vom Typ Crypto_KeyStatusType, an den der Zustand zurückgegeben wird.

Als Rückgabewert liefert die Schnittstelle Std_ReturnType zurück. Bei erfolgreicher Durchführung wird E_OK gemeldet, während im Fehlerfall E_NOT_OK zurückgegeben wird [SWS_Crypto_91019].

Nebenläufigkeit und Einschränkungen

Die Funktion ist als nicht reentrant (Non Reentrant) deklariert [SWS_Crypto_91019]. Aufrufer müssen daher sicherstellen, dass nebenläufige Aufrufe durch übergeordnete Synchronisationsmechanismen vermieden werden. Spezifische DET-Fehlermeldungen sind nicht aufgeführt; vermutlich führt ein fehlerhafter Aufruf wie ein ungültiger Zeiger oder eine ungültige ID direkt zur Rückgabe von E_NOT_OK [SWS_Crypto_91019]. Frage Q-5703fab02905e91a (offen)

Die synchrone Funktion Crypto_KeyElementCopy dient dem Kopieren eines Schlüsselelements auf ein anderes Schlüsselelement innerhalb desselben Crypto-Treibers [SWS_Crypto_00148]. Übergeben werden die Identifikatoren des Quellschlüssels (cryptoKeyId) und des Quell-Schlüsselelements (keyElementId) sowie des Zielschlüssels (targetCryptoKeyId) und des Ziel-Schlüsselelements (targetKeyElementId) [SWS_Crypto_00148].

Hinsichtlich des Zeitverhaltens ist zu beachten, dass es bei direkt im Flash-Speicher abgebildeten Schlüsselelementen aufgrund der synchronen Ausführung zu größeren Verzögerungen beim Funktionsaufruf kommen kann [SWS_Crypto_00148]. Das Laufzeitverhalten ist daher insbesondere in zeitkritischen Kontexten zu berücksichtigen.

Die Funktion ist reentrant ausgelegt, jedoch explizit nicht für dieselbe cryptoKeyId [SWS_Crypto_00148]. Gleichzeitige Aufrufe mit identischem Quellschlüssel sind folglich vom Aufrufer zu synchronisieren oder auszuschließen.

Im Erfolgsfall gibt die Funktion E_OK zurück [SWS_Crypto_00148]. Bei Fehlern signalisiert der Rückgabewert die spezifische Ursache [SWS_Crypto_00148]:

• CRYPTO_E_BUSY: Das Crypto-Treiber-Objekt ist belegt [SWS_Crypto_00148].
• CRYPTO_E_KEY_NOT_AVAILABLE: Das angeforderte Schlüsselelement mindestens eines Schlüssels ist nicht verfügbar [SWS_Crypto_00148].
• CRYPTO_E_KEY_READ_FAIL oder CRYPTO_E_KEY_WRITE_FAIL: Das Auslesen des Quell- bzw. Schreiben des Zielelements ist nicht gestattet [SWS_Crypto_00148].
• CRYPTO_E_KEY_SIZE_MISMATCH: Die Größen der Schlüsselelemente sind nicht zueinander kompatibel [SWS_Crypto_00148].
• CRYPTO_E_KEY_EMPTY: Das Quell-Schlüsselelement ist nicht initialisiert [SWS_Crypto_00148].
• E_NOT_OK: Die Anfrage ist allgemein fehlgeschlagen [SWS_Crypto_00148].

Die synchrone Funktion Crypto_KeyElementCopyPartial dient dem partiellen Kopieren von Daten aus einem Quell-Schlüsselelement in ein Ziel-Schlüsselelement innerhalb desselben Krypto-Treibers [SWS_Crypto_91015]. Über die Parameter keyElementSourceOffset und keyElementCopyLength wird der zu kopierende Ausschnitt des Quell-Elements (cryptoKeyId, keyElementId) festgelegt, während keyElementTargetOffset die Startposition im Ziel-Element (targetCryptoKeyId, targetKeyElementId) bestimmt. Bei fehlerfreier Prüfung führt der Treiber den Kopiervorgang synchron durch und gibt E_OK zurück [SWS_Crypto_00209].

Vor der Durchführung validiert der Treiber die Puffer- und Treiberzustände:

• Ist der Krypto-Treiber nicht initialisiert und die Entwicklungskontrolle aktiviert, meldet die Funktion CRYPTO_E_UNINIT an das DET und liefert E_NOT_OK [SWS_Crypto_00205].
• Ist die Gesamtlänge des Quell-Schlüsselelements kleiner als keyElementSourceOffset + keyElementCopyLength, schlägt der Aufruf mit CRYPTO_E_KEY_SIZE_MISMATCH fehl [SWS_Crypto_00207].
• Bietet der maximale Puffer des Ziel-Schlüsselelements weniger Platz als keyElementTargetOffset + keyElementCopyLength, wird ebenfalls CRYPTO_E_KEY_SIZE_MISMATCH gemeldet [SWS_Crypto_00208].
• Weitere spezifizierte Fehlerwerte sind unter anderem CRYPTO_E_BUSY (Treiberobjekt belegt), CRYPTO_E_KEY_EMPTY (uninitialisiertes Quell-Element), CRYPTO_E_KEY_NOT_AVAILABLE sowie Lese- oder Schreibzugriffsfehler (CRYPTO_E_KEY_READ_FAIL, CRYPTO_E_KEY_WRITE_FAIL) [SWS_Crypto_91015].

Die Funktion ist reentrant, darf jedoch nicht zeitgleich für dieselbe Schlüssel-ID cryptoKeyId aufgerufen werden [SWS_Crypto_91015]. Ist ein Schlüsselelement direkt im Flash-Speicher abgelegt, kann die synchrone Ausführung zu spürbaren Zeitverzögerungen führen [SWS_Crypto_91015].

Verwendung

Die synchrone Funktion Crypto_KeyCopy kopiert einen Schlüssel mitsamt all seiner Schlüsselelemente auf einen Zielschlüssel innerhalb desselben Crypto-Treibers [SWS_Crypto_00155]. Die Zuordnung erfolgt über die Eingangsparameter cryptoKeyId für den Quellschlüssel sowie targetCryptoKeyId für den Zielschlüssel [SWS_Crypto_00155]. Ein erfolgreicher Kopiervorgang wird mit E_OK bestätigt [SWS_Crypto_00155].

Nebenläufigkeit und Laufzeitverhalten

Die Schnittstelle ist reentrant ausgelegt, darf jedoch nicht zeitgleich für dieselbe cryptoKeyId ausgeführt werden [SWS_Crypto_00155]. Da die Ausführung synchron erfolgt, kann es bei Schlüsselelementen, die direkt im Flash-Speicher abgelegt sind, zu spürbaren Zeitverzögerungen während des Aufrufs kommen [SWS_Crypto_00155].

Fehlerbehandlung

Im Fehlerfall liefert die Funktion spezifische Rückgabewerte vom Typ Std_ReturnType [SWS_Crypto_00155]:

• CRYPTO_E_BUSY: Das zugehörige Crypto Driver Object ist ausgelastet [SWS_Crypto_00155].
• CRYPTO_E_KEY_NOT_AVAILABLE: Mindestens einer der angeforderten Schlüssel ist nicht verfügbar [SWS_Crypto_00155].
• CRYPTO_E_KEY_READ_FAIL: Das Auslesen des Quellschlüsselelements ist nicht erlaubt [SWS_Crypto_00155].
• CRYPTO_E_KEY_WRITE_FAIL: Das Beschreiben des Zielschlüsselelements ist nicht erlaubt [SWS_Crypto_00155].
• CRYPTO_E_KEY_SIZE_MISMATCH: Die Größen der Schlüsselelemente sind nicht miteinander kompatibel [SWS_Crypto_00155].
• CRYPTO_E_KEY_EMPTY: Das Schlüsselelement des Quellschlüssels ist nicht initialisiert [SWS_Crypto_00155].
• E_NOT_OK: Die Durchführung der Anforderung ist fehlgeschlagen [SWS_Crypto_00155].

Die synchrone Funktion Crypto_KeyElementIdsGet dient dazu, Informationen darüber abzufragen, welche Schlüsselelemente in einem gegebenen Schlüssel verfügbar sind [SWS_Crypto_00160]. Über den Eingabeparameter cryptoKeyId wird die Kennung des Schlüssels übergeben, dessen verfügbare Element-IDs exportiert werden sollen [SWS_Crypto_00160]. Die ermittelten Identifikatoren werden in dem durch den Zeiger keyElementIdsPtr referenzierten Array abgelegt [SWS_Crypto_00160].

Die Verwaltung der Puffergröße erfolgt über den Ein- und Ausgangsparameter keyElementIdsLengthPtr: Beim Aufruf muss dieser Parameter die bereitgestellte Größe des Puffers keyElementIdsPtr enthalten [SWS_Crypto_00160]. Nach Beendigung der Operation wird dort die tatsächliche Anzahl der vorhandenen Schlüsselelemente hinterlegt [SWS_Crypto_00160].

Als Rückgabewert liefert der Dienst E_OK bei erfolgreicher Abfrage oder E_NOT_OK, falls die Anfrage fehlgeschlagen ist [SWS_Crypto_00160]. Ist das zuständige Krypto-Treiber-Objekt zum Aufrufzeitpunkt beschäftigt, wird der Fehlercode CRYPTO_E_BUSY zurückgegeben [SWS_Crypto_00160].

Hinsichtlich der Nebenläufigkeit ist die Funktion reentrant, darf jedoch nicht zeitgleich für dieselbe cryptoKeyId aufgerufen werden [SWS_Crypto_00160]. Die Deklaration ist über den Header Crypto.h verfügbar [SWS_Crypto_00160].

Die synchrone Funktion Crypto_RandomSeed (Service-ID 0x0d) dient gemäß [SWS_Crypto_91013] der Erzeugung sowie der Aktualisierung des internen Seed-Zustands eines Schlüssels unter Nutzung einer bereitgestellten Entropiequelle. Die Funktionsdeklaration ist in der Header-Datei Crypto.h enthalten.

Verwendung und Aufrufparameter

Neben der initialen Generierung kann die Funktion laut [SWS_Crypto_91013] auch genutzt werden, um den Seed-Zustand mit neuer Entropie zu aktualisieren. Der synchrone Aufruf erfordert dabei drei Eingangsparameter:

• cryptoKeyId: Übergibt den Identifikator des Schlüssels, für den ein neuer Seed erzeugt werden soll.
• seedPtr: Hält einen Zeiger auf den Speicherbereich mit den Daten zur Speisung des Seeds.
• seedLength: Definiert die Länge der übergebenen Seed-Daten in Bytes.

Rückgabewerte und Fehlerbehandlung

Als Rückgabewert meldet Crypto_RandomSeed einen Status vom Typ Std_ReturnType nach [SWS_Crypto_91013]:

• E_OK: Die Anfrage wurde erfolgreich ausgeführt.
• E_NOT_OK: Die Anfrage ist fehlgeschlagen.
• CRYPTO_E_KEY_NOT_VALID: Die Ausführung schlägt fehl, da sich der Schlüsselzustand des durch cryptoKeyId identifizierten Schlüssels im Status „invalid“ befindet.

Nebenläufigkeit und Einschränkungen

Gemäß [SWS_Crypto_91013] ist die Funktion als reentrant spezifiziert, jedoch ausdrücklich nicht für dieselbe cryptoKeyId. Parallele Aufrufe für denselben Schlüssel müssen daher auf Aufruferseite verhindert werden.

Verwendung

Die über die Header-Datei Crypto.h bereitgestellte Funktion Crypto_KeyGenerate erzeugt neues Schlüsselmaterial und aktualisiert den Schlüssel, der über die Kennung cryptoKeyId adressiert wird [SWS_Crypto_91007]. Die Funktion arbeitet vollständig synchron und ist unter der Service-ID 0x07 definiert [SWS_Crypto_91007]. Weitere Parameter existieren neben dem Schlüsselbezeichner nicht [SWS_Crypto_91007].

Nebenläufigkeit und Einschränkungen

In Bezug auf die Nebenläufigkeit ist Crypto_KeyGenerate als reentrant spezifiziert, jedoch ausdrücklich mit der Einschränkung, dass dies nicht für dieselbe cryptoKeyId gilt [SWS_Crypto_91007]. Werden mehrere Anforderungen für denselben Schlüssel gestellt, müssen diese aufruferseitig synchronisiert werden, um Treiberkonflikte zu vermeiden.

Rückgabewerte und Fehlerbehandlung

Über den Rückgabewert vom Basistyp Std_ReturnType erhält der Aufrufer detaillierte Rückmeldung über Erfolg oder spezifische Fehlerursachen der Operation [SWS_Crypto_91007]:

• E_OK: Die Schlüsselerzeugung wurde erfolgreich ausgeführt [SWS_Crypto_91007].
• CRYPTO_E_BUSY: Die Anfrage schlug fehl, da das zuständige Crypto Driver Object derzeit belegt ist [SWS_Crypto_91007].
• CRYPTO_E_KEY_EMPTY: Die Erzeugung schlug fehl, weil ein erforderliches Quellschlüsselelement uninitialisiert ist [SWS_Crypto_91007].
• CRYPTO_E_KEY_NOT_VALID: Die Operation scheiterte, da der Schlüsselzustand des durch cryptoKeyId referenzierten Schlüssels als ungültig markiert ist [SWS_Crypto_91007].
• E_NOT_OK: Die Anfrage zur Schlüsselerzeugung ist aus sonstigen Gründen fehlgeschlagen [SWS_Crypto_91007].

Die synchrone Funktion Crypto_KeyDerive leitet aus den Schlüsselelementen eines Quellschlüssels (cryptoKeyId) einen neuen kryptografischen Schlüssel ab und speichert diesen im Schlüsselelement mit der ID 1 des Zielschlüssels (targetCryptoKeyId) [SWS_Crypto_91008]. Der Quellschlüssel muss die erforderlichen Schlüsselelemente für Passwort und Salt enthalten; die Anzahl der Iterationen wird über das Schlüsselelement CRYPTO_KE_KEYDERIVATION_ITERATIONS vorgegeben [SWS_Crypto_91008].

Aufruf und Nebenläufigkeit

Die Schnittstelle ist reentrant, darf jedoch nicht zeitgleich für dieselbe cryptoKeyId aufgerufen werden [SWS_Crypto_91008]. Aufrufer müssen daher sicherstellen, dass parallele Ableitungsvorgänge auf unterschiedlichen Quellschlüsseln operieren.

Rückgabewerte und Fehlerbehandlung

Die Funktion signalisiert das Ergebnis über definierte Rückgabewerte vom Typ Std_ReturnType [SWS_Crypto_91008]:

• E_OK: Schlüsselableitung erfolgreich durchgeführt.
• E_NOT_OK: Ableitung fehlgeschlagen. Liegt der Parameter targetCryptoKeyId außerhalb des gültigen Bereichs, meldet die Funktion bei aktivierter Entwicklungserkennung zudem CRYPTO_E_PARAM_HANDLE an das DET [SWS_Crypto_00180].
• CRYPTO_E_BUSY: Das zuständige Crypto Driver Object ist belegt [SWS_Crypto_91008].
• CRYPTO_E_KEY_EMPTY: Ein benötigtes Quellschlüsselelement ist nicht initialisiert [SWS_Crypto_91008].
• CRYPTO_E_KEY_NOT_VALID: Der Zustand des durch cryptoKeyId referenzierten Schlüssels ist ungültig [SWS_Crypto_91008].

Verwendung

Die synchrone Funktion Crypto_KeyExchangeCalcPubVal berechnet den öffentlichen Wert für ein Schlüsselaustauschprotokoll und speichert diesen am Speicherort von publicValuePtr ab ([SWS_Crypto_91009]). Der Aufrufer übergibt über cryptoKeyId die Kennung des Schlüssels, der für das Protokoll genutzt werden soll. Über den Ein- und Ausgangsparameter publicValueLengthPtr muss beim Aufruf die Puffergröße des bereitgestellten Speichers übergeben werden; nach Abschluss der Ausführung wird dort die tatsächliche Länge des berechneten öffentlichen Werts hinterlegt ([SWS_Crypto_91009]).

Fehlerbehandlung und Rückgabewerte

Die Funktion gibt E_OK bei erfolgreicher Ausführung zurück. Tritt ein Fehler auf, wird E_NOT_OK oder ein spezifischer Fehlercode zurückgegeben ([SWS_Crypto_91009]):

• CRYPTO_E_BUSY: Die Anfrage schlägt fehl, da das Crypto Driver Object belegt ist.
• CRYPTO_E_KEY_EMPTY: Die Anfrage schlägt fehl, weil das Quell-Schlüsselelement nicht initialisiert ist.
• CRYPTO_E_KEY_NOT_VALID: Die Anfrage schlägt fehl, da der Status des über cryptoKeyId referenzierten Schlüssels ungültig ist.

Nebenläufigkeit und Systemintegration

Gemäß [SWS_Crypto_91009] ist die Funktion reentrant, jedoch nicht für dieselbe cryptoKeyId. Wenn der Krypto-Treiber für interne Zwecke wie Crypto_KeyExchangeCalcPubVal Dienste eines Zufallszahlengenerators (RNG) benötigt, muss das erste Crypto Driver Object (Objektnummer 0) für diesen Zweck konfiguriert sein ([SWS_Crypto_00224]).

Die synchrone Funktion Crypto_KeyExchangeCalcSecret dient der Berechnung eines gemeinsamen Geheimnisses (Shared Secret Key) für ein Schlüsselaustausch-Protokoll [SWS_Crypto_91010]. Sie verarbeitet das Schlüsselmaterial des über cryptoKeyId spezifizierten Schlüssels zusammen mit dem über partnerPublicValuePtr übergebenen öffentlichen Wert des Partners, dessen Bytezahl über partnerPublicValueLength angegeben wird [SWS_Crypto_91010]. Das berechnete gemeinsame Geheimnis wird direkt als Schlüsselelement innerhalb desselben Schlüssels gespeichert [SWS_Crypto_91010].

Als Rückgabewert liefert die Funktion den Status über Std_ReturnType [SWS_Crypto_91010]:

• E_OK: Die Berechnung und Ablage des Geheimnisses wurden erfolgreich abgeschlossen [SWS_Crypto_91010].
• E_NOT_OK: Die Anfrage ist fehlgeschlagen [SWS_Crypto_91010].
• CRYPTO_E_BUSY: Die Ausführung scheiterte, da das zuständige Crypto Driver Object belegt ist [SWS_Crypto_91010].
• CRYPTO_E_KEY_EMPTY: Das Quell-Schlüsselelement ist uninitialisiert [SWS_Crypto_91010].
• CRYPTO_E_KEY_NOT_VALID: Der Zustand des durch cryptoKeyId referenzierten Schlüssels ist ungültig [SWS_Crypto_91010].

Die Schnittstelle ist reentrant implementiert, darf jedoch nicht nebenläufig für dieselbe cryptoKeyId aufgerufen werden [SWS_Crypto_91010]. Aufrufer müssen daher sicherstellen, dass gleichzeitige Aufrufe mit identischer Schlüssel-ID vermieden werden und das referenzierte Schlüsselmaterial vorab initialisiert sowie in einem gültigen Zustand ist, um Fehlerzustände zu verhindern [SWS_Crypto_91010].

Die Funktion Crypto_MainFunction dient der zyklischen Abarbeitung von eingereihten kryptografischen Aufträgen in den Job-Warteschlangen des Krypto-Treibers [SWS_Crypto_91012]. Voraussetzung für ihren Einsatz ist, dass im Modul die asynchrone Auftragsverarbeitung konfiguriert wurde und entsprechende Auftragswarteschlangen vorhanden sind [SWS_Crypto_91012].

Aufruf und Semantik

Die Funktion besitzt die Signatur void Crypto_MainFunction(void) und ist mit der Service-ID 0x0c spezifiziert [SWS_Crypto_91012]. Sie nimmt keine Eingabeparameter entgegen und liefert keinen Rückgabewert. Die Schnittstelle wird über den Header SchM_Crypto.h bereitgestellt [SWS_Crypto_91012]. Dies lässt die Interpretation zu, dass der zyklische Aufruf planmäßig durch den BSW-Scheduler (Schedule Manager) im Kontext einer periodischen Task des Betriebssystems angestoßen wird.

Nebenläufigkeit und Einschränkungen

Der Aufruf ist strikt an die Konfiguration asynchroner Job-Warteschlangen gebunden [SWS_Crypto_91012]. Da die Spezifikation keine Reentranz für Crypto_MainFunction ausweist, dürfte die Funktion als nicht reentrant zu behandeln sein; parallele Aufrufe aus mehreren Threads oder Tasks sollten daher vermieden werden. Frage Q-038d384305c8c5c3 (offen)

Fehlerbehandlung

In der Spezifikation sind für diese Funktion keine spezifischen Fehlercodes oder DET-Einträge hinterlegt [SWS_Crypto_91012]. Da die Funktion keine Rückgabewerte bereitstellt, werden etwaige Fehler während der asynchronen Abarbeitung vermutlich über Statusabfragen oder über die Rückmeldekanäle der jeweiligen Jobs an übergeordnete Schichten weitergegeben. Frage (offen)