From 06e439a99cbb8f336af846fee56c87463d55dacc Mon Sep 17 00:00:00 2001 From: Zoran Cutura Date: Mon, 7 Jul 2025 12:57:14 +0000 Subject: [PATCH 1/5] some_ip_gateway: overview SOME/IP gateway some_ip_gateway: corrected bullet list corrected the bullet list in the abstract some_ip_gateway: more detailed architecture added a deeper overview on architecture and discussion about introduction of additional processes and communication channel between SOME/IP service and rest of gateway. some_ip_gateway: added architecture drawings added overview drawing on SOME/IP gateway added draft of drawing on detailed architecture some_ip_gateway: adapted references to requirements added references to communication requirements that shall be fulfilled. some_ip_gateway: adding references to existing requirements added references to requirements from IPC. some_ip_gateway: Cleanup after rebase now building with github_plages__release target. Some referred requirements are not in IPC any more and need to be replaced. Commented out! some_ip_gateway: initial draft Drafting the SOME-IP-Gateway feature in very first version extending first draft of some/ip gateway Added more standard chapters Added Rationale paragraph started adding security topics docs dont build yet removing problems when building docs. Still does not build renamed directory to match s-core constraints adapted Specs for plug-in --- docs/features/communication/index.rst | 1 + .../some_ip_gateway/architecture/index.rst | 57 ++ .../some_ip_gateway_architecture.drawio.svg | 439 ++++++++++++++ .../some_ip_gateway_details.drawio.svg | 552 ++++++++++++++++++ .../communication/some_ip_gateway/index.rst | 136 +++++ .../some_ip_gateway/requirements/index.rst | 50 ++ 6 files changed, 1235 insertions(+) create mode 100644 docs/features/communication/some_ip_gateway/architecture/index.rst create mode 100644 docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_architecture.drawio.svg create mode 100644 docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_details.drawio.svg create mode 100644 docs/features/communication/some_ip_gateway/index.rst create mode 100644 docs/features/communication/some_ip_gateway/requirements/index.rst diff --git a/docs/features/communication/index.rst b/docs/features/communication/index.rst index f432f03ba7e..5270d68d46b 100644 --- a/docs/features/communication/index.rst +++ b/docs/features/communication/index.rst @@ -30,6 +30,7 @@ Communication docs/**/index ipc/index + some_ip_gateway/index Feature flag ============ diff --git a/docs/features/communication/some_ip_gateway/architecture/index.rst b/docs/features/communication/some_ip_gateway/architecture/index.rst new file mode 100644 index 00000000000..2ee6edec76b --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/index.rst @@ -0,0 +1,57 @@ +.. + # ******************************************************************************* + # Copyright (c) 2024 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _some_ip_gateway_architecture: + +SOME/IP Gateway Architecture +############################ + +.. note:: + For now we store the component architecture in the feature tree, because multi-repo docs are not yet supported. + Once this support becomes available the component architecture will be moved to the module. + +.. toctree:: + :titlesonly: + +SOME/IP Gateway on one side is a regular participant in IPC and uses the according mechanisms to publish +data or to subscribe to data. As such it will need to know and understand the data types that are used in +the IPC network. + +It also is a participant in the SOME/IP network and provides services for the service oriented communication. +This shall be possible by including SOME/IP stacks that are AUTOSAR compliant. + +There need to be some components between the two communication networks as data types and their according representations and +transmission cadence can be different. Translation of data types could be handled in some translation module +that might be independent of the rest of the gateway. But buffering / queuing of messages, events, signals +should be mostly freely programmable by integrators using the SOME/IP gateway. + + +.. figure:: some_ip_gateway_architecture.drawio.svg + :align: center + :name: _some_ip_gateway_architecture + + General overview of SOME/IP Gateway + + +SOME/IP stacks as supplied by AUTOSAR vendors mostly are available as QM only. +In the case that SOME/IP implementations are not developed under ASIL-B constraints, adequate measures need to be taken to +separate this QM component from the otherwise ASIL-B compliant components. This may be achieved through separate processes, +which again will require dedicated inter-process-communication between the SOME/IP-stack and the rest of the gateway. +It is preferred to avoid such additional IPC. + +.. figure:: some_ip_gateway_details.drawio.svg + :align: center + :name: _some_ip_gateway_details + + Detailed components view of SOME/IP Gateway diff --git a/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_architecture.drawio.svg b/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_architecture.drawio.svg new file mode 100644 index 00000000000..b0c8ee75fff --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_architecture.drawio.svg @@ -0,0 +1,439 @@ + + + + + + + + + + + + + + + + +
+
+
+ IPC +
+ mw::com +
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ + SOME/IP Gateway + +
+
+
+ + + SOME/IP Gateway + + + + + + + + + + + +
+
+
+ Gateway Logic & Configuration +
+
+
+ + + Gateway Logic & Configuration + + + + + + + + + + + +
+
+
+ SOME/IP +
+ communication +
+ stack +
+
+
+
+ + + SOME/IP... + + + + + + + + + + + +
+
+
+ End-to-End +
+ protection +
+
+
+ + + End-to-End... + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ Payload Transformation +
+
+
+ + + Payload Transformation + + + + + + + + + + + + + + + + +
+
+
+ SOME/IP Gateway is a regular IPC participant - +
+ it publishes data and subscribes to data exchanged on IPC +
+
+
+ + + SOME/IP Gateway is a regu... + + + + + + + + + + + + +
+
+
+ SOME/IP Gateway is a single process on the operating system and may be part of other frameworks, ie. FEO +
+
+
+ + + SOME/IP Gateway is... + + + + + + + + + + + + + + + + + + + + +
+
+
+ Gateway Logic configures IPC participation with events, signals, messages tobe received from IPC and sent to SOME/IP network. +
+ Vice versa it passed events, signals, messages from the network to IPC. +
+
+
+ + + Gateway Logic configures I... + + + + + + + + + + + + + + + + +
+
+
+ Implementation of services for communication on the network + + %3CmxGraphModel%3E%3Croot%3E%3CmxCell%20id%3D%220%22%2F%3E%3CmxCell%20id%3D%221%22%20parent%3D%220%22%2F%3E%3CmxCell%20id%3D%222%22%20value%3D%22SOME%2FIP%20Gateway%20is%20a%20single%20process%20on%20the%20operating%20system%20and%20may%20be%20part%20of%20other%20frameworks%2C%20ie.%20FEO%22%20style%3D%22whiteSpace%3Dwrap%3Bhtml%3D1%3Bshape%3Dmxgraph.basic.document%22%20vertex%3D%221%22%20parent%3D%221%22%3E%3CmxGeometry%20x%3D%22600%22%20y%3D%22370%22%20width%3D%22110%22%20height%3D%22140%22%20as%3D%22geometry%22%2F%3E%3C%2FmxCell%3E%3C%2Froot%3E%3C%2FmxGraphModel%3E + +
+
+
+ + + Implementation of... + + + + + + + + + + + + + + + + +
+
+
+ Baselib with polynoms for E2E-protection +
+
+
+ + + Baselib with polyn... + + + + + + + + + + + + + + + + +
+
+
+ translates complex data type representation +
+
+
+ + + translates complex... + + + + + + + + + + Text is not SVG - cannot display + + + + diff --git a/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_details.drawio.svg b/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_details.drawio.svg new file mode 100644 index 00000000000..699817d6a9b --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_details.drawio.svg @@ -0,0 +1,552 @@ + + + + + + + + + + + + + + + + + + + + + +
+
+
+ SOME/IP Gateway +
+
+
+ + + SOME/IP Gateway + + + + + + + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ Gateway Logic & Configuration +
+
+
+ + + Gateway Logic & Configuration + + + + + + + + + + + + + + +
+
+
+ SOME/IP +
+ + communication + +
+ + stack + +
+
+
+
+ + + SOME/IP... + + + + + + + + + + + +
+
+
+ End-to-End +
+ protection +
+ PlugIn +
+
+
+ + + End-to-End... + + + + + + + + + + + +
+
+
+ Payload Transformation +
+
+
+ + + Payload Transformation + + + + + + + + + + + +
+
+
+ Payload Transformation +
+ PlugIn +
+
+
+ + + Payload Transformati... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ IFC +
+
+
+ + + IFC + + + + + + + + + + + +
+
+
+ IFC +
+
+
+ + + IFC + + + + + + + + + + + +
+
+
+ IFC +
+
+
+ + + IFC + + + + + + + + + + + +
+
+
+ IFC = Interface +
+
+
+ + + IFC = Interface + + + + + + + + + + + +
+
+
+ IFC +
+
+
+ + + IFC + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ AUTOSAR code +
+
+
+ + + AUTOSAR code + + + + + + + + + + + +
+
+
+ IPC +
+ participant +
+
+
+
+ + + IPC... + + + + + + + + + + + +
+
+
+ << QM Process >> + + + 1..n +
+
+
+ + + << QM Process >> 1..n + + + + + + + + + + + +
+
+
+ << ASIL Process >>  1..n +
+
+
+ + + << ASIL Process >>  1..n + + + + + + + + + + + + + + + + + + + + + + + +
+
+
+ Payload Transformation +
+ Code Generator +
+
+
+ + + Payload Transformati... + + + + + + + + + + + + +
+
+
+ SOME/IP interface description +
+
+
+ + + SOME/IP int... + + + + + + + + + + + + + + + + +
+
+
+ mw:com +
+ + interface description (headers) + +
+
+
+
+ + + mw:com... + + + + + + + + + + + + + + Text is not SVG - cannot display + + + + diff --git a/docs/features/communication/some_ip_gateway/index.rst b/docs/features/communication/some_ip_gateway/index.rst new file mode 100644 index 00000000000..b43996b99c3 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/index.rst @@ -0,0 +1,136 @@ +.. + # ******************************************************************************* + # Copyright (c) 2024 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _some_ip_gateway_feature: + +SOME/IP-Gateway +########################### + +.. document:: SOME_IP-Gateway + :id: doc__some_ip_gateway + :status: valid + :safety: ASIL_B + :tags: contribution_request, feature_request + + +.. toctree:: + :hidden: + + architecture/index.rst + requirements/index.rst + + +Feature flag +============ + +To activate this feature, use the following feature flag: + +``experimental_some-ip-gateway`` + +Abstract +======== + +This contribution describes how data-exchange that is outside the scope of internal communication (IPC) shall be handled in modules that service data-input and data-output to a platform. +Services handling data in this context can be considered as gateways. +The focus is on a gateway to handle SOME/IP communication with external devices or counterparts, therefore this feature request is called: SOME/IP-Gateway + +This feature request includes: + - A description of how a SOME/IP gateway service (or data broker) shall be implemented + - How the SOME/IP gateway services shall integrate with the zero-copy communication from IPC (which might become a general description of how services plug-in to the IPC context) + - How data shall be mapped or translated between SOME/IP protocol and IPC communication + +.. _Motivation: + +Motivation +========== + +S-CORE is targeting high-performance automotive systems with safety impact. Applications integrated on S-CORE will be distributed across multiple processes and frameworks (like FEO) +that schedule software components (i.e. activities) with the need to exchange data. +For data-exchange between applications the IPC feature is providing high-speed communication capabilities, but when it comes to communication with applications outside the scope of +the S-CORE platform, services are required that will handle protocols for communication with both side. This is for instance the case when communication with rest of vehicle or sensors +needs to be realized with the SOME/IP protocol. + +For software component developers it should be unrecognized that data is originated from a SOME/IP communication channel, the data should be provided with the same API as in IPC. +Nonetheless integrators and architects will have to configure the system to receive or send data over SOME/IP, hence provide it as a SOME/IP service. + + +.. _Rationale: + +Rationale +========== + +SOME/IP and IPC use different mechanisms to communicate on different channels. Applications integrating on S-CORE platform may have certain requirements to data-input that is not directly supported with SOME/IP and vice versa +SOME/IP definition may have requirements that cannot directly be supported by the application providing data on IPC. Therefor it's not only a task of this gateway +to adapt the communication, but also to translate data between the two communication channels and probably even fill data, i.e. when applications require new data that has not be received on SOME/IP or vice versa. + +Hence the gateway on the one side should act as a participant in IPC and fulfill all requirements to this accordingly, whereas on the other side it shall participate in SOME/IP communication +acting as a SOME/IP service fulfilling all SOME/IP requirements and defined communication. Between these two contexts developers shall be able to create signal or data mappings and +translate the different data-types and representations of the two contexts. + +The SOME/IP side shall, where possible, use an existing SOME/IP stack that is fully compatible and complying with the SOME/IP specification from AUTOSAR Adaptive. + +This module shall fulfill the following requirements: + - Multi-Binding support - :need:`feat_req__com__multi_binding_support` + - agnostic binding - :need:`feat_req__com__binding_agnostic_api` + - deployment configuration - :need:`feat_req__com__multi_binding_depl` + + +.. _Specification: + +Specification +============= + +SOME/IP Gateway protocol implementation +--------------------------------------- + +The protocol implementation shall be fully compatible and complying with the SOME/IP specification from AUTOSAR Adaptive. +Specifically the SOME/IP specification from AUTOSAR release 24-11 shall be supported by the SOME/IP Gateway. This shall guarantee that systems integrated with the SOME/IP gateway can be used in +Protocol implementations shall be wrapped in an abstraction API, that stays stable and allows implementations may be exchanged, potentially even by binary only libraries. + + + +SOME/IP Gateway Security Goals +------------------------------ + +As with IPC generally, the security approach for SOME/IP gateway shall achieve the following security goals: + +- confidentiality (:need:`feat_req__ipc__confidentiality`) +- integrity (:need:`feat_req__ipc__integrity`) +- availability (per criticality-level) (:need:`feat_req__ipc__availability`) + + +Backwards Compatibility +======================= + +As there is currently no previous solution for communication in S-CORE, no backwards compatibility is required. +Subsequent changes to the SOME/IP gateway module shall keep the API stable where possible and introduce breaking APIs only with approval from tech lead circle. +Applications shall stay stable on API layer, need to recompile is acceptable. + +Security Impact +=============== + +As the SOME/IP gateway will open direct communication channels on the SOME/IP channels, the SOME/IP implementation shall comply with standard security requirements. + +Safety Impact +============= + + +License Impact +============== + +[How could the copyright impacted by the license of the new contribution?] + + +How to Teach This +================= diff --git a/docs/features/communication/some_ip_gateway/requirements/index.rst b/docs/features/communication/some_ip_gateway/requirements/index.rst new file mode 100644 index 00000000000..5527d9e4ff0 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/requirements/index.rst @@ -0,0 +1,50 @@ +.. + # ******************************************************************************* + # Copyright (c) 2024 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +SOME/IP Gateway Requirements +############################ + + +Functional Requirements +======================= + + + +Security Impact +=============== + + + +Safety Impact +============= + +.. feat_req:: SOME/IP Gateway ASIL level + :id: feat_req__some_ip_gateway__asil + :reqtype: Functional + :security: YES + :safety: ASIL_B + :satisfies: stkh_req__communication__safe + :status: valid + + The SOME/IP Gateway shall support safe communication up to ASIL-B. + +.. feat_req:: SOME/IP Gateway QM network stack + :id: feat_req__some_ip_gateway__network_stack + :reqtype: Functional + :security: YES + :safety: QM + :satisfies: stkh_req__communication__safe + :status: valid + + If SOME/IP network stacks are available as QM only. From c55a82508bfaf4a5933b4c9a08bab9f89b8a3e36 Mon Sep 17 00:00:00 2001 From: Holger Braun Date: Fri, 25 Jul 2025 15:38:01 +0000 Subject: [PATCH 2/5] some_ip_gateway: Add e2e state machine considerations --- .../e2e_state_machine_in_gateway.drawio.svg | 4 + ...2e_state_machine_on_client_side.drawio.svg | 4 + .../some_ip_gateway/architecture/index.rst | 126 +++++++++++++++++- .../communication/some_ip_gateway/index.rst | 3 + 4 files changed, 136 insertions(+), 1 deletion(-) create mode 100644 docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_in_gateway.drawio.svg create mode 100644 docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_on_client_side.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_in_gateway.drawio.svg b/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_in_gateway.drawio.svg new file mode 100644 index 00000000000..cf9ffa295ce --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_in_gateway.drawio.svg @@ -0,0 +1,4 @@ + + + +
SOME/IP Gateway
SOME/IP Gateway
IPC 
participant
IPC...
Gateway Logic & Configuration
Gateway Logic & Configuration
SOME/IP
communication
stack
SOME/IP...
End-to-End
protection PlugIn
with state machine
End-to-End...
Payload
Transformation
PlugIn
Payload...
IFC
IFC
IFC
IFC
IFC
IFC
IPC 
participant
IPC...
IPC 
participant
IPC...
IPC 
participant
IPC...
<< QM Process >> 1..n
<< QM Process >> 1..n
<< ASIL Process >>  1..n
<< ASIL Process >>  1..n
Payload Transformation
Payload Transformation
IPC
Mw::com/LoLa
IPC...
Additional metadata to be passed to the client:
    Additional metadata to be passed to the cli...
    E2E results
    of each single
    communication cycle
    E2E results...
    IFC = Interface
    IFC = Interface
    IFC
    IFC
    AUTOSAR code
    AUTOSAR code
    Aggregated state machine results per communication channel
    Aggregated stat...
    +
    +
    State machine configuration per communication channel
    State machine c...
    Due to pub/sub nature of mw::com, clients listening on the same topic can not be separately addressed. Therefore, the state machine results can not be selectively distributed according to the particular communication channel they belong to.

    Due to pub/sub nature of mw::co...    Text is not SVG - cannot display     \ No newline at end of file diff --git a/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_on_client_side.drawio.svg b/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_on_client_side.drawio.svg new file mode 100644 index 00000000000..a3aa7e7592b --- /dev/null +++ b/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_on_client_side.drawio.svg @@ -0,0 +1,4 @@ + + + +
    SOME/IP Gateway
    SOME/IP Gateway
    IPC 
    participant
    IPC...
    Gateway Logic & Configuration
    Gateway Logic & Configuration
    SOME/IP
    communication
    stack
    SOME/IP...
    End-to-End
    protection PlugIn
    w/o state machine
    End-to-End...
    Payload
    Transformation
    PlugIn
    Payload...
    IFC
    IFC
    IFC
    IFC
    IFC
    IFC
    IPC 
    participant
    IPC...
    IPC 
    participant
    IPC...
    IPC 
    participant
    IPC...
    << QM Process >> 1..n
    << QM Process >> 1..n
    << ASIL Process >>  1..n
    << ASIL Process >>  1..n
    All E2E results received via IPC metadata need to be fed into the state machine for each single  communication cacle.

    E2E state machine configuration details need to be known by the client.
    All E2E results received...
    End-to-End
    protection
    state machine
    End-to-End...
    IFC
    IFC
    E2E sate machine configuration
    E2E sate mach...
    Payload Transformation
    Payload Transformation
    IPC
    Mw::com/LoLa
    IPC...
    Additional metadata to be passed to the client:
      Additional metadata to be passed to the cli...
      E2E results
      of each single
      communication cycle
      E2E results...
      IFC = Interface
      IFC = Interface
      IFC
      IFC
      AUTOSAR code
      AUTOSAR code      Text is not SVG - cannot display       \ No newline at end of file diff --git a/docs/features/communication/some_ip_gateway/architecture/index.rst b/docs/features/communication/some_ip_gateway/architecture/index.rst index 2ee6edec76b..777f4e43d88 100644 --- a/docs/features/communication/some_ip_gateway/architecture/index.rst +++ b/docs/features/communication/some_ip_gateway/architecture/index.rst @@ -24,6 +24,8 @@ SOME/IP Gateway Architecture .. toctree:: :titlesonly: +Context View +============ SOME/IP Gateway on one side is a regular participant in IPC and uses the according mechanisms to publish data or to subscribe to data. As such it will need to know and understand the data types that are used in the IPC network. @@ -43,7 +45,8 @@ should be mostly freely programmable by integrators using the SOME/IP gateway. General overview of SOME/IP Gateway - +Structural View +=============== SOME/IP stacks as supplied by AUTOSAR vendors mostly are available as QM only. In the case that SOME/IP implementations are not developed under ASIL-B constraints, adequate measures need to be taken to separate this QM component from the otherwise ASIL-B compliant components. This may be achieved through separate processes, @@ -55,3 +58,124 @@ It is preferred to avoid such additional IPC. :name: _some_ip_gateway_details Detailed components view of SOME/IP Gateway + +E2E Considerations +================== +To cope with SOME/IP stack just beeing QM, we need to prepare for end-to-end protection. The goal shall be to +do the E2E protection/check **as centrally as possible** in the gateway. Unfortunately, the centralized end-to-end +check cannot be done for all relevant E2E properties. The following table proposes where the corresponding E2E properties shall +checked. + +.. list-table:: E2E properties + :widths: 20 50 5 5 + :header-rows: 1 + + * - Protection Property + - Purpose + - Gateway + - IPC Client + * - CRC + - Detects data corruption in the payload and metadata. + - x + - + * - Counter + - Detects message loss, duplication, or reordering. + - x + - x + * - Alive Counter + - Detects if the sender is still active or stuck/frozen + - x + - x + * - Data ID + - Identifies the data format version to prevent misinterpretation. + - + - x + * - Timeout + - Detects if no message is received within a defined time window. + - + - x + +E2E Design and Interface Considerations +--------------------------------------- +As mentioned above, not all E2E checks can be kept hidden within the gateway. For some problems it is up to the application to decide +whether it is still valuable to access and process the data. This is in particular true for duplication or re-odering issues. +Therefore, it is required to pass a **tupel** consisting of the **payload data** as well as **supplementary E2E metadata and error information** +to the IPC clients to enable the client to individually judge on particular E2E issues. + +* The API design needs to put the payload information as well as the additional E2E metadata as close as possible together to easily enable and motivate clients to consequently check for potential errors. +* Additional metadata and error information needs to be incorporated into regular mw::com user interface +* Error related interface design needs to be highly optimezed for the "good case" to have an optimized support for the common IPC case +* AoU's need to be provided to force the user to check for the (E2E-) result +* Additional E2E metadata to be handed over to the clients: + + * Counter, slightly different interpretation depending on profile, n/a in case the profile doesn't support it + * Data ID, n/a in case the profile does not support it or if the Data ID is not explicitely transmitted like in profile 22 + * Profile identification, required to properly interpret E2E attributes like "Counter". (Could be either an "Alive Counter" or a "Sequence Counter" depending on the profile) + * Detailed, profile specific error code (enum) + +* Proposed Error Enumeration + + * No E2E error + * CRC Error + * Sequence error (further subqualification in loss, duplication, reordering is up to the client based on the counter) + +.. note:: + The proposed error enumeration is an abstraction. Deriving detailed errors + based on the E2E metadata is task of the client. + For reference, this is the error enumeration of the Autosar specification (R24-11): + + * OK + * ERROR + * OKSOMELOST + * REPEATED + * WRONGSEQUENCE + * NONEWDATA + * SYNC + * INITIAL + +E2E State Machine Considerations +-------------------------------- +The E2E (End-to-End) state machine as defined within AUTOSAR E2E protocol provides a summarized result +about the overall health and state of a communication channel. Unlike individual E2E Profile Check() functions, +which assess data validity for a single communication cycle, the state machine aggregates results from multiple Check() +function invocations over a period. This allows it to determine a more holistic and debounced status of the communication. + +Purpose of the E2E State Machine: +The primary purpose of the E2E state machine is to transform instantaneous "per-cycle" check results into a stable, +long-term communication channel status. This aggregated status is then provided to the consuming application, +enabling it to make informed decisions about whether the received data can be trusted and used for safety-related functions. + +As mentioned above, the E2E statemachine is associated to one communication channel which is in turn associated to exactly one +individual IPC client. Therefore it is an obvious consequence, that the individiual state machine handling and state machine +configuration is responsibility of the client and not a central responsibility of the gateway. +The diagram below outlines this distribution of responsibilties. + +*Diagram: E2E state machine responsibility associated to IPC client* + +.. figure:: e2e_state_machine_on_client_side.drawio.svg + :align: center + :name: _e2e_state_machine_on_client_side + + E2E state machine responsibility associated to IPC client + +**Considered Alternative** + +If we allocate the statemachine responsibility to the gateway the distribution of resposnibilities would look like in the following diagram + +*Diagram: E2E state machine responsibility associated to the gateway* + +.. figure:: e2e_state_machine_in_gateway.drawio.svg + :align: center + :name: _e2e_state_machine_in_gateway + + E2E state machine responsibility associated to the gateway + +Due to pub/sub nature of mw::com, clients listening on the same topic can not be separately addressed. Therefore, **the state machine results +can not be selectively distributed according to the particular communication channel they belong to**. + +**=> Alternative dismissed** + +.. note:: + The End-to-End consideration in this chapter do not yet consider methods. + + diff --git a/docs/features/communication/some_ip_gateway/index.rst b/docs/features/communication/some_ip_gateway/index.rst index b43996b99c3..a1c9b7055f9 100644 --- a/docs/features/communication/some_ip_gateway/index.rst +++ b/docs/features/communication/some_ip_gateway/index.rst @@ -125,6 +125,9 @@ As the SOME/IP gateway will open direct communication channels on the SOME/IP ch Safety Impact ============= +SOME/IP stack and underlying OS network stacks are typically QM only. Freedom from interference needs to be respected between the +safty classified IPC component (mw::com) and the SOME/IP stack which is part of the gateway. The SOME/IP communication itself needs +to be properly protected by E2E to maintain a safe communication via the grey SOME/IP channel. License Impact ============== From 3f98656bafd14e1916b630c87e91624e75931f01 Mon Sep 17 00:00:00 2001 From: Andreas Kaluza Date: Mon, 28 Jul 2025 12:08:51 +0000 Subject: [PATCH 3/5] some_ip_gateway: security and crypto --- .../some_ip_gateway/architecture/index.rst | 18 +- .../e2e_state_machine_in_gateway.drawio.svg | 0 ...2e_state_machine_on_client_side.drawio.svg | 0 .../assets/puml-theme-score.puml | 566 ++++++++++++++++++ .../some_ip_gateway_architecture.drawio.svg | 0 .../some_ip_gateway_details.drawio.svg | 0 .../some_ip_gateway_sec_protocols.drawio.svg | 553 +++++++++++++++++ .../communication/some_ip_gateway/index.rst | 133 +++- .../some_ip_gateway/requirements/index.rst | 20 +- 9 files changed, 1278 insertions(+), 12 deletions(-) rename docs/features/communication/some_ip_gateway/{architecture => assets}/e2e_state_machine_in_gateway.drawio.svg (100%) rename docs/features/communication/some_ip_gateway/{architecture => assets}/e2e_state_machine_on_client_side.drawio.svg (100%) create mode 100644 docs/features/communication/some_ip_gateway/assets/puml-theme-score.puml rename docs/features/communication/some_ip_gateway/{architecture => assets}/some_ip_gateway_architecture.drawio.svg (100%) rename docs/features/communication/some_ip_gateway/{architecture => assets}/some_ip_gateway_details.drawio.svg (100%) create mode 100644 docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/architecture/index.rst b/docs/features/communication/some_ip_gateway/architecture/index.rst index 777f4e43d88..6cdcfbdd270 100644 --- a/docs/features/communication/some_ip_gateway/architecture/index.rst +++ b/docs/features/communication/some_ip_gateway/architecture/index.rst @@ -39,7 +39,7 @@ that might be independent of the rest of the gateway. But buffering / queuing of should be mostly freely programmable by integrators using the SOME/IP gateway. -.. figure:: some_ip_gateway_architecture.drawio.svg +.. figure:: ../assets/some_ip_gateway_architecture.drawio.svg :align: center :name: _some_ip_gateway_architecture @@ -53,7 +53,7 @@ separate this QM component from the otherwise ASIL-B compliant components. This which again will require dedicated inter-process-communication between the SOME/IP-stack and the rest of the gateway. It is preferred to avoid such additional IPC. -.. figure:: some_ip_gateway_details.drawio.svg +.. figure:: ../assets/some_ip_gateway_details.drawio.svg :align: center :name: _some_ip_gateway_details @@ -63,7 +63,7 @@ E2E Considerations ================== To cope with SOME/IP stack just beeing QM, we need to prepare for end-to-end protection. The goal shall be to do the E2E protection/check **as centrally as possible** in the gateway. Unfortunately, the centralized end-to-end -check cannot be done for all relevant E2E properties. The following table proposes where the corresponding E2E properties shall +check cannot be done for all relevant E2E properties. The following table proposes where the corresponding E2E properties shall checked. .. list-table:: E2E properties @@ -77,7 +77,7 @@ checked. * - CRC - Detects data corruption in the payload and metadata. - x - - + - * - Counter - Detects message loss, duplication, or reordering. - x @@ -88,11 +88,11 @@ checked. - x * - Data ID - Identifies the data format version to prevent misinterpretation. - - + - - x * - Timeout - Detects if no message is received within a defined time window. - - + - - x E2E Design and Interface Considerations @@ -152,7 +152,7 @@ The diagram below outlines this distribution of responsibilties. *Diagram: E2E state machine responsibility associated to IPC client* -.. figure:: e2e_state_machine_on_client_side.drawio.svg +.. figure:: ../assets/e2e_state_machine_on_client_side.drawio.svg :align: center :name: _e2e_state_machine_on_client_side @@ -164,7 +164,7 @@ If we allocate the statemachine responsibility to the gateway the distribution o *Diagram: E2E state machine responsibility associated to the gateway* -.. figure:: e2e_state_machine_in_gateway.drawio.svg +.. figure:: ../assets/e2e_state_machine_in_gateway.drawio.svg :align: center :name: _e2e_state_machine_in_gateway @@ -177,5 +177,3 @@ can not be selectively distributed according to the particular communication cha .. note:: The End-to-End consideration in this chapter do not yet consider methods. - - diff --git a/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_in_gateway.drawio.svg b/docs/features/communication/some_ip_gateway/assets/e2e_state_machine_in_gateway.drawio.svg similarity index 100% rename from docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_in_gateway.drawio.svg rename to docs/features/communication/some_ip_gateway/assets/e2e_state_machine_in_gateway.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_on_client_side.drawio.svg b/docs/features/communication/some_ip_gateway/assets/e2e_state_machine_on_client_side.drawio.svg similarity index 100% rename from docs/features/communication/some_ip_gateway/architecture/e2e_state_machine_on_client_side.drawio.svg rename to docs/features/communication/some_ip_gateway/assets/e2e_state_machine_on_client_side.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/assets/puml-theme-score.puml b/docs/features/communication/some_ip_gateway/assets/puml-theme-score.puml new file mode 100644 index 00000000000..fc78e4ca613 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/assets/puml-theme-score.puml @@ -0,0 +1,566 @@ +'' The referenced original work is published under MIT license +'' MIT license: https://github.com/bschwarz/puml-themes/blob/master/LICENSE +'' +'' conti theme is based on materia theme +'' Author: Andreas Kaluza +'' Copyright (c) 2012 by Andreas Kaluza +'' +'' materia theme based off of the bootstrap theme of the same name +'' https://bootswatch.com/materia/ +'' +'' Author: Brett Schwarz +'' Copyright (c) 2019 by Brett Schwarz + +!$THEME = "score" + +!if %not(%variable_exists("$BGCOLOR")) +!$BGCOLOR = "transparent" +!endif + +skinparam backgroundColor $BGCOLOR +skinparam useBetaStyle true + + + +!$SCORE = "#45ADA8" +!$BLUE = "#2196F3" +!$INDIGO = "#6610f2" +!$PURPLE = "#6f42c1" +!$PINK = "#e83e8c" +!$RED = "#e51c23" +!$ORANGE = "#fd7e14" +!$YELLOW = "#ff9800" +!$GREEN = "#4CAF50" +!$TEAL = "#20c997" +!$CYAN = "#9C27B0" +!$WHITE = "#FFF" +!$GRAY_DARK = "#222" +!$GRAY = "#666" +!$PRIMARY = $SCORE +!$SECONDARY = %lighten($SCORE, 80) +!$SUCCESS = "#4CAF50" +!$INFO = %lighten($SCORE, 40) +!$WARNING = "#ff9800" +!$DANGER = "#e51c23" +!$LIGHT = "#fff" +!$DARK = "#222" + +'' *_LIGHT = tint (lighter) of the main color of 80% +'' *_DARK = shade (darker) of the main color of 80% +'' +!$FGCOLOR = %darken($SCORE, 80) +!$PRIMARY_LIGHT = %lighten($SCORE, 40) +!$PRIMARY_DARK = %darken($SCORE, 40) +!$PRIMARY_TEXT = %darken($SCORE, 80) +!$SECONDARY_LIGHT = "#fff" +!$SECONDARY_DARK = "#cccccc" +!$SECONDARY_TEXT = %darken($SCORE, 80) +!$INFO_LIGHT = %lighten($INFO, 40) +!$INFO_DARK = %darken($INFO, 40) +!$INFO_TEXT = %darken($SCORE, 80) +!$SUCCESS_LIGHT = "#70bf73" +!$SUCCESS_DARK = "#3D8C40" +!$SUCCESS_TEXT = %darken($SCORE, 80) +!$WARNING_LIGHT = "#ffad33" +!$WARNING_DARK = "#CC7A00" +!$WARNING_TEXT = %darken($SCORE, 80) +!$DANGER_DARK = "#b7161c" +!$DANGER_LIGHT = "#B7161C" +!$DANGER_TEXT = %darken($SCORE, 80) + +!procedure $success($msg) + $msg +!endprocedure + +!procedure $failure($msg) + $msg +!endprocedure + +!procedure $warning($msg) + $msg +!endprocedure + +!procedure $primary_scheme() + FontColor $PRIMARY_TEXT + BorderColor $PRIMARY + BackgroundColor $PRIMARY_LIGHT-$PRIMARY +!endprocedure +'' +'' Style settings +'' + +'' +'' Global Default Values +'' +skinparam defaultFontName "Arial" +skinparam defaultFontSize 12 +skinparam dpi 100 +skinparam shadowing true +skinparam roundcorner 8 +skinparam ParticipantPadding 1 +skinparam BoxPadding 1 +skinparam Padding 1 +skinparam ArrowColor $GRAY +skinparam stereotype { + CBackgroundColor $SECONDARY_LIGHT + CBorderColor $SECONDARY_DARK + ABackgroundColor $SUCCESS_LIGHT + ABorderColor $SUCCESS_DARK + IBackgroundColor $DANGER_LIGHT + IBorderColor $DANGER_DARK + EBackgroundColor $WARNING_LIGHT + EBorderColor $WARNING_DARK + NBackgroundColor $INFO_LIGHT + NBorderColor $INFO_DARK +} +skinparam title { + FontColor $PRIMARY + BorderColor $SECONDARY_DARK + FontSize 20 + BorderRoundCorner 8 + BorderThickness 1 + BackgroundColor $SECONDARY_LIGHT-$SECONDARY +} + +skinparam legend { + BackgroundColor $SECONDARY + BorderColor $SECONDARY_DARK + FontColor $DARK +} + +!startsub swimlane +skinparam swimlane { + BorderColor $PRIMARY + BorderThickness 2 + TitleBackgroundColor $SECONDARY_LIGHT-$SECONDARY + TitleFontColor $PRIMARY +} +!endsub + +!startsub activity + +skinparam activity { + $primary_scheme() + BarColor $PRIMARY_DARK + StartColor $PRIMARY + EndColor $PRIMARY + '' + DiamondBackgroundColor $PRIMARY_LIGHT + DiamondBorderColor $PRIMARY_DARK + DiamondFontColor $SECONDARY_TEXT + NoteFontColor %darken($SCORE, 40) +} +!endsub + +!startsub participant + +skinparam participant { + $primary_scheme() + ParticipantBorderThickness 2 +} +!endsub + +!startsub actor + +skinparam actor { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub arrow + +skinparam arrow { + Thickness 1 + Color $PRIMARY + FontColor $FGCOLOR +} +!endsub + +!startsub sequence + +skinparam sequence { + BorderColor $PRIMARY + ' For some reason sequence title font color does not pick up from global + TitleFontColor $PRIMARY + BackgroundColor transparent + StartColor $PRIMARY + EndColor $PRIMARY + '' + BoxBackgroundColor transparent + BoxBorderColor $GRAY + BoxFontColor $DARK + '' + DelayFontColor $DARK + '' + LifeLineBorderColor $PRIMARY_DARK + LifeLineBorderThickness 2 + LifeLineBackgroundColor $PRIMARY_LIGHT + '' + GroupBorderColor $GRAY + GroupFontColor $DARK + GroupHeaderFontColor $INFO + '' + DividerBackgroundColor $WHITE-$LIGHT + DividerBorderColor $GRAY + DividerBorderThickness 2 + DividerFontColor $DARK + '' + ReferenceBackgroundColor transparent + ReferenceBorderColor $GRAY + ReferenceFontColor $DARK + ReferenceHeaderFontColor $INFO + '' + StereotypeFontColor $PRIMARY_TEXT + '' + ParticipantBorderThickness 0 + GroupBodyBackgroundColor transparent +} +!endsub + +!startsub partition + +skinparam partition { + BorderColor $PRIMARY + FontColor $PRIMARY + BackgroundColor transparent +} +!endsub + +!startsub collections + +skinparam collections { + $primary_scheme() +} +!endsub + +!startsub control + +skinparam control { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub entity + +skinparam entity { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub boundary + +skinparam boundary { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub agent + +skinparam agent { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub note + +skinparam note { + BorderThickness 1 + BackgroundColor $INFO_LIGHT-$INFO + BorderColor $INFO + FontColor %darken($SCORE, 40) +} +!endsub + +!startsub artifact + +skinparam artifact { + $primary_scheme() +} +!endsub + +!startsub component + +skinparam component { + $primary_scheme() +} +!endsub + +!startsub interface + +skinparam interface { + BackgroundColor $DANGER_LIGHT + BorderColor $DANGER + FontColor $DARK +} +!endsub + +!startsub storage + +skinparam storage { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub node + +skinparam node { + BackgroundColor $SECONDARY_LIGHT-$SECONDARY + BorderColor $PRIMARY + FontColor $DARK +} +!endsub + +!startsub cloud + +skinparam cloud { + BackgroundColor transparent + BorderColor $PRIMARY + FontColor $DARK +} +!endsub + +!startsub database + +skinparam database { + $primary_scheme() + FontColor $DARK +} +!endsub + +!startsub class + +skinparam class { + $primary_scheme() + HeaderBackgroundColor $PRIMARY-$PRIMARY_DARK + StereotypeFontColor $DARK + BorderThickness 1 + AttributeFontColor $LIGHT + AttributeFontSize 11 +} +!endsub + +!startsub object + +skinparam object { + $primary_scheme() + StereotypeFontColor $DARK + BorderThickness 1 + AttributeFontColor $SECONDARY_TEXT + AttributeFontSize 11 +} +!endsub + +!startsub usecase + +skinparam usecase { + $primary_scheme() + BorderThickness 2 + StereotypeFontColor $PRIMARY +} +!endsub + +!startsub rectangle + +skinparam rectangle { + FontColor $PRIMARY + BackgroundColor $SECONDARY_LIGHT-$SECONDARY + BorderThickness 2 + StereotypeFontColor $PRIMARY +} +!endsub + +!startsub package + +skinparam package { + $primary_scheme() + BackgroundColor $SECONDARY_LIGHT-$SECONDARY + BorderThickness 2 +} +!endsub + +!startsub folder + +skinparam folder { + BackgroundColor $WHITE-$SECONDARY_LIGHT + BorderColor $PRIMARY + FontColor $PRIMARY + BorderThickness 2 +} +!endsub + +!startsub frame + +skinparam frame { + BackgroundColor $WHITE-$SECONDARY_LIGHT + BorderColor $INFO + FontColor $INFO + BorderThickness 2 +} +!endsub + +!startsub state + +skinparam state { + $primary_scheme() + BorderColor $PRIMARY_DARK + StartColor $INFO + EndColor $INFO + AttributeFontColor $SECONDARY_TEXT + AttributeFontSize 11 +} +!endsub + +!startsub queue + +skinparam queue { + $primary_scheme() +} +!endsub + +!startsub card + +skinparam card { + BackgroundColor $INFO_LIGHT-$INFO + BorderColor $INFO + FontColor $INFO_TEXT +} +!endsub + +!startsub file + +skinparam file { + BackgroundColor $SECONDARY_LIGHT-$SECONDARY + BorderColor $GRAY + FontColor $GRAY + +} +!endsub + +!startsub stack + +skinparam stack { + $primary_scheme() +} +!endsub diff --git a/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_architecture.drawio.svg b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_architecture.drawio.svg similarity index 100% rename from docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_architecture.drawio.svg rename to docs/features/communication/some_ip_gateway/assets/some_ip_gateway_architecture.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_details.drawio.svg b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_details.drawio.svg similarity index 100% rename from docs/features/communication/some_ip_gateway/architecture/some_ip_gateway_details.drawio.svg rename to docs/features/communication/some_ip_gateway/assets/some_ip_gateway_details.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg new file mode 100644 index 00000000000..b8950b1b2c4 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg @@ -0,0 +1,553 @@ + + + + + + + + + + +
      +
      +
      + + Layer 2 + +
      +
      +
      +       + + Layer 2 + +       +       +       + + + + + + + +
      +
      +
      + + + + MACsec + + + +
      + + + + / VLAN + + + +
      +
      +
      +
      +       + + MACsec... + +       +       +       + + + + + + + +
      +
      +
      + + Layer 5-7 + +
      +
      +
      +       + + Layer 5-7 + +       +       +       + + + + + + + +
      +
      +
      + + SOME/IP + +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + SOME/IP... + +       +       +       + + + + + + + +
      +
      +
      + + Signal PDUs + +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + Signal PDUs... + +       +       +       + + + + + + + +
      +
      +
      + + UDP-NM + +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + UDP-NM... + +       +       +       + + + + + + + +
      +
      +
      + + Layer 4 + +
      +
      +
      +       + + Layer 4 + +       +       +       + + + + + + + +
      +
      +
      + + Layer 3 + +
      +
      +
      +       + + Layer 3 + +       +       +       + + + + + + + +
      +
      +
      + + Layer 1 + +
      +
      +
      +       + + Layer 1 + +       +       +       + + + + + + + +
      +
      +
      + + DoIP + +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + DoIP... + +       +       +       + + + + + + + +
      +
      +
      +
      + +
      +       +
      + + DTCP/IP Stack (e.g. TCP, UDP, IP, ICMP, ARP, DHCP) + +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + DTCP/IP Stack (e.g. TCP, UDP, IP, ICMP, ARP, DHCP)... + +       +       +       + + + + + + + +
      +
      +
      + + + AVTP + + +
      +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + AVTP... + +       +       +       + + + + + + + +
      +
      +
      + + gPTP + +
      + + +
      +       +       +
      +
      +
      +
      +
      +
      +
      +       + + gPTP... + +       +       +       + + + + + + + +
      +
      +
      + + + + SecOC, ACL* + + + +
      +
      +
      +       + + SecOC, ACL* + +       +       +       + + + + + + + +
      +
      +
      + + MAC Layer and AVB/TSN/QoS features + +
      +
      +
      +       + + MAC Layer and AVB/TSN/QoS features + +       +       +       + + + + + + + +
      +
      +
      + + 100BASE-TX + +
      +
      +
      +       + + 100BASE-TX + +       +       +       + + + + + + + +
      +
      +
      + + Automotive Phys 100, 1000, and more MBit/s + +
      +
      +
      +       + + Automotive Phys 100, 1000, and more MBit/s + +       +       +       + + + + + + + +
      +
      +
      + + + + TLS / DTLS + + + +
      +
      +
      +       + + TLS / DTLS + +       +       +       + + + + + + + +
      +
      +
      + + + + IPsec + + + +
      +
      +
      +       + + IPsec + +       +       +       +       + + + + + Text is not SVG - cannot display + + + +       diff --git a/docs/features/communication/some_ip_gateway/index.rst b/docs/features/communication/some_ip_gateway/index.rst index a1c9b7055f9..c2bb048ba49 100644 --- a/docs/features/communication/some_ip_gateway/index.rst +++ b/docs/features/communication/some_ip_gateway/index.rst @@ -108,6 +108,8 @@ As with IPC generally, the security approach for SOME/IP gateway shall achieve t - confidentiality (:need:`feat_req__ipc__confidentiality`) - integrity (:need:`feat_req__ipc__integrity`) - availability (per criticality-level) (:need:`feat_req__ipc__availability`) +- secure communication (:need:`feat_req__some_ip_gateway__secure_com`) +- access control (:need:`feat_req__some_ip_gateway__access_control`) Backwards Compatibility @@ -120,7 +122,136 @@ Applications shall stay stable on API layer, need to recompile is acceptable. Security Impact =============== -As the SOME/IP gateway will open direct communication channels on the SOME/IP channels, the SOME/IP implementation shall comply with standard security requirements. +There are multiple protocols targeting secure communication. In general a holistic security concept for a vehicle will not apply all together. + +.. figure:: assets/some_ip_gateway_sec_protocols.drawio.svg + :align: center + :name: some_ip_gateway_sec_protocols_ + + Secure communication protocols + + +.. note:: + Access Control List (ACL) is not a security protocol, but a mechanism to restrict access to the SOME/IP Gateway services and tylically allocated within the stateful packet inspection firewall. + +Scope +----- + +As the SOME/IP gateway will open direct communication channels via SOME/IP, where the SOME/IP implementation shall comply with standard security requirements. + +Since SOME/IP is a protocol relies on the security of the underlying transport layer, the SOME/IP gateway makes use of the security features relevant for it. This includes: + +- VLAN (= Virtual Local Area Network): A virtual interface that separates ethernet network packets identified by a VLAN ID +- MACsec: Provides L2 data Integrity, Authenticity and optionally Confidentiality for point-to-point communication. +- IPsec: A network layer protocol suite that secures network connections by encrypting and/or authenticating IP packets. +- TLS (= Transport Layer Security): Authentication, integrity, confidentiality of TCP channels -> Protection for one to one communication. +- DTLS (= Datagram Transport Layer Security): Authentication, integrity, confidentiality of UDP packets -> Protection for multicast communication. +- ACL (= Access Control List): A filter mechanism to ensure that only allowed SOME/IP communication can take place. + +Features included `Feature Request for Security & Crypto `_ e.g cryptographic algorithms, symmetric-, asymmetric encryption, Signature functionality, Certificate management, certificate management, entropy generation, data integrity, key management, are out of scope. + + +Access Control List +------------------- + +An access control mechanism is part of a firewall solution, which states that only the traffic defined in the security policy is allowed onto the network and all other traffic must be silently dropped. +Access Control acts on OSI Layer 5-7. It shall fulfill following: + +- Whitelisting of SOME/IP services and methods based on IP addresses and therefore IP address authenticity. +- A static list which could be updated via OTA (= Over-The-Air) updates. +- Versioning +- ACL shall be able to be switched on/off to allow bypassing in an secured environment e.g. engineering mode or repair shop. +- ACL drop actions shall be logged persistently via a DTC (= Diagnostic Trouble Code) including needed environment data to clearly understand the context of the drop, including the sender, timestamp, Service ID and Instance ID. +- To avoid code injection attacks, into services of the system, only authenticated and authorized communication partners are allowed to write or delete entries into the **Service Registry**. + +.. note:: + - Checking SOME/IP-SD messages with the ACL is optional because no functional data is transported. + - SOME/IP-SD messages are not protected as per AUTSAR Adaptive specification. + + +.. uml:: + :name: doc__acl_activity_diagram + :scale: 80 + :align: center + :caption: Simplified Access Control Activity Diagram + + !include assets/puml-theme-score.puml + + start + + :Ingress SOME/IP; + :ACL Check; + + if (Packet matches ACL entry?) then (Yes) + :Process Packet; + else (No) + :Log Event; + if (ACL is active?) then (Yes) + :Drop Packet; + else (No) + :Process Packet; + endif + endif + + stop + + +E2E and CRC (Informal Notes) +---------------------------- + +There are several E2E (= End-to-End) profiles, which utilize various CRC routines as part of AUTOSAR E2E Protocol Specification: + +- CRC8 (SAEJ1850) +- CRC8H2F (0x2F polynomial) +- CRC16 (also known as CCITT-FALSE 16-bit CRC) +- CRC32 (also known as IEEE 802.3 Ethernet 32-bit CRC) +- CRC32P4 (0xF4ACFB13 polynomial) +- CRC64 (CRC-64-ECMA) +- CRC32_J1939 (0x6938392D polynomial) (used by Profile 76). + +These routines can be implemented using different calculation methods: + +- Table based calculation for faster execution, but requiring a larger code size due to ROM tables. +- Runtime calculation for smaller code size (no ROM table), but resulting in slower execution. +- Hardware supported CRC calculation (device-specific) for fast execution and less CPU time. + +The E2E Library itself does not provide CRC routine implementations, instead, it calls the CRC routines from a dedicated CRC library. +It is also a requirement that the CRC used in an E2E profile must be different from the CRC used by the underlying physical communication protocol. + +All E2E profiles can be used in combination with SOME/IP, although specific profiles may have limitations regarding maximum data length or being restricted to fixed-length messages. + +For E2E protection with SOME/IP, the CRC is calculated over specific parts of the serialized SOME/IP message: + +- For profiles 1, 2, 4, 5, 6, 7, 11, and 22, which are typically used for signal-based or periodic event-based communication, the E2E CRC should be calculated over the following elements of the serialized SOME/IP message: + + - Request ID (Client ID / Session ID) + - Protocol Version + - Interface Version + - Message Type + - Return Code + - Payload + +- For profiles 4m, 7m, 8m, and 44m, which are designed for method-based (client-server) communication, the E2E CRC shall be calculated over specific parts of the serialized SOME/IP message. These method-specific profiles incorporate additional fields like Message Type and Message Result within their E2E headers to distinguish between request and response messages and their outcomes. + +The E2E communication protection process involves the sender adding control fields, including the CRC, to the transmitted data, and the receiver then evaluating these fields upon reception. +The middleware, is responsible for determining parameters like DataID, Message Type, Message Result, and SourceID from the exchanged information and then invoking the E2E functions. +The CRC is calculated over the entire E2E header (excluding the CRC bytes themselves) and the user data. +For some profiles (e.g., Profile 5, 6, 22), the Data ID is included as an extension at the end of the user data for CRC calculation, even if it is not explicitly transmitted. + + +References + +- `AUTOSAR_FO_PRS_E2EProtocol `_ +- `AUTOSAR_FO_RS_E2E `_ + +SecOC (Informal Notes) +---------------------- + +- The SecOC protocol provides a mechanism to verify the authenticity and integrity but lacks of confidentiality. +- SecOC (= Secured Onboard Communication) does not offer encryption support by design. +- In contrast to SecOC, TLS can protect all payload of an AUTOSAR PDU including the AUTOSAR PDU header used which overlaps with the SOME/IP message header. +- In case of SOME/IP protocol, the SOME/IP message id can not be protected by SecOC, because it is stripped before SecO is invoked. + Safety Impact ============= diff --git a/docs/features/communication/some_ip_gateway/requirements/index.rst b/docs/features/communication/some_ip_gateway/requirements/index.rst index 5527d9e4ff0..ddfbf161c5b 100644 --- a/docs/features/communication/some_ip_gateway/requirements/index.rst +++ b/docs/features/communication/some_ip_gateway/requirements/index.rst @@ -24,7 +24,25 @@ Functional Requirements Security Impact =============== +.. feat_req:: SOME/IP Gateway Secure Communication + :id: feat_req__some_ip_gateway__secure_com + :reqtype: Functional + :security: YES + :safety: QM + :satisfies: stkh_req__communication__secure + :status: valid + + The platform shall support secure communication. + +.. feat_req:: SOME/IP Gateway Access Control + :id: feat_req__some_ip_gateway__access_control + :reqtype: Functional + :security: YES + :safety: QM + :satisfies: stkh_req__dependability__security_features + :status: valid + The SOME/IP Gateway shall support access control to restrict access to the gateway services. Safety Impact ============= @@ -43,7 +61,7 @@ Safety Impact :id: feat_req__some_ip_gateway__network_stack :reqtype: Functional :security: YES - :safety: QM + :safety: ASIL_B :satisfies: stkh_req__communication__safe :status: valid From 280fc96acdce6e7ad01565958ac0836be79abdbe Mon Sep 17 00:00:00 2001 From: lurtz <727209+lurtz@users.noreply.github.com> Date: Thu, 31 Jul 2025 11:51:08 +0200 Subject: [PATCH 4/5] some_ip_gateway: SOME/IP Service Discovery (#5) SOME/IP service discovery needs to be mapped to IPC features. Also its behavior in relationship to IPC needs to be shown. --- .../communication/some_ip_gateway/index.rst | 1 + .../service_discovery/index.rst | 180 ++++++++++++++++++ 2 files changed, 181 insertions(+) create mode 100644 docs/features/communication/some_ip_gateway/service_discovery/index.rst diff --git a/docs/features/communication/some_ip_gateway/index.rst b/docs/features/communication/some_ip_gateway/index.rst index c2bb048ba49..b3b4359c2e7 100644 --- a/docs/features/communication/some_ip_gateway/index.rst +++ b/docs/features/communication/some_ip_gateway/index.rst @@ -29,6 +29,7 @@ SOME/IP-Gateway architecture/index.rst requirements/index.rst + service_discovery/index.rst Feature flag diff --git a/docs/features/communication/some_ip_gateway/service_discovery/index.rst b/docs/features/communication/some_ip_gateway/service_discovery/index.rst new file mode 100644 index 00000000000..e56a5d1e138 --- /dev/null +++ b/docs/features/communication/some_ip_gateway/service_discovery/index.rst @@ -0,0 +1,180 @@ +.. + # ******************************************************************************* + # Copyright (c) 2025 Contributors to the Eclipse Foundation + # + # See the NOTICE file(s) distributed with this work for additional + # information regarding copyright ownership. + # + # This program and the accompanying materials are made available under the + # terms of the Apache License Version 2.0 which is available at + # https://www.apache.org/licenses/LICENSE-2.0 + # + # SPDX-License-Identifier: Apache-2.0 + # ******************************************************************************* + +.. _some_ip_gateway_service_discovery: + +SOME/IP-Gateway Service Discovery +################################# + +Service discovery deals with discovery and connection setup of services. +The basic summary of service discovery is as follows: + +- provided / required services (including their service elements like events, methods, and fields) must be configured +- (locally) provided services are discovered (locally) via IPC and then offered on the network by sending a SOME/IP-SD message with an OfferService entry according to configuration +- (locally) required services may trigger the discovery on the network by sending of a SOME/IP-SD message with a FindService entry +- when a SOME/IP-SD message containing a FindService entry is received, the SOME/IP gateway checks this service has been already offered locally via IPC +- for IPC service discovery the features of lola are used by the SOME/IP gateway + +Configuration +============= + +The configuration tells the SOME/IP communication stack which services it should provide and which services it should require on the network. +The configuration contains SOME/IP and SOME/IP-SD settings as well as IP interface bindings. +Events, methods and fields are configured as well. + +The integrator must be able to change configuration at runtime deployment. +Thus it is likely read from one or multiple files. + +Provided services +================= + +Services available in the local ECU / VM are offered by the SOME/IP gateway once they become internally available and are present in the configuration. +This is done by sending an SOME/IP-SD messages containing an OfferService entry to the network. +As long as the service is locally available the service offering is periodically (according to the configuration) renewed by sending a SOME/IP-SD messages containing an OfferService entry to the network. + +.. uml:: + :alt: Gateway offers a service to the network + + @startuml + participant "Producer" as IPC_client + participant "Service\nvia IPC" as Service + participant "SOME/IP Gateway" as Someipgateway + actor "Network" as Network + + IPC_client -> Service ** : create() + IPC_client -> Service : OfferService() + Someipgateway -> Service: service_discovery() + Someipgateway -> Network: OfferService + Network -> Someipgateway: SubscribeEventgroup + Someipgateway -> Someipgateway: create_proxy() + @enduml + +Once the service ceased to exist locally, the SOME/IP communication stack sends a SOME/IP-SD message containing a StopOfferService entry to the network. + +.. uml:: + :alt: Gateway stops service offer + + @startuml + participant "Producer" as IPC_client + participant "Service\nvia IPC" as Service + participant "SOME/IP Gateway" as Someipgateway + actor "Network" as Network + + IPC_client -> Service : StopOfferService() + Someipgateway -> Service: service_discovery() + Someipgateway -> Network: StopOfferService + @enduml + +.. note:: ``mw::com::::StartFindService()`` function can tell us that a service is offered or stopped. But using it is awkward / complicated. + +Required services +================= + +For configured required services, the SOME/IP communication stack will send a SOME/IP-SD message containing a FindService entry to the network. + +FindService message might not be needed, if OfferService messages for that services have been already received. + +Upon initial reception of a SOME/IP-SD message containing an OfferService entry, the SOME/IP communication stack checks if the service has been configured as required service. +If so, the SOME/IP communication stack offers the service locally in the ECU / VM. +Here, initial reception is the first reception after a previous service loss or withdrawal, i.e., + +- after the reception of a SOME/IP-SD message containing an StopOfferService entry +- after a TTL expiry of the previous OfferService entry +- after the detection of a reboot of the (remote) service provider +- after a link-down/link-up event + +.. uml:: + :alt: Gateway receives OfferService from the network + + @startuml + actor "Network" as Network + participant "SOME/IP Gateway" as Someipgateway + participant "Service\nvia IPC" as Service + participant "Consumer" as IPC_client + + Network -> Someipgateway: OfferService + Someipgateway -> Service ** : create() + Someipgateway -> Service: OfferService() + IPC_client -> Service: service_discovery() + IPC_client -> Service: connect() + @enduml + +.. note:: + The SOME/IP communication stack can create the service before receiving an OfferService, + but can only start offering it after having received an OfferService message from the network. + This behavior may reduce the time until the service is available for consumers, but may increase boot time. + Thus the decision is to create the service only after having received an OfferService message from the network. + +Upon reception of SOME/IP-SD message containing an StopOfferService entry, the SOME/IP communication stack stops the proxy service offered via IPC as well. + +.. uml:: + :alt: Gateway receives StopOfferService from the network + + @startuml + actor "Network" as Network + participant "SOME/IP Gateway" as Someipgateway + participant "Service\nvia IPC" as Service + participant "Consumer" as IPC_client + + Network -> Someipgateway: StopOfferService + Someipgateway -> Service: StopOfferService() + IPC_client -> Service: service_discovery() + IPC_client -> IPC_client: handle_disconnect() + @enduml + +.. note:: + If the service times out we may internally stop the service, but keep it alive until another timeout is reached. + The intention is to avoid destroying and recreating the service repeatedly. + + TODO: is this optimization for a rare case and worth the complexity? + +FindService +================ + +Upon reception of a SOME/IP-SD message containing a FindService entry, the SOME/IP communication stack checks if the service is available locally and has been configured as provided service. +If both questions are answered positively, the SOME/IP communication stack responds by sending a SOME/IP-SD message containing an OfferService to the sender of the SOME/IP-SD message containing a FindService entry. + +This will **not** trigger creation of the service internally by any means. +Only lookup of running services is done. + +.. uml:: + :alt: Gateway receives FindService from the network + + @startuml + actor "Network" as Network + participant "SOME/IP Gateway" as Someipgateway + participant "Service\nvia IPC" as Service + + Network -> Someipgateway: FindService + Someipgateway -> Service: service_discovery() + alt Service available + Someipgateway -> Network: OfferService + end + @enduml + +If an service is configured to be needed and no OfferService has been received yet, the SOME/IP communication stack may send a SOME/IP-SD message containing a FindService entry. + +.. uml:: + :alt: Gateway sends FindService to the network + + @startuml + actor "Network" as Network + participant "SOME/IP Gateway" as Someipgateway + + loop required Service + alt no OfferService received + Someipgateway -> Network: FindService + end + end + @enduml From 0b805a106c5cbc14f495e538be12a39672be27cb Mon Sep 17 00:00:00 2001 From: ZoranCutura Date: Tue, 19 Aug 2025 14:28:46 +0000 Subject: [PATCH 5/5] some_ip_gateway: introduced requirements to AUTOSAR compatibility some_ip_gateway: spelling correction some_ip_gateway: spelling corrections some_ip_gateway: ACL and SD conf Changes after reviews and discussions some_ip_gateway: typos some_ip_gateway: changed comment on architecture some_ip_gateway: corrections and AUTOSAR reference corrected typos and wordings introduced requirements to AUTOSAR compatibility review comments addressed some_ip_gateway: adapted requirements to meet com removed requirements for ACL, as they are defined in com already removed ASIL requirement as this is defined for com added remark in specification, that com requirements apply some_ip_gateway: updated requirements with .. stkh missing stkh-requirements added some_ip_gateway: added requirements reworked requirements some_ip_gateway: title underline adapted some_ip_gateway: security-considerations, methods reworked after internal review - methods will be treated mostly like events - security impact adapted to leaner approach - license impact adapted - clean-up and wording some_ip_gateway: license impact to/from AUTOSAR AUTOSAR components like SOME/IP have to make sure to apply AUTOSAR license and constraints correctly. some_ip_gateway: interface to lifecycle added comments on integration with lifecycle management. added comment on licenses impacts with AUTOSAR SOME/IP. Co-authored-by: Ulrich Huber Co-authored-by: Lutz Reinhard Co-authored-by: Andreas Kaluza --- .../some_ip_gateway/architecture/index.rst | 39 +- .../some_ip_gateway_architecture.drawio.svg | 4 +- .../some_ip_gateway_sec_protocols.drawio.svg | 553 ------------------ .../communication/some_ip_gateway/index.rst | 188 +++--- .../some_ip_gateway/requirements/index.rst | 65 +- .../service_discovery/index.rst | 12 +- 6 files changed, 149 insertions(+), 712 deletions(-) delete mode 100644 docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg diff --git a/docs/features/communication/some_ip_gateway/architecture/index.rst b/docs/features/communication/some_ip_gateway/architecture/index.rst index 6cdcfbdd270..4b3e79164bb 100644 --- a/docs/features/communication/some_ip_gateway/architecture/index.rst +++ b/docs/features/communication/some_ip_gateway/architecture/index.rst @@ -17,10 +17,6 @@ SOME/IP Gateway Architecture ############################ -.. note:: - For now we store the component architecture in the feature tree, because multi-repo docs are not yet supported. - Once this support becomes available the component architecture will be moved to the module. - .. toctree:: :titlesonly: @@ -61,7 +57,7 @@ It is preferred to avoid such additional IPC. E2E Considerations ================== -To cope with SOME/IP stack just beeing QM, we need to prepare for end-to-end protection. The goal shall be to +To cope with SOME/IP stack just being QM, we need to prepare for end-to-end protection. The goal shall be to do the E2E protection/check **as centrally as possible** in the gateway. Unfortunately, the centralized end-to-end check cannot be done for all relevant E2E properties. The following table proposes where the corresponding E2E properties shall checked. @@ -98,18 +94,18 @@ checked. E2E Design and Interface Considerations --------------------------------------- As mentioned above, not all E2E checks can be kept hidden within the gateway. For some problems it is up to the application to decide -whether it is still valuable to access and process the data. This is in particular true for duplication or re-odering issues. +whether it is still valuable to access and process the data. This is in particular true for duplication or re-ordering issues. Therefore, it is required to pass a **tupel** consisting of the **payload data** as well as **supplementary E2E metadata and error information** to the IPC clients to enable the client to individually judge on particular E2E issues. * The API design needs to put the payload information as well as the additional E2E metadata as close as possible together to easily enable and motivate clients to consequently check for potential errors. * Additional metadata and error information needs to be incorporated into regular mw::com user interface -* Error related interface design needs to be highly optimezed for the "good case" to have an optimized support for the common IPC case -* AoU's need to be provided to force the user to check for the (E2E-) result +* Error related interface design needs to be highly optimized for the "good case" to have an optimized support for the common IPC case +* Assumptions of Use need to be provided to force the user to check for the (E2E-) result * Additional E2E metadata to be handed over to the clients: * Counter, slightly different interpretation depending on profile, n/a in case the profile doesn't support it - * Data ID, n/a in case the profile does not support it or if the Data ID is not explicitely transmitted like in profile 22 + * Data ID, n/a in case the profile does not support it or if the Data ID is not explicitly transmitted like in profile 22 * Profile identification, required to properly interpret E2E attributes like "Counter". (Could be either an "Alive Counter" or a "Sequence Counter" depending on the profile) * Detailed, profile specific error code (enum) @@ -117,12 +113,16 @@ to the IPC clients to enable the client to individually judge on particular E2E * No E2E error * CRC Error - * Sequence error (further subqualification in loss, duplication, reordering is up to the client based on the counter) + * Sequence error (further sub-qualification in loss, duplication, reordering is up to the client based on the counter) + +.. note:: + CRC Errors might cause problems with corrupted service / instance IDs, as such messages might not get forwarded to the correct recipient. + This requires further discussion during implementation phase. .. note:: The proposed error enumeration is an abstraction. Deriving detailed errors based on the E2E metadata is task of the client. - For reference, this is the error enumeration of the Autosar specification (R24-11): + For reference, this is the error enumeration of the AUTOSAR specification (R24-11): * OK * ERROR @@ -140,15 +140,17 @@ about the overall health and state of a communication channel. Unlike individual which assess data validity for a single communication cycle, the state machine aggregates results from multiple Check() function invocations over a period. This allows it to determine a more holistic and debounced status of the communication. -Purpose of the E2E State Machine: +Purpose of the E2E State Machine +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The primary purpose of the E2E state machine is to transform instantaneous "per-cycle" check results into a stable, long-term communication channel status. This aggregated status is then provided to the consuming application, enabling it to make informed decisions about whether the received data can be trusted and used for safety-related functions. -As mentioned above, the E2E statemachine is associated to one communication channel which is in turn associated to exactly one -individual IPC client. Therefore it is an obvious consequence, that the individiual state machine handling and state machine +As mentioned above, the E2E state-machine is associated to one communication channel which is in turn associated to exactly one +individual IPC client. Therefore it is an obvious consequence, that the individual state machine handling and state machine configuration is responsibility of the client and not a central responsibility of the gateway. -The diagram below outlines this distribution of responsibilties. +Even for the same service different clients may use different state machine configuration. +The diagram below outlines this distribution of responsibilities. *Diagram: E2E state machine responsibility associated to IPC client* @@ -159,8 +161,7 @@ The diagram below outlines this distribution of responsibilties. E2E state machine responsibility associated to IPC client **Considered Alternative** - -If we allocate the statemachine responsibility to the gateway the distribution of resposnibilities would look like in the following diagram +If we allocate the state-machine responsibility to the gateway the distribution of responsibilities would look like in the following diagram *Diagram: E2E state machine responsibility associated to the gateway* @@ -170,8 +171,8 @@ If we allocate the statemachine responsibility to the gateway the distribution o E2E state machine responsibility associated to the gateway -Due to pub/sub nature of mw::com, clients listening on the same topic can not be separately addressed. Therefore, **the state machine results -can not be selectively distributed according to the particular communication channel they belong to**. +Due to pub/sub nature of mw::com, clients listening on the same topic cannot be separately addressed. Therefore, **the state machine results +cannot be selectively distributed according to the particular communication channel they belong to**. **=> Alternative dismissed** diff --git a/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_architecture.drawio.svg b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_architecture.drawio.svg index b0c8ee75fff..5c110a038a3 100644 --- a/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_architecture.drawio.svg +++ b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_architecture.drawio.svg @@ -1,4 +1,4 @@ - + @@ -303,7 +303,7 @@
      - SOME/IP Gateway is a single process on the operating system and may be part of other frameworks, ie. FEO + SOME/IP Gateway is a component / service may be used in other frameworks, ie. FEO
      diff --git a/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg b/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg deleted file mode 100644 index b8950b1b2c4..00000000000 --- a/docs/features/communication/some_ip_gateway/assets/some_ip_gateway_sec_protocols.drawio.svg +++ /dev/null @@ -1,553 +0,0 @@ - - - - - - - - - - -
      -
      -
      - - Layer 2 - -
      -
      -
      -       - - Layer 2 - -       -       -       - - - - - - - -
      -
      -
      - - - - MACsec - - - -
      - - - - / VLAN - - - -
      -
      -
      -
      -       - - MACsec... - -       -       -       - - - - - - - -
      -
      -
      - - Layer 5-7 - -
      -
      -
      -       - - Layer 5-7 - -       -       -       - - - - - - - -
      -
      -
      - - SOME/IP - -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - SOME/IP... - -       -       -       - - - - - - - -
      -
      -
      - - Signal PDUs - -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - Signal PDUs... - -       -       -       - - - - - - - -
      -
      -
      - - UDP-NM - -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - UDP-NM... - -       -       -       - - - - - - - -
      -
      -
      - - Layer 4 - -
      -
      -
      -       - - Layer 4 - -       -       -       - - - - - - - -
      -
      -
      - - Layer 3 - -
      -
      -
      -       - - Layer 3 - -       -       -       - - - - - - - -
      -
      -
      - - Layer 1 - -
      -
      -
      -       - - Layer 1 - -       -       -       - - - - - - - -
      -
      -
      - - DoIP - -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - DoIP... - -       -       -       - - - - - - - -
      -
      -
      -
      - -
      -       -
      - - DTCP/IP Stack (e.g. TCP, UDP, IP, ICMP, ARP, DHCP) - -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - DTCP/IP Stack (e.g. TCP, UDP, IP, ICMP, ARP, DHCP)... - -       -       -       - - - - - - - -
      -
      -
      - - - AVTP - - -
      -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - AVTP... - -       -       -       - - - - - - - -
      -
      -
      - - gPTP - -
      - - -
      -       -       -
      -
      -
      -
      -
      -
      -
      -       - - gPTP... - -       -       -       - - - - - - - -
      -
      -
      - - - - SecOC, ACL* - - - -
      -
      -
      -       - - SecOC, ACL* - -       -       -       - - - - - - - -
      -
      -
      - - MAC Layer and AVB/TSN/QoS features - -
      -
      -
      -       - - MAC Layer and AVB/TSN/QoS features - -       -       -       - - - - - - - -
      -
      -
      - - 100BASE-TX - -
      -
      -
      -       - - 100BASE-TX - -       -       -       - - - - - - - -
      -
      -
      - - Automotive Phys 100, 1000, and more MBit/s - -
      -
      -
      -       - - Automotive Phys 100, 1000, and more MBit/s - -       -       -       - - - - - - - -
      -
      -
      - - - - TLS / DTLS - - - -
      -
      -
      -       - - TLS / DTLS - -       -       -       - - - - - - - -
      -
      -
      - - - - IPsec - - - -
      -
      -
      -       - - IPsec - -       -       -       -       - - - - - Text is not SVG - cannot display - - - -       diff --git a/docs/features/communication/some_ip_gateway/index.rst b/docs/features/communication/some_ip_gateway/index.rst index b3b4359c2e7..5d3b6f85070 100644 --- a/docs/features/communication/some_ip_gateway/index.rst +++ b/docs/features/communication/some_ip_gateway/index.rst @@ -12,6 +12,8 @@ # SPDX-License-Identifier: Apache-2.0 # ******************************************************************************* + # #914 Feature Request for SOME/IP Gateway + .. _some_ip_gateway_feature: SOME/IP-Gateway @@ -48,8 +50,10 @@ The focus is on a gateway to handle SOME/IP communication with external devices This feature request includes: - A description of how a SOME/IP gateway service (or data broker) shall be implemented - - How the SOME/IP gateway services shall integrate with the zero-copy communication from IPC (which might become a general description of how services plug-in to the IPC context) + - How the SOME/IP gateway services shall integrate with the zero-copy communication from IPC - How data shall be mapped or translated between SOME/IP protocol and IPC communication + - How service discovery should be integrated, also for services that are offered by IPC-Clients + - How End-to-End protection and checking shall be realized .. _Motivation: @@ -63,7 +67,7 @@ the S-CORE platform, services are required that will handle protocols for commun needs to be realized with the SOME/IP protocol. For software component developers it should be unrecognized that data is originated from a SOME/IP communication channel, the data should be provided with the same API as in IPC. -Nonetheless integrators and architects will have to configure the system to receive or send data over SOME/IP, hence provide it as a SOME/IP service. +Nonetheless integrators and architects will have to configure the system to receive or send data over SOME/IP. .. _Rationale: @@ -71,19 +75,17 @@ Nonetheless integrators and architects will have to configure the system to rece Rationale ========== -SOME/IP and IPC use different mechanisms to communicate on different channels. Applications integrating on S-CORE platform may have certain requirements to data-input that is not directly supported with SOME/IP and vice versa -SOME/IP definition may have requirements that cannot directly be supported by the application providing data on IPC. Therefor it's not only a task of this gateway -to adapt the communication, but also to translate data between the two communication channels and probably even fill data, i.e. when applications require new data that has not be received on SOME/IP or vice versa. +SOME/IP and IPC use different mechanisms and data representations to communicate. Therefor it's not only a task of this gateway +to adapt the communication, but also to transform from one representation to another. This includes changing data layout, filling in missing data, filtering traffic, error handling, service discovery and further steps. -Hence the gateway on the one side should act as a participant in IPC and fulfill all requirements to this accordingly, whereas on the other side it shall participate in SOME/IP communication -acting as a SOME/IP service fulfilling all SOME/IP requirements and defined communication. Between these two contexts developers shall be able to create signal or data mappings and -translate the different data-types and representations of the two contexts. +Hence the gateway shall be a transparent bridge between IPC and SOME/IP. On the one side it should act as a participant in IPC and fulfill all requirements to this accordingly, where providing data or consuming it. +Whereas on the other side it shall participate in SOME/IP communication acting as a SOME/IP service and client fulfilling all SOME/IP requirements and defined communication. +Between these two contexts developers shall be able to create signal or data mappings and translate the different data-types and representations of the two contexts. -The SOME/IP side shall, where possible, use an existing SOME/IP stack that is fully compatible and complying with the SOME/IP specification from AUTOSAR Adaptive. This module shall fulfill the following requirements: - Multi-Binding support - :need:`feat_req__com__multi_binding_support` - - agnostic binding - :need:`feat_req__com__binding_agnostic_api` + - binding agnostic API - :need:`feat_req__com__binding_agnostic_api` - deployment configuration - :need:`feat_req__com__multi_binding_depl` @@ -92,82 +94,87 @@ This module shall fulfill the following requirements: Specification ============= -SOME/IP Gateway protocol implementation ---------------------------------------- +The requirements from Communication generally apply to the SOME/IP Gateway. + + +SOME/IP protocol implementation +------------------------------- -The protocol implementation shall be fully compatible and complying with the SOME/IP specification from AUTOSAR Adaptive. -Specifically the SOME/IP specification from AUTOSAR release 24-11 shall be supported by the SOME/IP Gateway. This shall guarantee that systems integrated with the SOME/IP gateway can be used in +The protocol implementation shall be fully compatible and complying with the SOME/IP specification from AUTOSAR Adaptive. (:need:`feat_req__some_ip_gateway__someip_protocol`) +Specifically the SOME/IP specification from AUTOSAR release R24-11 shall be supported by the SOME/IP Gateway. This shall guarantee that systems integrated with the SOME/IP gateway can be used in according +automotive E/E-architectures. Protocol implementations shall be wrapped in an abstraction API, that stays stable and allows implementations may be exchanged, potentially even by binary only libraries. +The SOME/IP Gateway shall support SOME/IP Events, Fields and Methods and shall map these accordingly into IPC. + +The SOME/IP Gateway shall support SOME/IP Service Discovery. Please refer to the Service Discovery page for detailed discussions on how SD shall be realized with IPC-Clients. + +.. + # fix #1424 SOME/IP Gateway in lifecycle-management + +SOME/IP Gateway processes and life cycle management +--------------------------------------------------- + +The implementation of a gateway likely requires using one or multiple processes. Startup of processes for the gateway, as with any other +process in the S-CORE system, need to be put under the control of lifecycle-management (see feature Lifecycle). +Hence the SOME/IP Gateway must not start any processes on its own, but configure the lifecycle launch and health-monitoring accordingly. +Specifically for the integration of the SOME/IP Stack "plug-in", which is expected to be QM, whereas the rest of the gateway is ASIL-B, +if one or more additional processes need to be spawned and additional executables need to be involved with the implementation, +all need to go into launch control in health monitoring and must not be setup (fork()) by the gateway. + SOME/IP Gateway Security Goals ------------------------------ -As with IPC generally, the security approach for SOME/IP gateway shall achieve the following security goals: +The security approach for SOME/IP gateway shall achieve the following security goals: + +- access control (:need:`feat_req__com__acl_per_service_instance`) -- confidentiality (:need:`feat_req__ipc__confidentiality`) -- integrity (:need:`feat_req__ipc__integrity`) -- availability (per criticality-level) (:need:`feat_req__ipc__availability`) -- secure communication (:need:`feat_req__some_ip_gateway__secure_com`) -- access control (:need:`feat_req__some_ip_gateway__access_control`) +The SOME/IP Gateway service instance shall be defined in the deployment configuration. + +- :need:`ACL Placement ` Backwards Compatibility ======================= -As there is currently no previous solution for communication in S-CORE, no backwards compatibility is required. +As there is currently no previous solution for gateways in S-CORE, no backwards compatibility is required. Subsequent changes to the SOME/IP gateway module shall keep the API stable where possible and introduce breaking APIs only with approval from tech lead circle. Applications shall stay stable on API layer, need to recompile is acceptable. Security Impact =============== -There are multiple protocols targeting secure communication. In general a holistic security concept for a vehicle will not apply all together. - -.. figure:: assets/some_ip_gateway_sec_protocols.drawio.svg - :align: center - :name: some_ip_gateway_sec_protocols_ - - Secure communication protocols - +Be aware, communication with SOME/IP generally is considered to be not secure. Integrators may apply measures that are outside the +scope of the SOME/IP gateway to secure the communication (IPsec, MACsec, ...). .. note:: - Access Control List (ACL) is not a security protocol, but a mechanism to restrict access to the SOME/IP Gateway services and tylically allocated within the stateful packet inspection firewall. + it is expected that a feature request for crypto and security will cover the necessary measures. + `Feature Request for Security & Crypto `_ -Scope ------ -As the SOME/IP gateway will open direct communication channels via SOME/IP, where the SOME/IP implementation shall comply with standard security requirements. +Access Control List (ACL) +------------------------- -Since SOME/IP is a protocol relies on the security of the underlying transport layer, the SOME/IP gateway makes use of the security features relevant for it. This includes: +The gateway shall only forward selective service instances originating from IP addresses configured in an allow-list. +The logic required for this is protocol specific and therefore part of this feature request. -- VLAN (= Virtual Local Area Network): A virtual interface that separates ethernet network packets identified by a VLAN ID -- MACsec: Provides L2 data Integrity, Authenticity and optionally Confidentiality for point-to-point communication. -- IPsec: A network layer protocol suite that secures network connections by encrypting and/or authenticating IP packets. -- TLS (= Transport Layer Security): Authentication, integrity, confidentiality of TCP channels -> Protection for one to one communication. -- DTLS (= Datagram Transport Layer Security): Authentication, integrity, confidentiality of UDP packets -> Protection for multicast communication. -- ACL (= Access Control List): A filter mechanism to ensure that only allowed SOME/IP communication can take place. - -Features included `Feature Request for Security & Crypto `_ e.g cryptographic algorithms, symmetric-, asymmetric encryption, Signature functionality, Certificate management, certificate management, entropy generation, data integrity, key management, are out of scope. - - -Access Control List -------------------- +Be aware that an additional security mechanism may be necessary that ensures that IP addresses are not forged. This mechanism is out of scope of this feature. An access control mechanism is part of a firewall solution, which states that only the traffic defined in the security policy is allowed onto the network and all other traffic must be silently dropped. -Access Control acts on OSI Layer 5-7. It shall fulfill following: +Access Control acts on OSI Layer 5-7. It shall fulfill the following: -- Whitelisting of SOME/IP services and methods based on IP addresses and therefore IP address authenticity. -- A static list which could be updated via OTA (= Over-The-Air) updates. -- Versioning -- ACL shall be able to be switched on/off to allow bypassing in an secured environment e.g. engineering mode or repair shop. -- ACL drop actions shall be logged persistently via a DTC (= Diagnostic Trouble Code) including needed environment data to clearly understand the context of the drop, including the sender, timestamp, Service ID and Instance ID. -- To avoid code injection attacks, into services of the system, only authenticated and authorized communication partners are allowed to write or delete entries into the **Service Registry**. +- What SOME/IP service instances to forward +- What IP address is allowed to offer a SOME/IP service instance +- Configuration of ACL is done at deployment +- Versioning of services +- ACL, or single parameters of it, shall be able to be switched on/off +- It shall be possible to persistently log ACL drop actions .. note:: - Checking SOME/IP-SD messages with the ACL is optional because no functional data is transported. - - SOME/IP-SD messages are not protected as per AUTSAR Adaptive specification. + - SOME/IP-SD messages are not protected as per AUTOSAR Adaptive specification. .. uml:: @@ -197,75 +204,46 @@ Access Control acts on OSI Layer 5-7. It shall fulfill following: stop -E2E and CRC (Informal Notes) ----------------------------- - -There are several E2E (= End-to-End) profiles, which utilize various CRC routines as part of AUTOSAR E2E Protocol Specification: - -- CRC8 (SAEJ1850) -- CRC8H2F (0x2F polynomial) -- CRC16 (also known as CCITT-FALSE 16-bit CRC) -- CRC32 (also known as IEEE 802.3 Ethernet 32-bit CRC) -- CRC32P4 (0xF4ACFB13 polynomial) -- CRC64 (CRC-64-ECMA) -- CRC32_J1939 (0x6938392D polynomial) (used by Profile 76). - -These routines can be implemented using different calculation methods: - -- Table based calculation for faster execution, but requiring a larger code size due to ROM tables. -- Runtime calculation for smaller code size (no ROM table), but resulting in slower execution. -- Hardware supported CRC calculation (device-specific) for fast execution and less CPU time. - -The E2E Library itself does not provide CRC routine implementations, instead, it calls the CRC routines from a dedicated CRC library. -It is also a requirement that the CRC used in an E2E profile must be different from the CRC used by the underlying physical communication protocol. +Safety Impact +============= -All E2E profiles can be used in combination with SOME/IP, although specific profiles may have limitations regarding maximum data length or being restricted to fixed-length messages. +SOME/IP stack and underlying OS network stacks are typically QM only. Freedom from interference needs to be respected between the +safety classified IPC component (mw::com) and the SOME/IP stack which is part of the gateway. The SOME/IP communication itself needs +to be properly protected by E2E to maintain a safe communication via the grey SOME/IP channel. -For E2E protection with SOME/IP, the CRC is calculated over specific parts of the serialized SOME/IP message: +End-to-End (E2E) protection with CRC and counters +------------------------------------------------- -- For profiles 1, 2, 4, 5, 6, 7, 11, and 22, which are typically used for signal-based or periodic event-based communication, the E2E CRC should be calculated over the following elements of the serialized SOME/IP message: +Applications communicating over the network may have to protect data with end-to-end protection (E2E), which may involve +CRC-protection and checks, and message counters. - - Request ID (Client ID / Session ID) - - Protocol Version - - Interface Version - - Message Type - - Return Code - - Payload +There are several E2E (= End-to-End) profiles, which utilize various CRC routines as part of AUTOSAR E2E Protocol Specification, that shall be supported with the SOME/IP Gateway. -- For profiles 4m, 7m, 8m, and 44m, which are designed for method-based (client-server) communication, the E2E CRC shall be calculated over specific parts of the serialized SOME/IP message. These method-specific profiles incorporate additional fields like Message Type and Message Result within their E2E headers to distinguish between request and response messages and their outcomes. +Though the implementation of the SOME/IP protocol itself is likely not going to be ASIL-B compliant and have a safety consideration of QM rather, +E2E-checks and protection need to happen in an ASIL-B context. The gateway may perform the CRC routines as a central service. +All communication channels (IPC) to this central service must be qualified for ASIL-B, and protected against data loss / loss of samples. -The E2E communication protection process involves the sender adding control fields, including the CRC, to the transmitted data, and the receiver then evaluating these fields upon reception. -The middleware, is responsible for determining parameters like DataID, Message Type, Message Result, and SourceID from the exchanged information and then invoking the E2E functions. -The CRC is calculated over the entire E2E header (excluding the CRC bytes themselves) and the user data. -For some profiles (e.g., Profile 5, 6, 22), the Data ID is included as an extension at the end of the user data for CRC calculation, even if it is not explicitly transmitted. +SOME/IP Events, Methods, and Fields need to be supported with E2E protection. +Please refer to the SOME/IP Gateway architecture for further details. References - `AUTOSAR_FO_PRS_E2EProtocol `_ - `AUTOSAR_FO_RS_E2E `_ -SecOC (Informal Notes) ----------------------- - -- The SecOC protocol provides a mechanism to verify the authenticity and integrity but lacks of confidentiality. -- SecOC (= Secured Onboard Communication) does not offer encryption support by design. -- In contrast to SecOC, TLS can protect all payload of an AUTOSAR PDU including the AUTOSAR PDU header used which overlaps with the SOME/IP message header. -- In case of SOME/IP protocol, the SOME/IP message id can not be protected by SecOC, because it is stripped before SecO is invoked. - - -Safety Impact -============= - -SOME/IP stack and underlying OS network stacks are typically QM only. Freedom from interference needs to be respected between the -safty classified IPC component (mw::com) and the SOME/IP stack which is part of the gateway. The SOME/IP communication itself needs -to be properly protected by E2E to maintain a safe communication via the grey SOME/IP channel. - License Impact ============== [How could the copyright impacted by the license of the new contribution?] +Since SOME/IP is a protocol, including applied E2E protection and the according profile (polynom, etc.), +defined by AUTOSAR and published under the license of AUTOSAR, the gateway implementation shall carefully distinguish between the SOME/IP communication stack, +the E2E protection of data, and the integration into S-CORE mw::com. Breach of foreign licenses must be avoided. + +Anybody using SOME/IP Gateway needs to make sure to follow the license conditions and rules of AUTOSAR. How to Teach This ================= + +TBD diff --git a/docs/features/communication/some_ip_gateway/requirements/index.rst b/docs/features/communication/some_ip_gateway/requirements/index.rst index ddfbf161c5b..bc26141f5f7 100644 --- a/docs/features/communication/some_ip_gateway/requirements/index.rst +++ b/docs/features/communication/some_ip_gateway/requirements/index.rst @@ -19,50 +19,59 @@ SOME/IP Gateway Requirements Functional Requirements ======================= - - -Security Impact -=============== - -.. feat_req:: SOME/IP Gateway Secure Communication - :id: feat_req__some_ip_gateway__secure_com +.. feat_req:: Plug-In-IFC for SOME/IP protocol stacks + :id: feat_req__some_ip_gateway__stack_plugin_ifc :reqtype: Functional - :security: YES + :security: NO :safety: QM - :satisfies: stkh_req__communication__secure + :satisfies: stkh_req__communication__extensible_external, stkh_req__communication__supported_net :status: valid - The platform shall support secure communication. + The SOME/IP Gateway shall support an interface to plug-in a SOME/IP stack implementation. -.. feat_req:: SOME/IP Gateway Access Control - :id: feat_req__some_ip_gateway__access_control +.. feat_req:: Plug-In-IFC for End-to-End protection modules + :id: feat_req__some_ip_gateway__e2e_plugin_ifc :reqtype: Functional - :security: YES - :safety: QM - :satisfies: stkh_req__dependability__security_features + :security: NO + :safety: ASIL_B + :satisfies: stkh_req__communication__safe :status: valid - The SOME/IP Gateway shall support access control to restrict access to the gateway services. + The SOME/IP Gateway shall support an interface to plug-in a E2E protection service implementation. -Safety Impact -============= +.. feat_req:: Compatibility with AUTOSAR SOME/IP Protocol Specification + :id: feat_req__some_ip_gateway__someip_protocol + :reqtype: Functional + :security: NO + :safety: ASIL_B + :satisfies: stkh_req__communication__supported_net + :status: valid + + The SOME/IP protocol implementation shall be fully compatible and complying with the SOME/IP protocol specification from AUTOSAR Adaptive Version 24-11. + - `AUTOSAR_FO_PRS_SOMEIPProtocol `_ + - `AUTOSAR_FO_RS_SOMEIPProtocol `_ -.. feat_req:: SOME/IP Gateway ASIL level - :id: feat_req__some_ip_gateway__asil +.. feat_req:: Compatibility with AUTOSAR E2E Protocol Specification + :id: feat_req__some_ip_gateway__e2e_specs :reqtype: Functional - :security: YES + :security: NO :safety: ASIL_B - :satisfies: stkh_req__communication__safe + :satisfies: stkh_req__communication__supported_net :status: valid - The SOME/IP Gateway shall support safe communication up to ASIL-B. + The E2E protection implementation shall be fully compatible and complying with the E2E protocol specification from AUTOSAR Adaptive Version 24-11. + - `AUTOSAR_FO_PRS_E2EProtocol `_ + - `AUTOSAR_FO_RS_E2E `_ + -.. feat_req:: SOME/IP Gateway QM network stack - :id: feat_req__some_ip_gateway__network_stack +.. feat_req:: Compatibility with AUTOSAR SOME/IP Service Discovery Protocol Specification + :id: feat_req__some_ip_gateway__someip_sd_protocol :reqtype: Functional - :security: YES + :security: NO :safety: ASIL_B - :satisfies: stkh_req__communication__safe + :satisfies: stkh_req__communication__supported_net :status: valid - If SOME/IP network stacks are available as QM only. + The Service Discovery implementation shall be fully compatible and complying with the SOME/IP service discovery specification from AUTOSAR Adaptive Version 24-11. + - `AUTOSAR_FO_PRS_SOMEIPServiceDiscoveryProtocol `_ + - `AUTOSAR_FO_RS_SOMEIPServiceDiscoveryProtocol `_ diff --git a/docs/features/communication/some_ip_gateway/service_discovery/index.rst b/docs/features/communication/some_ip_gateway/service_discovery/index.rst index e56a5d1e138..cee8f4ac6db 100644 --- a/docs/features/communication/some_ip_gateway/service_discovery/index.rst +++ b/docs/features/communication/some_ip_gateway/service_discovery/index.rst @@ -14,17 +14,18 @@ .. _some_ip_gateway_service_discovery: -SOME/IP-Gateway Service Discovery +SOME/IP Gateway Service Discovery ################################# +The implementation shall be fully compatible and complying with the SOME/IP Service Discovery Protocol specification from AUTOSAR Adaptive. Service discovery deals with discovery and connection setup of services. The basic summary of service discovery is as follows: - provided / required services (including their service elements like events, methods, and fields) must be configured - (locally) provided services are discovered (locally) via IPC and then offered on the network by sending a SOME/IP-SD message with an OfferService entry according to configuration -- (locally) required services may trigger the discovery on the network by sending of a SOME/IP-SD message with a FindService entry +- (locally) required services trigger the discovery on the network by sending of a SOME/IP-SD message with a FindService entry - when a SOME/IP-SD message containing a FindService entry is received, the SOME/IP gateway checks this service has been already offered locally via IPC -- for IPC service discovery the features of lola are used by the SOME/IP gateway +- the IPC service discovery is used by the SOME/IP gateway and no parallel discovery mechanism is introduced Configuration ============= @@ -32,6 +33,7 @@ Configuration The configuration tells the SOME/IP communication stack which services it should provide and which services it should require on the network. The configuration contains SOME/IP and SOME/IP-SD settings as well as IP interface bindings. Events, methods and fields are configured as well. +Only full interfaces of services are forwarded (all events, methods, fields of a service). The integrator must be able to change configuration at runtime deployment. Thus it is likely read from one or multiple files. @@ -116,7 +118,7 @@ Here, initial reception is the first reception after a previous service loss or This behavior may reduce the time until the service is available for consumers, but may increase boot time. Thus the decision is to create the service only after having received an OfferService message from the network. -Upon reception of SOME/IP-SD message containing an StopOfferService entry, the SOME/IP communication stack stops the proxy service offered via IPC as well. +Upon reception of SOME/IP-SD message containing an StopOfferService entry, the SOME/IP communication stack stops the service offered via IPC as well. .. uml:: :alt: Gateway receives StopOfferService from the network @@ -163,7 +165,7 @@ Only lookup of running services is done. end @enduml -If an service is configured to be needed and no OfferService has been received yet, the SOME/IP communication stack may send a SOME/IP-SD message containing a FindService entry. +If a service is configured to be needed and no OfferService has been received yet, the SOME/IP communication stack shall send a SOME/IP-SD message containing a FindService entry. .. uml:: :alt: Gateway sends FindService to the network