Key Manager (KeyM)

Die Funktion KeyM_Init dient der Initialisierung des Key-Management-Moduls ([SWS_KeyM_00043]). Der Aufruf erfolgt synchron und ist als nicht reentrant definiert ([SWS_KeyM_00043]). Als einziger Übergabeparameter wird ConfigPtr erwartet, welcher einen Zeiger auf den Konfigurationsdatensatz für VARIANT-POST-BUILD darstellt; die Funktion besitzt keinen Rückgabewert ([SWS_KeyM_00043]).

Hinsichtlich des Zusammenspiels mit anderen Modulfunktionen stellt KeyM_Init eine zwingende Vorbedingung dar: Bei aktivierter Entwicklungserkennung prüfen alle weiteren Funktionen des Key Managers, ob das Modul zuvor über KeyM_Init initialisiert und noch nicht mittels KeyM_Deinit deinitialisiert wurde ([SWS_KeyM_00144]). Wird eine Modulfunktion im uninitialisierten Zustand aufgerufen, meldet der Key Manager den Entwicklungsfehler KEYM_E_UNINIT ([SWS_KeyM_00144]).

Da KeyM_Init als nicht reentrant spezifiziert ist ([SWS_KeyM_00043]), darf die Funktion in der System-Initialisierungsphase nur einmalig und unter Ausschluss nebenläufiger Aufrufe ausgeführt werden. Das Modul ist nach erfolgreicher Ausführung über die Header-Datei KeyM.h verfügbar ([SWS_KeyM_00043]).

Die Funktion KeyM_Deinit dient dazu, das Modul Key Manager wieder in den uninitialisierten Zustand zurückzusetzen ([SWS_KeyM_00047]).

Verwendung und Aufrufkontext

Der Aufruf von KeyM_Deinit erfolgt synchron und ist als nicht reentrant (Non Reentrant) spezifiziert. Die Funktion besitzt die Service-ID 0x02, akzeptiert keine Parameter und liefert keinen Rückgabewert zurück ([SWS_KeyM_00047]).

Nebenläufigkeit und Zusammenspiel

Durch die Nicht-Reentranz darf KeyM_Deinit nicht nebenläufig zu sich selbst oder im Widerspruch zu laufenden Operationen aufgerufen werden. Nach Ausführung dieser Deinitialisierung befindet sich das Modul im uninitialisierten Zustand. Wenn Development-Fehler aktiviert sind, prüft der Key Manager bei jedem nachfolgenden Funktionsaufruf, ob das Modul zuvor über KeyM_Init() initialisiert und noch nicht mittels KeyM_Deinit() deinitialisiert wurde; andernfalls wird der Entwicklungsfehler KEYM_E_UNINIT gemeldet ([SWS_KeyM_00144]).

Die synchrone Funktion KeyM_Start dient dazu, Operationen zur Schlüsselaktualisierung im Key Manager freizugeben ([SWS_KeyM_00050]). Sie ist optional und steht nur zur Verfügung, wenn der Konfigurationsparameter KeyMCryptoKeyStartFinalizeFunctionEnabled auf true konfiguriert ist (AUTOSAR_SWS_KeyManager S. 35). Die Funktion wird über KeyM.h bereitgestellt und erwartet über StartType den auszuführenden Betriebsmodus sowie über Request Data und Request Data Length zusätzliche Anforderungsdaten wie etwa eine Signatur.

Antwortdaten werden über den Ausgabepuffer Response Data zurückgeliefert. Der Parameter Response Data Length fungiert dabei als Ein- und Ausgabeparameter: Vor dem Aufruf definiert er die maximal im Puffer bereitstehende Bytezahl, nach der Ausführung enthält er die tatsächlich geschriebene Datenlänge ([SWS_KeyM_00050]).

Fehlerbehandlung und Rückgabewerte:

• E_OK: Start-Operation erfolgreich ausgeführt; Schlüsselaktualisierungen sind nun zulässig.
• E_NOT_OK: Start-Operation nicht akzeptiert.
• KEYM_E_PARAMETER_MISMATCH: Übergabeparameter stimmen nicht mit den erwarteten Werten überein.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Eine übergebene Parametergröße stimmt nicht mit der erwarteten Größe überein.

Die Funktion ist als nicht-reentrant (Non Reentrant) spezifiziert ([SWS_KeyM_00050]). Da keine modulinternen Verriegelungen beschrieben sind, dürfte der Aufrufer für eine koordinierte, serialisierte Ausführung sorgen müssen. Frage Q-82276b712a8dd170 (offen)

Die synchrone Funktion KeyM_Prepare dient zur Vorbereitung einer Schlüsselaktualisierung (Key Update Operation) und übermittelt die erforderlichen Informationen an den Schlüsselserver oder stößt die Aushandlung eines gemeinsamen Geheimnisses zur Schlüsselableitung an [SWS_KeyM_00051]. Die Funktion besitzt die Service-ID 0x05, ist über den Header KeyM.h deklariert und steht ausschließlich zur Verfügung, wenn der Konfigurationsparameter Key MCrypto Key Prepare Function Enabled auf TRUE gesetzt ist [SWS_KeyM_00051].

Beim Aufruf sind folgende Puffer und Längenangaben zu übergeben [SWS_KeyM_00051]:

• Request Data und Request Data Length: Eingabedaten und deren Länge für die Anfrage [SWS_KeyM_00051].
• Response Data: Zeiger auf den Puffer zur Aufnahme der Ausgabedaten [SWS_KeyM_00051].
• Response Data Length: Ein-/Ausgabeparameter, der vor dem Aufruf die maximal verfügbare Puffergröße angibt und bei Rückkehr die tatsächlich geschriebene Bytezahl enthält [SWS_KeyM_00051].

Wird der Aufruf mit E_OK quittiert, wurde der Dienst angenommen und wird intern verarbeitet; die finalen Ergebnisse werden anschließend über einen Callback bereitgestellt [SWS_KeyM_00051]. Schlägt die Annahme fehl, liefert die Funktion E_NOT_OK bei internen Fehlern, KEYM_E_PARAMETER_MISMATCH bei abweichenden Parameterwerten oder KEYM_E_KEY_CERT_SIZE_MISMATCH bei unpassenden Größenangaben zurück [SWS_KeyM_00051].

Da KeyM_Prepare als nicht reentrant (Non Reentrant) spezifiziert ist, dürfen keine gleichzeitigen oder verschachtelten Aufrufe erfolgen [SWS_KeyM_00051].

Die Funktion KeyM_Finalize schließt Aktualisierungsvorgänge für Schlüssel ab und überführt die Schlüsseloperation zurück in den Ruhezustand (Idle-Modus) [SWS_KeyM_00053]. Sie wird typischerweise in Verbindung mit einer vorangegangenen KeyM_Start-Operation verwendet. Nach dem Aufruf akzeptiert das Modul keine weiteren Vorbereitungs- oder Aktualisierungsoperationen (Prepare/Update), bis über KeyM_Start ein neuer Ablauf initiiert wird [SWS_KeyM_00053]. Zudem wird das aktualisierte Schlüsselmaterial persistiert und durch den Aufruf von Csm_KeySetValid in den gültigen Zustand überführt [SWS_KeyM_00053].

Verwendung und Nebenläufigkeit: KeyM_Finalize ist nicht reentrant (Non Reentrant) und arbeitet asynchron [SWS_KeyM_00053]. Interpretation: Mangels Reentranz dürfte der Aufruf typischerweise im Task-Kontext erfolgen. Frage Q-895ebec2d0d2e635 (offen) Die Schnittstelle steht nur zur Verfügung, wenn der Konfigurationsparameter KeyMCryptoKeyStartFinalizeFunctionEnabled auf TRUE gesetzt ist, und ist über KeyM.h deklariert [SWS_KeyM_00053].

Parameter und Rückgabewerte: Über RequestDataPtr und RequestDataLength werden anfragespezifische Daten übergeben. Antwortdaten werden über ResponseDataPtr bereitgestellt; ResponseMaxDataLength dient eingangs als Puffergröße und liefert bei synchroner Rückgabe die tatsächliche Byteanzahl [SWS_KeyM_00053]. Wird die Operation angenommen und intern verarbeitet, gibt die Funktion E_OK zurück (die Ergebnisse folgen asynchron per Callback) und ResponseMaxDataLength bleibt unberührt [SWS_KeyM_00053].

Fehlerbehandlung: Im Fehlerfall signalisiert KeyM_Finalize das Scheitern über spezifische Rückgabewerte [SWS_KeyM_00053]:

• E_NOT_OK: Operation wegen eines internen Fehlers nicht angenommen.
• KEYM_E_BUSY: KeyM ist mit anderen Aufträgen beschäftigt; Validierung kann noch nicht durchgeführt werden.
• KEYM_E_PARAMETER_MISMATCH: Parameter stimmen nicht mit dem erwarteten Wert überein.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Parametergröße stimmt nicht überein.

Verwendung

Die synchrone Funktion KeyM_SetCertificate übergibt dem Schlüsselmanagement-Modul Zertifikatsdaten, um ein Zertifikat temporär zu speichern [SWS_KeyM_00057]. Sie erwartet als Eingabeparameter die Kennung des Zertifikats CertId (Typ KeyM_CertificateIdType) sowie den Zeiger CertificateDataPtr (Typ const KeyM_CertDataType*), der auf die bereitzustellende Zertifikatsstruktur verweist [SWS_KeyM_00057]. Die Schnittstelle wird über den Header KeyM.h deklariert und besitzt die Service-ID 0x0a [SWS_KeyM_00057].

Rückgabewerte und Fehlerbehandlung

Der Rückgabewert vom Typ Std_ReturnType gibt Auskunft über die Annahme der Daten [SWS_KeyM_00057]:

• E_OK: Das Zertifikat wurde erfolgreich akzeptiert [SWS_KeyM_00057].
• E_NOT_OK: Das Zertifikat konnte nicht gesetzt werden [SWS_KeyM_00057].
• KEYM_E_PARAMETER_MISMATCH: Die übergebenen Parameter stimmen nicht mit den erwarteten Werten überein [SWS_KeyM_00057].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Die Größe der übergebenen Zertifikatsdaten weicht von der erwarteten Größe ab [SWS_KeyM_00057].

Nebenläufigkeit und Einschränkungen

Die Funktion ist als nicht reentrant (Non Reentrant) eingestuft [SWS_KeyM_00057]. Konkurrierende Aufrufe müssen daher aufruferseitig synchronisiert oder ausgeschlossen werden. Da die Spezifikation explizit eine temporäre Speicherung vorsieht, verbleiben die übergebenen Zertifikatsdaten vermutlich zunächst im flüchtigen Speicher des Moduls, bevor eine dauerhafte Speicherung oder Verifikation erfolgt. Frage Q-c35c4b02344d5bc9 (offen)

Verwendung

Die synchrone Funktion KeyM_GetCertificate dient dazu, die Zertifikatsdaten für eine vorgegebene Zertifikatskennung bereitzustellen [SWS_KeyM_00058]. Der Aufrufer übergibt über den Parameter CertId den Bezeichner des gewünschten Zertifikats sowie über den Inout-Parameter CertificateDataPtr einen Zeiger auf die Zertifikatsdatenstruktur. Der Aufrufer ist dafür verantwortlich, den Puffer bereitzustellen, auf den der Zeiger in der Struktur verweist [SWS_KeyM_00058]. Vor dem Aufruf muss in der Struktur die Maximallänge dieses Puffers angegeben sein; bei erfolgreicher Rückgabe (E_OK) enthält das Längenfeld die tatsächliche Länge der bereitgestellten Zertifikatsdaten [SWS_KeyM_00058].

Fehlerbehandlung

Die Funktion signalisiert den Erfolg oder spezifische Fehler über den Rückgabewert vom Typ Std_ReturnType [SWS_KeyM_00058]:

• E_OK: Zertifikatsdaten sind verfügbar und wurden erfolgreich übergeben.
• KEYM_E_PARAMETER_MISMATCH: Die übergebene Zertifikats-ID (CertId) ist ungültig.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Der bereitgestellte Puffer ist zu klein für das Zertifikat.
• KEYM_E_KEY_CERT_EMPTY: Es sind keine Zertifikatsdaten vorhanden, da der Zertifikats-Slot leer ist.
• KEYM_E_KEY_CERT_READ_FAIL: Das Zertifikat kann nicht bereitgestellt werden, da der Zugriff verweigert wurde.
• E_NOT_OK: Die Operation wurde aufgrund eines internen Fehlers nicht akzeptiert.

Nebenläufigkeit und Einschränkungen

Die Funktion ist als nicht reentrant (Non Reentrant) spezifiziert und steht über die Header-Datei KeyM.h zur Verfügung [SWS_KeyM_00058]. Aufrufer müssen daher sicherstellen, dass parallele Aufrufe der Funktion gegeneinander synchronisiert werden.

Die Funktion KeyM_VerifyCertificates dient der asynchronen Überprüfung zweier intern gespeicherter und geparster Zertifikate gegeneinander gemäß [SWS_KeyM_00059]. Dabei wird validiert, ob das über CertId referenzierte untergeordnete Zertifikat durch das mit CertUpperId referenzierte übergeordnete Zertifikat signiert wurde.

Da der Dienst als nicht reentrant (Non Reentrant) definiert ist, darf er nicht nebenläufig für überlappende Vorgänge aufgerufen werden [SWS_KeyM_00059]. Die Ausführung erfolgt asynchron im Hintergrund: Ein Rückgabewert von E_OK signalisiert lediglich die erfolgreiche Annahme des Prüfauftrags. Das eigentliche Prüfergebnis wird dem Aufrufer über die konfigurierte Callback-Funktion KeyMCertificateVerifyCallbackNotificationFunc mitgeteilt, sofern diese gültig konfiguriert ist [SWS_KeyM_00153].

Wird die Anfrage nicht akzeptiert, liefert die Funktion spezifische Rückgabewerte zur Fehlerbehandlung [SWS_KeyM_00059]:

• KEYM_E_BUSY: Der Key Manager ist durch andere Aufgaben ausgelastet; die Validierung kann zu diesem Zeitpunkt noch nicht gestartet werden.
• KEYM_E_PARAMETER_MISMATCH: Mindestens eine übergebene Zertifikats-ID ist ungültig.
• KEYM_E_KEY_CERT_EMPTY: Einer der referenzierten Zertifikats-Slots ist leer.
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Das übergeordnete Zertifikat (CertUpperId) ist nicht gültig.
• E_NOT_OK: Der Auftrag wurde aufgrund eines internen Fehlers abgewiesen.

Die Funktion KeyM_VerifyCertificate dient der asynchronen Verifikation eines Zertifikats, das zuvor über KeyM_SetCertificate() bereitgestellt wurde [SWS_KeyM_00060]. Die Prüfung erfolgt anhand der übergebenen Zertifikatskennung CertId gegen bereits im Key Manager hinterlegte Zertifikate anderer Zertifikats-IDs [SWS_KeyM_00060]. Die Deklaration ist über die Header-Datei KeyM.h verfügbar [SWS_KeyM_00060].

Aufrufsemantik und Rückgabewerte

Ein Rückgabewert von E_OK bestätigt, dass die Verifikationsanfrage erfolgreich akzeptiert wurde und die Operation im Hintergrund ausgeführt wird [SWS_KeyM_00060]. Kann der Auftrag nicht angenommen werden, erfolgt die Rückmeldung synchron über spezifische Fehlercodes [SWS_KeyM_00060]:

• E_NOT_OK: Die Operation wurde aufgrund eines internen Fehlers abgewiesen [SWS_KeyM_00060].
• KEYM_E_BUSY: Das Modul KeyM ist derzeit mit anderen Aufgaben ausgelastet, sodass die Validierung noch nicht ausgeführt werden kann [SWS_KeyM_00060].
• KEYM_E_PARAMETER_MISMATCH: Die übergebene CertId ist ungültig [SWS_KeyM_00060].
• KEYM_E_KEY_CERT_EMPTY: Mindestens einer der benötigten Zertifikatsslots ist leer [SWS_KeyM_00060].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Ein übergeordnetes Zertifikat in der Vertrauenskette ist ungültig [SWS_KeyM_00060].

Nebenläufigkeit und Asynchronität

Da KeyM_VerifyCertificate als nicht reentrant (Non Reentrant) spezifiziert ist, muss der Aufrufer sicherstellen, dass keine zeitgleichen oder unterbrechenden Aufrufe stattfinden [SWS_KeyM_00060]. Nach erfolgreicher Annahme des Prüfauftrags (Rückgabe E_OK) wird das Ergebnis der Hintergrundoperation an die konfigurierte Callback-Funktion KeyMCertificateVerifyCallbackNotificationFunc übermittelt, sofern diese mit einem gültigen Funktionsnamen versehen ist [SWS_KeyM_00153].

Die Funktion KeyM_VerifyCertificateChain dient der asynchronen Verifizierung eines Zertifikats gegen eine Kette übergebener Zertifikate [SWS_KeyM_00061]. Als Parameter werden die Kennung des letzten Zertifikats der Kette (CertId), ein Zeiger auf das gemäß der PKI-Reihenfolge sortierte Zertifikatsarray (certChainData) sowie die Anzahl der Zertifikate (NumberOfCertificates) übergeben [SWS_KeyM_00061]. Vor dem Aufruf muss das zu prüfende Zertifikat über KeyM_SetCertificate() eingetragen worden sein, und das Root-Zertifikat muss entweder in der Liste enthalten oder bereits einem der anderen Zertifikate zugewiesen sein [SWS_KeyM_00061].

Die Funktion ist nicht reentrant (Non Reentrant) und wird über die Header-Datei KeyM.h bereitgestellt [SWS_KeyM_00061]. Folgende synchrone Rückgabewerte zeigen den Status der Auftragsannahme an [SWS_KeyM_00061]:

• E_OK: Der Prüfauftrag wurde akzeptiert und wird im Hintergrund ausgeführt [SWS_KeyM_00061].
• E_NOT_OK: Der Auftrag wurde aufgrund eines internen Fehlers abgelehnt [SWS_KeyM_00061].
• KEYM_E_BUSY: Das Modul ist mit anderen Aufträgen ausgelastet; die Validierung kann noch nicht ausgeführt werden [SWS_KeyM_00061].
• KEYM_E_PARAMETER_MISMATCH: Die übergebene Zertifikats-ID ist ungültig [SWS_KeyM_00061].
• KEYM_E_KEY_CERT_EMPTY: Einer der benötigten Zertifikats-Slots ist leer [SWS_KeyM_00061].
• KEYM_E_CERT_INVALID_CHAIN_OF_TRUST: Ein übergeordnetes Zertifikat in der Vertrauenskette ist ungültig [SWS_KeyM_00061].

Wurde der Auftrag mit E_OK angenommen, erfolgt die Auswertung im Hintergrund. Sofern KeyMCertificateVerifyCallbackNotificationFunc mit einer gültigen Funktion konfiguriert ist, meldet KeyM das Endergebnis der Verifizierungsoperation über diese Callback-Funktion an die aufrufende Anwendung zurück [SWS_KeyM_00061] [SWS_KeyM_00153].

Verwendung und Aufrufkontext

Die synchrone Funktion KeyM_CertElementGet dient dem Auslesen der Daten eines spezifischen Zertifikatselements aus einem Zertifikatsslot in einen vom Aufrufer bereitgestellten Puffer [SWS_KeyM_00063]. Sie kommt zum Einsatz, wenn der in der Zertifikatskonfiguration hinterlegten Objektkennung (OID) genau ein einzelnes Element zugeordnet ist [SWS_KeyM_00063].

Der Aufrufer übergibt die Zertifikatskennung CertId, die Elementkennung CertElementId sowie einen Zeiger auf den Zielpuffer CertElementData [SWS_KeyM_00063]. Der Parameter CertElementDataLength dient als kombinierter Ein- und Ausgabewert: Vor dem Aufruf muss er die maximale Puffergröße enthalten. Im Erfolgsfall (E_OK) wird er mit der tatsächlichen Länge der geschriebenen Daten überschrieben; im Fehlerfall setzt die Funktion den referenzierten Wert auf null zurück [SWS_KeyM_00063].

Fehlerbehandlung und Rückgabewerte

Die Funktion meldet den Ausführungsstatus über folgende Rückgabewerte [SWS_KeyM_00063]:

• E_OK: Das Element wurde gefunden und erfolgreich in den Puffer kopiert [SWS_KeyM_00063].
• E_NOT_OK: Die Elementdaten wurden nicht gefunden [SWS_KeyM_00063].
• KEYM_E_PARAMETER_MISMATCH: Ungültige CertId oder CertElementId [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Der bereitgestellte Puffer ist zu klein für die Daten des Elements [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_EMPTY: Für den angegebenen Slot existieren keine Daten, der Slot ist leer [SWS_KeyM_00063].
• KEYM_E_KEY_CERT_INVALID: Das Zertifikat ist ungültig oder wurde noch nicht verifiziert [SWS_KeyM_00063].

Nebenläufigkeit

Die Funktion ist als nicht reentrant (Non Reentrant) spezifiziert [SWS_KeyM_00063]. Bei nebenläufigen Aufrufen aus verschiedenen Tasks oder Kontexten dürfte daher eine aufruferseitige Synchronisation erforderlich sein. Frage Q-238a3e53ce0e3a45 (offen)

Die synchrone Funktion KeyM_CertificateElementGetByIndex dient dem gezielten Auslesen von Daten eines Zertifikatselements anhand eines nullbasierten Index (0..N), wenn für einen Elementtyp mehrere Einträge vorliegen [SWS_KeyM_91014]. Sie stellt damit eine Direktzugriffsalternative zur sequentiellen Iteration dar.

Verwendung und Parameter

Der Aufrufer übergibt die Zertifikatskennung CertId, die Elementkennung CertElementId sowie den gewünschten Index [SWS_KeyM_91014]. Zudem muss der Aufrufer den Speicher für CertElementDataPtr allokieren und über CertElementDataLengthPtr die maximal verfügbare Puffergröße übergeben. Bei erfolgreicher Rückgabe wird CertElementDataLengthPtr mit der tatsächlichen Länge der kopierten Daten überschrieben [SWS_KeyM_91014].

Rückgabewerte und Fehlerbehandlung

Die Funktion signalisiert das Ergebnis über spezifische Std_ReturnType-Rückgabewerte [SWS_KeyM_91014]:

• E_OK: Das Element wurde gefunden und erfolgreich in den Zielpuffer kopiert.
• KEYM_E_PARAMETER_MISMATCH: Ungültige CertId, ungültige CertElementId oder der übergebene Index liegt außerhalb des gültigen Bereichs.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Der bereitgestellte Puffer ist zu klein für das Zertifikatselement.
• KEYM_E_KEY_CERT_EMPTY: Das angegebene Zertifikat enthält keine Daten bzw. ist leer.
• KEYM_E_CERT_INVALID: Das Zertifikat ist ungültig oder die Verifikation war nicht erfolgreich.
• E_NOT_OK: Das Auslesen der Elementdaten ist fehlgeschlagen.

Nebenläufigkeit

Gemäß Spezifikation ist der Dienst als nicht reentrant (Non Reentrant) eingestuft [SWS_KeyM_91014]. Aufrufe dürfen daher nicht ungeschützt nebenläufig ausgeführt werden.

Die synchrone Schnittstelle KeyM_CertificateElementGetCount ermittelt die Gesamtanzahl an Datenelementen, die für ein spezifisches Zertifikatselement hinterlegt sind, und schreibt das Ergebnis in den Puffer CountPtr [SWS_KeyM_91015].

Verwendung und Parameter

Die Funktion wird über den Header KeyM.h deklariert und besitzt die Service-ID 0x1c [SWS_KeyM_91015]. Sie verarbeitet folgende Parameter:

• CertId (IN): Eindeutige Kennung des abzufragenden Zertifikats ([SWS_KeyM_91015]).
• CertElementId (IN): Bestimmt das konkrete Element innerhalb des Zertifikats ([SWS_KeyM_91015]).
• CountPtr (OUT): Zeiger auf den Puffer vom Typ uint16, in welchen die Anzahl der verfügbaren Datenelemente kopiert wird ([SWS_KeyM_91015]).

Fehlerbehandlung und Rückgabewerte

Der Rückgabewert vom Typ Std_ReturnType gibt Auskunft über das Ergebnis der Ausführung [SWS_KeyM_91015]:

• E_OK: Der Zählwert wurde erfolgreich in den Puffer geschrieben ([SWS_KeyM_91015]).
• E_NOT_OK: Der Zählwert konnte nicht bereitgestellt werden ([SWS_KeyM_91015]).
• KEYM_E_PARAMETER_MISMATCH: Die Zertifikats-ID (CertId) oder die Element-ID (CertElementId) ist ungültig oder liegt außerhalb des zulässigen Bereichs ([SWS_KeyM_91015]).

Nebenläufigkeit und Zusammenspiel

Die Ausführung ist synchron, jedoch als nicht reentrant (Non Reentrant) eingestuft, sodass gleichzeitige Aufrufe koordiniert werden müssen [SWS_KeyM_91015]. Während Zertifikatselementen typischerweise nur ein einzelnes Datenelement zugewiesen ist, können in bestimmten Fällen mehrere Datenelemente hintereinander vorliegen [SWS_KeyM_91015]. Die ermittelte Gesamtzahl dient als Grundlage, um die einzelnen Elemente anschließend gezielt über KeyM_CertificateElementGetByIndex() auszulesen, was funktional dem iterativen Ansatz mit KeyM_CertElementGetFirst und KeyM_CertElementGetNext ähnelt [SWS_KeyM_91015].

Die synchrone Funktion KeyM_CertElementGetFirst dient gemäß [SWS_KeyM_00064] dazu, die iterative Extraktion von Zertifikatsdaten einzuleiten. Sie liest das oberste Element des über CertElementId adressierten Zertifikatselements aus dem Zertifikat CertId aus und initialisiert die Iteratorkonstruktion CertElementIterator für nachfolgende Aufrufe von KeyM_CertElementGetNext().

Beim Aufruf sind folgende Parameter- und Speicheranforderungen nach [SWS_KeyM_00064] zu beachten:

• CertElementIterator: Zeiger auf eine vom Aufrufer allozierte und verwaltete Struktur; diese darf von der Applikation weder zerstört noch verändert werden, solange nicht alle Daten über KeyM_CertElementGetNext() abgerufen wurden.
• CertElementData: Zeiger auf einen vom Aufrufer bereitgestellten Ausgabepuffer, in den bei erfolgreichem Auffinden (E_OK) die Nutzdaten kopiert werden.
• CertElementDataLength: Übergibt als Eingabe die Maximallänge des Datenpuffers und wird bei Rückgabe von E_OK mit der tatsächlich geschriebenen Datenlänge überschrieben.

Hinsichtlich Nebenläufigkeit ist der Service laut [SWS_KeyM_00064] reentrant, jedoch bezogen auf genau einen Iterator („Reentrant for one iterator“).

Im Fehlerfall differenziert die Funktion über spezifische Rückgabewerte gemäß [SWS_KeyM_00064]: E_NOT_OK zeigt an, dass keine Elementdaten gefunden wurden (der Iterator darf danach nicht für weitere Aufrufe verwendet werden). KEYM_E_PARAMETER_MISMATCH signalisiert eine ungültige Zertifikats- oder Element-ID, KEYM_E_KEY_CERT_SIZE_MISMATCH einen zu kleinen Datenpuffer, KEYM_E_KEY_CERT_EMPTY ein leeres Zertifikat ohne verfügbare Daten und KEYM_E_CERT_INVALID ein ungültiges oder nicht erfolgreich verifiziertes Zertifikat.

Die synchrone Funktion KeyM_CertElementGetNext (Service-ID 0x11, bereitgestellt über KeyM.h) dient dem fortlaufenden Auslesen weiterer Daten aus einem Zertifikatselement, falls darin mehrere Datensätze sequenziell abgelegt sind [SWS_KeyM_00065]. Als zwingende Aufrufbedingung verlangt die Spezifikation, dass zuvor mindestens einmal die Funktion KeyM_CertElementGetFirst() aufgerufen wurde [SWS_KeyM_00065].

Die Speicherbereiche für sämtliche Parameter müssen durch die aufrufende Applikation bereitgestellt werden [SWS_KeyM_00065]:

• CertElementIterator: Zeiger auf eine allokierte Iterator-Struktur, die von der Anwendung während des Durchlaufens weder modifiziert noch zerstört werden darf, bis alle Elemente vollständig ausgelesen sind [SWS_KeyM_00065].
• CertElementData: Zeiger auf den Ausgabepuffer, in welchen die Funktion bei erfolgreicher Ausführung die Nutzdaten kopiert [SWS_KeyM_00065].
• CertElementDataLength: Übergibt beim Aufruf die maximale Kapazität des Datenpuffers und wird bei erfolgreicher Rückgabe mit der tatsächlichen Länge der kopierten Daten überschrieben [SWS_KeyM_00065].

Liefert der Aufruf E_OK, wurde das nächste Element gefunden, in den Puffer geschrieben und der Iterator entsprechend weitergeführt [SWS_KeyM_00065]. Bei E_NOT_OK konnten keine weiteren Elementdaten gefunden werden; in diesem Fall darf der Iterator für keine weiteren Aufrufe mehr genutzt werden [SWS_KeyM_00065]. Fehlersituationen werden über spezifische Rückgabewerte gemeldet: KEYM_E_KEY_CERT_SIZE_MISMATCH zeigt einen zu klein dimensionierten Datenpuffer an, KEYM_E_PARAMETER_MISMATCH eine ungültige Zertifikats- oder Element-ID, KEYM_E_KEY_CERT_EMPTY ein leeres Zertifikat und KEYM_E_CERT_INVALID ein ungültiges oder nicht erfolgreich verifiziertes Zertifikat [SWS_KeyM_00065].

Bezüglich der Nebenläufigkeit ist die synchrone Funktion reentrant für jeweils einen Iterator spezifiziert [SWS_KeyM_00065].

Die synchrone Funktion KeyM_CertGetStatus dient dazu, den Status eines Zertifikats abzufragen und über einen Ausgabeparameter bereitzustellen [SWS_KeyM_00066]. Die Deklaration der Funktion ist über die Header-Datei KeyM.h zugänglich, und dem Dienst ist die hexadezimale Service-ID 0x12 zugewiesen [SWS_KeyM_00066].

Für den Aufruf werden die folgenden Parameter verwendet [SWS_KeyM_00066]:

• CertId (IN): Enthält den Bezeichner des abzufragenden Zertifikats und wird mit dem Datentyp KeyM_CertificateIdType übergeben [SWS_KeyM_00066].
• Status (OUT): Zeiger auf den Speicherbereich vom Typ KeyM_CertificateStatusType, in den die Funktion den ermittelten Status des Zertifikats schreibt [SWS_KeyM_00066].

Der Rückgabewert vom Typ Std_ReturnType informiert über den Ausgang der Statusabfrage [SWS_KeyM_00066]:

• E_OK: Der Zertifikatsstatus wurde erfolgreich ermittelt und bereitgestellt [SWS_KeyM_00066].
• E_NOT_OK: Eine Bereitstellung des Status ist gegenwärtig nicht möglich [SWS_KeyM_00066]. Dies tritt beispielsweise auf, wenn eine ungültige Zertifikats-ID übergeben wird, dokumentiert mit dem Fehlercode KEYM_E_PARAMETER_MISMATCH [SWS_KeyM_00066].

In Bezug auf Ausführung und Nebenläufigkeit verhält sich die Schnittstelle rein synchron und ist als nicht reentrant (Non Reentrant) spezifiziert [SWS_KeyM_00066]. Gleichzeitige Aufrufe über mehrere Ausführungskontexte hinweg sind demnach nicht zulässig. Zusätzliche Ein- und Ausgabeparameter sind für diese Schnittstelle nicht vorgesehen [SWS_KeyM_00066].

Die Funktion KeyM_MainFunction dient als periodische Hauptfunktion für das Classic-AUTOSAR-Modul KeyM [SWS_KeyM_00074]. Gemäß Spezifikation verfügt die Funktion über die Service-ID 0x19 in hexadezimaler Darstellung sowie die Signatur void KeyM_MainFunction (void) [SWS_KeyM_00074]. Aufrufende Instanzen übergeben somit keine Eingabeparameter und erhalten keinen Rückgabewert [SWS_KeyM_00074].

Für die zeitliche Steuerung ist festgelegt, dass die Funktion periodisch gemäß einem definierten Zeitintervall aufzurufen ist [SWS_KeyM_00074]. Als Schnittstellendatei ist die Header-Datei SchM_KeyM.h deklariert [SWS_KeyM_00074]. Daraus ergibt sich die Interpretation: Durch die Bereitstellung über SchM_KeyM.h dürfte der regelmäßige Aufruf der Funktion im Kontext des Basissoftware-Schedulers (SchM) stattfinden [SWS_KeyM_00074]. Frage Q-761ff71812bda3c2 (offen) Zudem dient die zyklische Triggerung vermutlich der internen Bearbeitung zeitabhängiger Abläufe im Modul KeyM.

Hinsichtlich der Fehlerbehandlung und des Fehlerverhaltens sind für diesen Dienst keine Rückgabecodes, Fehlerkonstanten oder Meldungen an DET oder DEM im Spezifikationselement dokumentiert [SWS_KeyM_00074]. Da keine Eingabeparameter existieren, entfällt auch eine Überprüfung von Übergabewerten beim Aufruf [SWS_KeyM_00074].

Verwendung und Aufrufkontext

Die Funktion KeyM_MainBackgroundFunction besitzt die Signatur void KeyM_MainBackgroundFunction(void) und ist unter der Service-ID 0x1a spezifiziert [SWS_KeyM_00075]. Sie nimmt keine Übergabeparameter entgegen und liefert keinen Rückgabewert an den Aufrufer zurück [SWS_KeyM_00075]. Zur Einbindung wird die Schnittstelle über die Header-Datei SchM_KeyM.h deklariert und bereitgestellt [SWS_KeyM_00075].

Der Aufruf erfolgt durch ein präemptives Betriebssystem im Hintergrund, sobald keine sonstige Task-Operation zur Abarbeitung ansteht [SWS_KeyM_00075]. Primärer Zweck dieser Funktion ist die Bereitstellung eines unkritischen Hintergrundkontexts für zeitaufwendige, synchrone Operationen des Moduls KeyM, wie beispielhaft für die Ausführung von KeyM_KH_Update() beschrieben [SWS_KeyM_00075].

Nebenläufigkeit und Fehlerbehandlung

Da die Funktion im Hintergrundkontext eines präemptiven Betriebssystems ausgeführt wird, dürfte sie durch beliebige reguläre, höher priorisierte Tasks jederzeit unterbrechbar sein. Frage Q-a2394a51ba63467f (offen) Für diesen Hintergrunddienst spezifiziert der Standard weder spezifische Fehlercodes noch Benachrichtigungen an das DET oder DEM [SWS_KeyM_00075]. Zudem werden im vorgegebenen Datenstand keine besonderen Reentranz-Eigenschaften oder feste Reihenfolgebedingungen bezüglich anderer Modulfunktionen vorgeschrieben [SWS_KeyM_00075].

Die synchrone und nicht-reentrante Funktion KeyM_KH_Start wird über den Header KeyM_Externals.h deklariert [SWS_KeyM_00067]. Wenn die Konfigurationsparameter KeyMCryptoKeyStartFinalizeFunctionEnabled und KeyMCryptoKeyHandlerStartFinalizeEnabled auf TRUE gesetzt sind, wird sie unmittelbar bei einem Aufruf von KeyM_Start ausgeführt [SWS_KeyM_00067].

Über den Parameter StartType wird der Ausführungsmodus der Schlüsseloperation festgelegt. Mittels RequestData und RequestDataLength empfängt die Funktion anfragespezifische Begleitdaten wie beispielsweise Signaturen. Der Aufrufer übergibt über den Ein-/Ausgabeparameter ResponseDataLength die maximal im Puffer ResponseData verfügbare Bytemenge; im Erfolgsfall meldet die Funktion darüber die tatsächlich geschriebene Anzahl von Antwortbytes zurück [SWS_KeyM_00067].

Als Rückgabewert liefert die Funktion einen Status vom Typ Std_ReturnType [SWS_KeyM_00067]:

• E_OK: Die Start-Operation war erfolgreich. Nur durch diesen Rückgabewert wechselt der Key Manager in den aktiven Zustand, sodass anschließende Schlüsselaktualisierungen (Key Updates) zulässig sind.
• E_NOT_OK: Die Start-Operation wurde nicht akzeptiert.
• KEYM_E_PARAMETER_MISMATCH: Ein übergebener Parameter stimmt nicht mit dem erwarteten Wert überein.
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Eine angegebene Parametergröße passt nicht zur erwarteten Größe.

Da KeyM_KH_Start als nicht-reentrant definiert ist, dürfen Aufrufe für parallele Schlüsseloperationen nicht nebenläufig stattfinden [SWS_KeyM_00067].

Verwendung und Aufrufkontext

Die Funktion KeyM_KH_Prepare wird über die Header-Datei KeyM_Externals.h deklariert und dient der Vorbereitung einer Schlüsselmanagement-Operation [SWS_KeyM_00068]. Sie wird unmittelbar beim Aufruf von KeyM_Prepare angestoßen, wenn die beiden Konfigurationsparameter KeyMCryptoKeyPrepareFunctionEnabled und KeyMCryptoKeyHandlerPrepareEnabled jeweils auf TRUE gesetzt sind [SWS_KeyM_00068]. Die Ausführung erfolgt synchron und ist als nicht reentrant spezifiziert [SWS_KeyM_00068].

Die Datenübergabe erfolgt über vier Parameter [SWS_KeyM_00068]:

• RequestData: Eingangsdaten, die zusammen mit der Anfrage übergeben werden [SWS_KeyM_00068].
• RequestDataLength: Länge der Daten im Array RequestData [SWS_KeyM_00068].
• ResponseDataPtr: Zeiger auf den Puffer für die von der Funktion zurückgegebenen Antwortdaten, welche unverändert an den Aufrufer von Key_Prepare weitergeleitet werden [SWS_KeyM_00068].
• ResponseDataLength: Ein- und Ausgabeparameter; übergibt beim Aufruf die maximal im Puffer verfügbare Bytezahl und liefert nach Rückkehr die tatsächlich geschriebene Bytemenge zurück [SWS_KeyM_00068].

Rückgabewerte und Fehlerverhalten

Die Funktion liefert als Ergebnis den Statuswert Std_ReturnType zurück [SWS_KeyM_00068]:

• E_OK: Der Dienst wurde akzeptiert und wird intern weiterverarbeitet; Resultate werden über einen Callback übermittelt [SWS_KeyM_00068].
• E_NOT_OK: Der Dienst wurde aufgrund eines internen Fehlers nicht akzeptiert [SWS_KeyM_00068].
• KEYM_E_PARAMETER_MISMATCH: Ein Parameter stimmt nicht mit dem erwarteten Wert überein [SWS_KeyM_00068].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Die Größe eines Parameters ist nicht passend [SWS_KeyM_00068].

Verwendung und Delegierung

Die Funktion KeyM_KH_Finalize wird über die Header-Datei KeyM_Externals.h deklariert und fungiert als anwenderspezifischer Key-Handler [SWS_KeyM_00070]. Wenn in der Konfiguration sowohl KeyMCryptoKeyStartFinalizeFunctionEnabled als auch KeyMCryptoKeyHandlerStartFinalizeEnabled auf TRUE gesetzt sind, führt KeyM_Finalize() keine eigenständige Operation aus, sondern delegiert die Verarbeitung unmittelbar an diese Handler-Funktion [SWS_KeyM_00070].

Aufrufkontext und Parameter

Der Aufruf von KeyM_KH_Finalize erfolgt synchron, ist jedoch als nicht reentrant (Non Reentrant) eingestuft und verlangt einen geschützten Aufrufkontext [SWS_KeyM_00070]. Die Datenübergabe erfolgt über folgende Parameter:

• RequestData und RequestDataLength: Zeiger auf die mit der Anfrage übergebenen Eingangsdaten sowie die Länge des Datenarrays [SWS_KeyM_00070].
• ResponseData: Puffer für die von der Funktion bereitgestellten Ausgabedaten [SWS_KeyM_00070].
• ResponseDataLength: Ein In/Out-Parameter, der beim Aufruf die maximal im Antwortpuffer verfügbare Bytemenge vorgibt und bei Rückkehr die tatsächlich geschriebene Bytezahl enthält [SWS_KeyM_00070].

Rückgabewerte und Fehlerbehandlung

Das Operationsergebnis wird über Std_ReturnType zurückgegeben [SWS_KeyM_00070]:

• E_OK: Die Operation wurde akzeptiert und wird intern weiterverarbeitet; die Ergebnisse werden über einen Callback bereitgestellt [SWS_KeyM_00070]. Interpretation: Obwohl die Funktionsschnittstelle als synchron definiert ist, dürfte die tatsächliche Abarbeitung im Hintergrund fortgeführt werden. Frage Q-02c4aac040570c03 (offen)
• E_NOT_OK: Die Operation wurde aufgrund eines internen Fehlers nicht akzeptiert [SWS_KeyM_00070].
• KEYM_E_BUSY: Der Key Manager ist mit anderen Aufgaben ausgelastet, weshalb die Validierung aktuell nicht durchgeführt werden kann [SWS_KeyM_00070].
• KEYM_E_PARAMETER_MISMATCH: Ein Parameter stimmt nicht mit dem erwarteten Wert überein [SWS_KeyM_00070].
• KEYM_E_KEY_CERT_SIZE_MISMATCH: Die übergebene Parametergröße entspricht nicht den Vorgaben [SWS_KeyM_00070].

Die Callback-Funktion KeyM_CryptoKeyUpdateCallbackNotification() benachrichtigt die Anwendung darüber, dass eine Aktualisierung eines kryptografischen Schlüssels abgeschlossen wurde ([SWS_KeyM_00077]). Die Funktion wird über KeyM_Externals.h bereitgestellt, ist synchron und reentrant und besitzt keinen Rückgabewert ([SWS_KeyM_00077]).

Parameter

• Result: Überträgt Informationen über das Ergebnis der Aktualisierungsoperation über den Typ KeyM_ResultType ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataLength: Gibt die Länge der resultierenden Daten dieser Operation an ([SWS_KeyM_00077], [SWS_KeyM_00156]).
• ResultDataPtr: Zeiger auf die Daten des Ergebnisses ([SWS_KeyM_00077]).

Zusammenspiel und Pufferverwaltung

Der Aufruf von KeyM_CryptoKeyUpdateCallbackNotification() erfolgt durch KeyM_Update(), sobald der Key-Handler zurückkehrt und den Operationstyp KEYM_KH_UPDATE_FINISH liefert ([SWS_KeyM_00093]). Dabei werden die Ergebnisdaten aus KeyM_KH_Update::ResultDataPtr in den Puffer kopiert, der beim Aufruf von KeyM_Update() übergeben wurde, und der Rückgabewert des Key-Handlers wird übernommen ([SWS_KeyM_00093]).

Sofern KeyM_Update() den Vorgang mit E_OK akzeptiert hat, darf die aufrufende Funktion den Puffer ResultDataPtr keinesfalls verändern, bis die Callback-Benachrichtigung KeyM_CryptoKeyUpdateCallbackNotification() erfolgt ist ([SWS_KeyM_00156]). Derselbe Pufferzeiger wird im Callback als ResultDataPtr mit den hineinkopierten Operationsergebnissen übergeben ([SWS_KeyM_00156]).

Die Callback-Funktion KeyM_CryptoKeyFinalizeCallbackNotification benachrichtigt die Anwendung über den Abschluss einer Schlüssel-Finalisierungsoperation [SWS_KeyM_00079]. Sie ist als synchron sowie reentrant spezifiziert, besitzt keinen Rückgabewert und wird über die Header-Datei KeyM_Externals.h deklariert [SWS_KeyM_00079].

Die Schnittstelle übergibt beim Aufruf folgende Parameter an die Anwendung [SWS_KeyM_00079]:

• Result (Typ KeyM_ResultType): Übermittelt das Ergebnis und Statusinformationen der abgeschlossenen Operation [SWS_KeyM_00079].
• Result Data Length (Typ uint16): Gibt die Länge der resultierenden Daten dieser Operation an [SWS_KeyM_00079].
• Result Data Ptr (Typ const uint8*): Zeiger auf den Puffer mit den Ergebnisdaten, der der Service-Funktion zuvor bereitgestellt wurde [SWS_KeyM_00079].

Hinsichtlich der Konfiguration wird die Callback-Funktion nur aufgerufen und benötigt, wenn der Konfigurationsparameter KeyMCryptoKeyStartFinalizeFunctionEnabled auf TRUE gesetzt ist [SWS_KeyM_00079]. Spezifische DET- oder DEM-Fehlermeldungen sind für diese Callback-Funktion nicht definiert. Vermutlich implementiert die Anwendung diesen Callback, um die asynchronen Resultate einer zuvor initiierten Schlüssel-Finalisierung entgegenzunehmen. Frage Q-6d9e4e062b008832 (offen)

Verwendung und Parameter

Die Callback-Funktion KeyM_CryptoKeyVerifyCallbackNotification informiert die Applikation über den Abschluss einer Verifikationsoperation für einen kryptografischen Schlüssel durch das Modul KeyM [SWS_KeyM_00081]. Interpretation: Da das Element laut Spezifikation über den Header KeyM_Externals.h zur Verfügung steht und der Benachrichtigung der Applikation dient, dürfte die Implementierung durch die anwendende Softwarekomponente erfolgen, während der Aufruf durch den Key-Manager vorgenommen wird [SWS_KeyM_00081]. Frage Q-e88e332a7d2cac40 (offen)

Für den Aufruf sind vier reine Eingangsparameter definiert [SWS_KeyM_00081]:

• Result (KeyM_ResultType): Übergibt das Ergebnis der abgeschlossenen Verifikation [SWS_KeyM_00081].
• KeyId (uint32): Kennzeichnet die Schlüsselkennung, für welche die Verifikation gestartet wurde [SWS_KeyM_00081].
• ResultDataLength (uint16): Enthält die Länge der resultierenden Ergebnisdaten, sofern vorhanden [SWS_KeyM_00081].
• ResultDataPtr (const uint8*): Zeigt auf die Daten des Verifikationsergebnisses [SWS_KeyM_00081].

Nebenläufigkeit und Einschränkungen

Die Funktion besitzt keinen Rückgabewert (void) sowie weder Ausgangs- noch Ein-/Ausgangsparameter [SWS_KeyM_00081]. Der Aufruf ist synchron und reentrant ausgeführt [SWS_KeyM_00081]. Spezifische Fehlercodes sowie DET- oder DEM-Meldungen sind für diesen Callback nicht spezifiziert; Status- und Fehlerinformationen werden ausschließlich über den Parameter Result an die Applikation übermittelt [SWS_KeyM_00081].

Verwendung und Semantik

Die Callback-Funktion KeyM_ServiceCertificateCallbackNotification wird vom Zertifikats-Submodul des KeyM aufgerufen, um die Anwendung über den Abschluss einer Zertifikatsdienst-Operation zu benachrichtigen [SWS_KeyM_00147]. Die vorausgehende Zertifikatsoperation läuft asynchron ab und führt bei ihrer Beendigung diesen Callback aus, um die Resultate an die Anwendung zu übermitteln [SWS_KeyM_00149].

Über die Funktionsparameter werden alle relevanten Ergebnisdaten übermittelt [SWS_KeyM_00147]:

• CertId: Bezeichner des Zertifikats, für welches die Operation initiiert wurde.
• Result: Typ KeyM_ResultType mit dem Status bzw. Ergebnis der Operation.
• ResultDataLength: Länge der Ergebnisdaten, sofern vorhanden.
• ResultDataPtr: Zeiger auf die Ergebnisdaten.

Die Funktion selbst besitzt keinen Rückgabewert (void) und weist eine synchrone Ausführungssemantik auf [SWS_KeyM_00147].

Konfiguration und Einschränkungen

Der Callback wird über den Header KeyM_Externals.h bereitgestellt, ist jedoch nur verfügbar, wenn der Konfigurationsparameter KeyMServiceCertificateFunctionEnabled auf TRUE gesetzt ist [SWS_KeyM_00147]. Der tatsächliche Name der Benachrichtigungsfunktion ist über den Konfigurationsparameter KeyMServiceCertificateCallbackNotificationFunc anpassbar [SWS_KeyM_00147].

Nebenläufigkeit und Fehlerbehandlung

Gemäß Spezifikation ist die Funktion als reentrant klassifiziert [SWS_KeyM_00147]. Fehler oder Erfolgszustände der vorangegangenen asynchronen Operation werden über den Übergabeparameter Result signalisiert; spezifische DET- oder DEM-Meldungen sind für diese Callback-Schnittstelle im Payload nicht definiert [SWS_KeyM_00147].

Verwendung

Die Callback-Funktion KeyM_CertificateVerifyCallbackNotification dient dazu, die Anwendung über den Abschluss einer Zertifikatsverifizierung zu benachrichtigen [SWS_KeyM_00073]. Die Deklaration ist über den Header KeyM_Externals.h verfügbar, wobei der Funktionsname über den Konfigurationsparameter KeyMCertificateVerifyCallbackNotificationFunc konfiguriert werden kann [SWS_KeyM_00073].

Beim Aufruf werden zwei Eingabeparameter übergeben [SWS_KeyM_00073]:

• CertId (Typ KeyM_CertificateIdType): Bezeichner des verifizierten Zertifikats [SWS_KeyM_00073].
• Result (Typ KeyM_CertificateStatusType): Enthält Informationen über das Ergebnis der Verifizierungsoperation [SWS_KeyM_00073].

Die Funktion gibt als Statuswert vom Typ Std_ReturnType den Wert E_OK zurück [SWS_KeyM_00073].

Ausführung und Fehlerbehandlung

Die Ausführung der Benachrichtigung ist als synchron und reentrant definiert [SWS_KeyM_00073]. Spezifische Fehlercodes, abweichende Rückgabewerte oder Meldungen an DET oder DEM sind für diesen Callback nicht vorgesehen [SWS_KeyM_00073]. Interpretation: Die anwendungsseitige Implementierung dürfte threadsicher ausgelegt sein müssen, um gleichzeitige Aufrufe für unterschiedliche Zertifikate ohne Nebenwirkungen zu verarbeiten. Frage Q-6bf5313c425fe1a8 (offen)

Verwendung

Der Datentyp KeyM_CertElementIteratorType ist gemäß [SWS_KeyM_00042] als Struktur (Structure) definiert und wird über die Header-Datei KeyM.h zur Verfügung gestellt. Gemäß der Spezifikation dient dieser Typ dazu, über eine Reihe von Elementen eines Zertifikats zu iterieren ([SWS_KeyM_00042]). Da der konkrete Inhalt der Datenstruktur ausdrücklich als implementierungsspezifisch festgelegt ist ([SWS_KeyM_00042]), dürften Anwender den Typ als opaken Iterationszustand betrachten und nicht direkt auf interne Strukturfelder zugreifen. Frage Q-81b5deb7dcdf2812 (offen)

Handhabung und Einschränkungen

Aus der Spezifikation ergeben sich folgende praktische Rahmenbedingungen für die Nutzung:

• Implementierungsspezifischer Aufbau: Da die Felder von KeyM_CertElementIteratorType herstellerspezifisch implementiert werden ([SWS_KeyM_00042]), hängt das interne Speicher-Layout von der jeweiligen BSW-Realisierung ab.
• Zustandsverwaltung: Interpretation: Eine Instanz der Struktur dürfte vom Aufrufer als Iteratorkontext allokiert und an die entsprechenden Funktionen zur Zertifikatselement-Traversierung übergeben werden, um den Fortschritt bei der Prüfung oder Extraktion von Zertifikatsfeldern zu verfolgen. Frage Q-5ddb438001abe656 (offen)
• Nebenläufigkeit: Vermutlich ist eine Iteratorinstanz nicht nebenläufig ohne externe Synchronisation über mehrere Tasks hinweg nutzbar, wenn parallele Zugriffe auf dasselbe Zertifikat erfolgen. Frage Q-6b4b8b1cdc35f021 (offen)

Der Enumerationstyp KeyM_ServiceCertificateType wird über den Header Rte_KeyM_Type.h bereitgestellt und spezifiziert die vom Key-Server angeforderte Zertifikats-Dienstoperation sowie die Art der mit der Funktion übergebenen Informationen [SWS_KeyM_00039]. Die Deklaration in der RTE-Header-Datei dürfte darauf hinweisen, dass der Typ vor allem im Datenaustausch zwischen Software-Komponenten und dem Key-Manager-Modul zur Anwendung kommt. Frage Q-37ed693ea3eda646 (offen)

Folgende standardisierte Operationscodes sind für das Zertifikatsmanagement definiert [SWS_KeyM_00039]:

• KEYM_SERVICE_CERT_REQUEST_CSR (0x01): Der Key-Server fordert den Key-Client auf, ein Zertifikat bzw. einen Zertifikatsantrag (CSR) zu generieren [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_SIGNED_CSR (0x02): Der Server gibt ein zuvor empfangenes, inzwischen durch die Zertifizierungsstelle (CA) signiertes Zertifikat zurück [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_ROOT (0x03) und KEYM_SERVICE_CERT_UPDATE_ROOT (0x04): Anlegen eines neuen oder Aktualisieren eines bestehenden Root-Zertifikats [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_SET_INTERMEDIATE (0x05) und KEYM_SERVICE_CERT_UPDATE_INTERMEDIATE (0x06): Hinzufügen oder Aktualisieren eines Zwischenzertifikats (CA-Zertifikat) [SWS_KeyM_00039].
• KEYM_SERVICE_CERT_UPDATE_CRL (0x07): Bereitstellen oder Aktualisieren einer Zertifikatssperrliste (CRL) [SWS_KeyM_00039].

Als wesentliche Vorbedingung verlangt KEYM_SERVICE_CERT_SET_INTERMEDIATE, dass vor dem Setzen eines Zwischenzertifikats bereits das zugehörige Root-Zertifikat hinterlegt sein muss, um eine erfolgreiche Verifikation zu gewährleisten [SWS_KeyM_00039]. Für projektspezifische Erweiterungen sieht die Spezifikation den reservierten Wertebereich von 0x80 bis 0x9F vor [SWS_KeyM_00039].

Der Aufzählungstyp KeyM_CertificateStatusType repräsentiert das Ergebnis von Zertifikatsprüfungen und bildet den aktuellen Verifikations- und Verarbeitungsstatus eines Zertifikats im Key Manager ab [SWS_KeyM_91003]. Der Typ wird über den Header Rte_KeyM_Type.h bereitgestellt und dient Aufrufern dazu, den Zustand oder spezifische Fehlerursachen einer Zertifikatsverifikation differenziert auszuwerten [SWS_KeyM_91003].

Die Enumerationswerte decken sowohl reguläre Zwischen- und Erfolgszustände als auch präzise Fehlerbilder ab [SWS_KeyM_91003]:

• KEYM_CERTIFICATE_VALID (0x00): Das Zertifikat wurde erfolgreich geparst und verifiziert [SWS_KeyM_91003].
• KEYM_CERTIFICATE_INVALID (0x01): Das Zertifikat ist ungültig aufgrund eines nicht näher spezifizierten Fehlers [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_PARSED (0x02): Das Zertifikat wurde bislang noch nicht geparst [SWS_KeyM_91003].
• KEYM_CERTIFICATE_PARSED_NOT_VALIDATED (0x03): Das Zertifikat wurde geparst, aber noch nicht validiert [SWS_KeyM_91003].
• KEYM_CERTIFICATE_NOT_AVAILABLE (0x04): Es ist kein Zertifikat gesetzt [SWS_KeyM_91003].
• Fehlerspezifische Prüfergebnisse: Fehlgeschlagene Gültigkeitsdauer (KEYM_E_CERTIFICATE_VALIDITY_PERIOD_FAIL, 0x05), fehlerhafte Signatur (KEYM_E_CERTIFICATE_SIGNATURE_FAIL, 0x06), ungültige Vertrauenskette (KEYM_E_CERTIFICATE_INVALID_CHAIN_OF_TRUST, 0x07), ungültiger Typ (KEYM_E_CERTIFICATE_INVALID_TYPE, 0x08), fehlerhaftes Format (KEYM_E_CERTIFICATE_INVALID_FORMAT, 0x09), ungültiger Inhalt (KEYM_E_CERTIFICATE_INVALID_CONTENT, 0x0A) sowie Widerruf bzw. ungültiger Gültigkeitsbereich (KEYM_E_CERTIFICATE_REVOKED, 0x0B) [SWS_KeyM_91003].

Aufrufer sollten den Status vor der Verwendung kryptografischer Schlüssel prüfen; Operationen dürfen typischerweise nur dann auf einem Zertifikat aufsetzen, wenn der Status explizit KEYM_CERTIFICATE_VALID signalisiert. Da der Typ über Rte_KeyM_Type.h deklariert wird, dürfte er vorrangig in standardisierten Service-Schnittstellen und Ports zur Interaktion zwischen KeyM und Applikations-SWCs eingesetzt werden. Frage Q-f3ca10ee673798df (offen)

Verwendung und Struktur

Der Datentyp KeyM_CertificateElementType ist als Byte-Array mit dem Elementtyp uint8 spezifiziert und dient laut Spezifikation als ausreichend großer Speicherbereich zur Ablage von Daten eines Zertifikatselements [SWS_KeyM_91004]. Die Bereitstellung und Deklaration des Datentyps erfolgt für das Modul KeyM über die Headerdatei Rte_KeyM_Type.h [SWS_KeyM_91004].

Konfiguration und Variantenbildung

Die Ausprägung des Datentyps unterliegt einer konfigurationsabhängigen Namens- und Größenvariation, die aus den konfigurierten Parametern des Moduls abgeleitet wird [SWS_KeyM_91004]:

• Namensmuster: Der konkrete Typname wird elementspezifisch nach dem Schema KeyM_CertificateElementType_{KeyMCertificate}_{KeyMCertificateElement} erzeugt, wobei die Platzhalter den konfigurierten Kurznamen SHORT-NAME der jeweiligen Instanzen von Zertifikat und Zertifikatselement entsprechen [SWS_KeyM_91004].
• Array-Größe: Die Anzahl der uint8-Elemente wird durch den Konfigurationsparameter KeyMCertificateElementMaxLength bestimmt, damit das Array ausreichend Speicherplatz für die Rohdaten des jeweiligen Elements bietet [SWS_KeyM_91004].

Einschränkungen und Annahmen

Da die Definition in Rte_KeyM_Type.h bereitgestellt wird, dürfte der Typ primär als standardisierter Puffer an den Schnittstellen zu Software-Komponenten für den Austausch von Zertifikatsinhalten verwendet werden [SWS_KeyM_91004]. Frage Q-994f8ac6772de3c1 (offen) Die maximal verarbeitbare Datenlänge bleibt dabei statisch an die zur Konfigurationszeit definierte Maximallänge gebunden [SWS_KeyM_91004].

Verwendung und Typdefinition

Der Datentyp KeyM_CryptoKeyDataType ist als Zeigertyp auf uint8* definiert und dient als Byte-Zeiger für Eingabe- oder Ausgabedaten innerhalb des Moduls KeyM [SWS_KeyM_91012]. Die Typdefinition wird über die Header-Datei Rte_KeyM_Type.h bereitgestellt [SWS_KeyM_91012].

Einschränkungen und Speicherverwaltung

Bei der Verwendung von KeyM_CryptoKeyDataType als Zeiger auf Byte-Puffer sind spezifische Randbedingungen zu beachten:

• Interpretation: Da der Typ als einfacher Byte-Zeiger (uint8*) spezifiziert ist [SWS_KeyM_91012], obliegt die Allokation, Dimensionierung sowie die Gültigkeit des referenzierten Speichers vermutlich dem jeweiligen Aufrufer. Frage Q-07c167f400cbfb9c (offen)
• Interpretation: Bei der Übergabe als Ausgabepuffer dürfte sicherzustellen sein, dass der referenzierte Speicherbereich groß genug für die aufzunehmenden Schlüssel- bzw. Krypto-Daten ist, um Pufferüberläufe zu verhindern. Frage (offen)
• Interpretation: Für den nebenläufigen Zugriff auf den referenzierten Puffer dürften zusätzliche Synchronisationsmaßnahmen durch die aufrufende Software erforderlich sein, da der Typ selbst keinen Synchronisationsmechanismus bietet. Frage (offen)

Integration

Aufrufer, die Kryptoschlüssel- oder Zertifikatsdaten an KeyM-Schnittstellen übergeben oder von diesen empfangen, binden Rte_KeyM_Type.h ein, um Zugriff auf die typisierte Zeigerdefinition von KeyM_CryptoKeyDataType zu erhalten [SWS_KeyM_91012].

Der Enumerationstyp KeyM_ResultType spezifiziert das Ergebnis von asynchronen Funktionen des Moduls KeyM zur Schlüssel- und Zertifikatsverwaltung [SWS_KeyM_91008]. Der Typ wird über die Header-Datei Rte_KeyM_Type.h bereitgestellt und dient der Rückmeldung über den Ausgang eines angeforderten asynchronen Arbeitsauftrags [SWS_KeyM_91008].

Der Wertebereich umfasst standardisierte Status- und Fehlercodes zur differenzierten Auswertung durch Aufrufer [SWS_KeyM_91008]:

• KEYM_RT_OK (0x00): Die Schlüsselmanagement-Operation wurde erfolgreich abgeschlossen [SWS_KeyM_91008].
• KEYM_RT_NOT_OK (0x01): Während der Schlüsselmanagement-Operation ist ein allgemeiner Fehler aufgetreten [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_INVALID (0x02): Der referenzierte Schlüssel oder das Zertifikat ist ungültig und kann nicht für die Operation genutzt werden [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_WRITE_FAIL (0x03): Das Schreiben des Schlüssels oder Zertifikats in den vorgesehenen Zielspeicher ist fehlgeschlagen [SWS_KeyM_91008].
• KEYM_RT_KEY_CERT_UPDATE_FAIL (0x04): Allgemeiner Fehler bei der Aktualisierung eines Schlüssels oder Zertifikats, der nicht durch einen spezifischeren Code präzisiert werden konnte [SWS_KeyM_91008].
• KEYM_RT_CERT_INVALID_CHAIN_OF_TRUST (0x05): Die Zertifikatsverifikation schlug aufgrund einer ungültigen Vertrauenskette fehl [SWS_KeyM_91008].

Aufrufer asynchroner KeyM-Funktionen müssen diesen Rückgabetyp auswerten, um im Fehlerfall gezielt auf ungültige Vertrauensketten, Speicherzugriffsfehler oder inkorrektes Schlüsselmaterial reagieren zu können [SWS_KeyM_91008].

Die Struktur KeyM_CertDataType wird im Modul KeyM zur Übergabe und zum Austausch von Zertifikatsdaten über Schnittstellenfunktionen eingesetzt [SWS_KeyM_00041]. Die Typdefinition ist über die Header-Datei KeyM.h verfügbar [SWS_KeyM_00041].

Die Struktur bündelt zwei wesentliche Elemente [SWS_KeyM_00041]:

• certDataLength: Element vom Typ uint32, das die Länge der Zertifikatsdaten angibt [SWS_KeyM_00041].
• certData: Element vom Typ VoidPtr, das als Zeiger direkt auf die Zertifikatsdaten in einem lokalen Datenbereich des Aufrufers referenziert [SWS_KeyM_00041].

Da certData auf Speicherbereiche im lokalen Kontext des Aufrufers verweist [SWS_KeyM_00041], obliegt die Pufferverwaltung der aufrufenden Instanz. Interpretation: Der Aufrufer dürfte gewährleisten müssen, dass der referenzierte Speicher für die gesamte Ausführungsdauer der jeweiligen Schnittstellenfunktion gültig bleibt und mindestens die in certDataLength angegebene Bytezahl umfasst. Frage Q-7da9d5ed0975ddbd (offen) Zudem dürfte vermutet werden, dass bei einer Länge größer null ein gültiger Zeiger ungleich NULL übergeben werden muss, um fehlerhafte Speicherzugriffe innerhalb der Schnittstellenfunktion zu vermeiden.