module ara::fw — Firewall

The Functional Cluster Firewall filters network packets according to state-dependent rule sets from the manifest and reports blocked packets as Security Events to the IdsM (EXP_PlatformDesign p. 92). Applications select the active firewall state via FirewallStateSwitchInterface::SwitchFirewallState. The method returns a ara::core::Future<void> and reports errors such as kServiceNotAvailable or kInvalidStateDependentFirewall [AP_SWS_Fw_82008]. The states are not a fixed list, but are generated as an enumeration for each modeled interface. Instances of the interface can only be moved, not copied.

more ›

The module fw specifies the daemon-based Functional Cluster Firewall of the Adaptive Platform. Its application API is the interface FirewallStateSwitchInterface with the operation SwitchFirewallState(), which is used by an Adaptive Application (EXP_SWArchitecture p. 126). The cluster has two tasks: it switches the firewall state and reports Security Events to the Intrusion Detection System Manager (EXP_SWArchitecture p. 197).

Context diagram: The FC Firewall connects manifest configuration, state specification by the application, rule enforcement in the operating system, and SEv reporting to the IdsM. Sources: EXP_PlatformDesign p. 97, EXP_SWArchitecture p. 197

Filtering is state-dependent. The OEM defines states such as driving, parking, or diagnostics, and only the rules of the active state apply to a packet (EXP_PlatformDesign p. 92). In the manifest, AdaptiveFirewallModuleInstantiation bundles StateDependentFirewall elements for this purpose. Each of these contains ordered rule properties, an optional defaultAction, and references to the associated states (TPS_ManifestSpecification p. 679). In the code, the states appear as an enumeration generated per interface in ara::fw::states [AP_SWS_Fw_81001].

The application creates the interface object from an ara::core::InstanceSpecifier. This constructor is thread-safe [AP_SWS_Fw_82002]. SwitchFirewallState is noexcept and returns a ara::core::Future<void> [AP_SWS_Fw_82008]. Internally, according to the scenario, the cluster applies each firewall rule individually in the operating system (EXP_SWArchitecture p. 232). Instances cannot be copied, but they can be moved. Move and destructor are not thread-safe [AP_SWS_Fw_82004] [AP_SWS_Fw_82006].

Sequence diagram: The request for the state change returns as a future. In between, each rule is applied individually. Sources: EXP_SWArchitecture p. 232, [AP_SWS_Fw_82008]

In case of an error, the future contains FwErrc::kServiceNotAvailable or FwErrc::kInvalidStateDependentFirewall [AP_SWS_Fw_83001]. The meaning can only be deduced from the names: presumably the service is unavailable, or a valid rule configuration is missing for the target state. Question Q-45e3225696efb3dc (open) An error can be thrown as FwException via FwErrorDomain::ThrowAsException [AP_SWS_Fw_83012]. Blocked packets are not an API error. They are reported as Security Events to the IdsM, additionally distinguished by diverging protocol in R23-11 (SWS_Firewall p. 31).

more ›

Role of the FC Firewall between Application, Operating System, and IdsM

The module fw describes the Functional Cluster Firewall of the Adaptive Platform. It is daemon-based and implements the interface FirewallStateSwitchInterface with the operation SwitchFirewallState(). An Adaptive Application uses this interface via a «use» relationship (EXP_SWArchitecture p. 126). The use cases limit the cluster to two tasks. "Switch Firewall State" is triggered by the Adaptive Application, with the operating system participating. "Report Security Event" is directed at the likewise daemon-based Intrusion Detection System Manager (EXP_SWArchitecture p. 197).

The architectural overview separates configuration, control, and execution from each other:

• The Machine Manifest provides the filter rules.
• The FC Firewall uses them to configure a firewall engine.
• An OEM application sets the firewall state.
• The cluster reports Security Events (SEvs) to the IdsM (EXP_PlatformDesign p. 97).

Two use cases are in the foreground. The first is state-dependent filtering with OEM-specific states such as driving, parking, or diagnostic session. The second is supporting the intrusion detection system via Security Events for blocked messages. Qualification, forwarding to a SOC, or persistent storage is handled by the IdsM (EXP_PlatformDesign p. 92). The module's only application API is the state change [AP_SWS_Fw_82008].

Context diagram: The FC Firewall receives configuration from the Machine Manifest and state specifications from the application. It controls the engine and operating system and reports SEvs to the IdsM. Sources: EXP_PlatformDesign p. 97, EXP_SWArchitecture p. 197, EXP_SWArchitecture p. 232

Firewall States: from the State Machine in the Model to the Generated Enumeration

In the manifest metamodel, FirewallStateSwitchInterface specializes an PortInterface. Via the role firewallStateMachine, it aggregates any number (0..*) of ModeDeclarationGroupPrototype elements (TPS_ManifestSpecification p. 263). The individual states are ModeDeclarations with the optional attribute value: PositiveInteger (TPS_ManifestSpecification p. 679).

For each modeled interface, a dedicated enumeration enum class {<fwssi-sn>} : std::uint32_t is generated in the namespace ara::fw::states. It is included via ara/fw/states/{<fwssi-sn>}.h [AP_SWS_Fw_81001]. An enumerator {<symbol-fw-state>} = {<fw-state-value>} is generated for each modeled firewall state [AP_SWS_Fw_81002].

For users, this means: There is no platform-wide fixed list of states. Which states exist is defined by the OEM model (EXP_PlatformDesign p. 92). SwitchFirewallState expects a parameter firewallState of type EnumT [AP_SWS_Fw_82008]. Interpretation: EnumT is likely to correspond to the state enumeration generated for the respective interface. Question Q-26dbe38f70cb0222 (open) This is supported by the fact that [AP_SWS_Fw_81001] explicitly defines them as states "for FirewallStateSwitchInterface".

Context diagram (model–code): The states originate from the state machine of the interface in the model. An enumeration is generated in ara::fw::states for each interface. Sources: TPS_ManifestSpecification p. 263, [AP_SWS_Fw_81001], [AP_SWS_Fw_81002], [AP_SWS_Fw_82008]

Manifest Configuration: Module Instance, State-Dependent Rule Sets, and Port Mapping

The machine-specific settings of the firewall module are collected in AdaptiveFirewallModuleInstantiation. The associated specification has the status DRAFT in R25-11 (TPS_ManifestSpecification p. 677). The module instance specializes NonOsModuleInstantiation and references any number of StateDependentFirewall elements via stateDepFirewall.

A StateDependentFirewall contains:

• optionally an defaultAction of type FirewallActionEnum,
• ordered firewallRuleProps,
• via firewallState (instanceRef), references to the ModeDeclarations in which it applies (TPS_ManifestSpecification p. 679).

The System Template concisely describes them as "Firewall rules that are defined in a firewall state" (TPS_SystemTemplate p. 644).

The rules themselves are FirewallRule elements with attributes such as bucketSize and refillAmount. In addition, the metamodel lists NetworkLayerRule and TransportLayerRule, the latter including port ranges and checksumVerification. A CouplingElement can also aggregate rules via firewallRule (TPS_ManifestSpecification p. 679). For details, the System Template explicitly refers to the manifest specification (TPS_SystemTemplate p. 644).

The connection to the application is established by AdaptiveFirewallToPortPrototypeMapping. It maps the module instance (reference firewall, 0..1) to the RPortPrototype of the application, which is typed by the state switch interface (TPS_ManifestSpecification p. 677). Two limitations apply:

• The class note names the interface FirewallModeSwitchInterface, whereas the figure title and API name it FirewallStateSwitchInterface. For the code, the name from [AP_SWS_Fw_82002] is decisive.
• The mapping class and its reference have the status candidate (TPS_ManifestSpecification p. 677).

Context diagram (metamodel): The module instance bundles state-dependent rule sets. The mapping connects them to the R-Port of the application. Sources: TPS_ManifestSpecification p. 677, TPS_ManifestSpecification p. 679, TPS_ManifestSpecification p. 677

Sequence of a State Change with SwitchFirewallState

On the code side, the application includes ara/fw/firewall_state.h. It creates ara::fw::FirewallStateSwitchInterface via the explicit constructor from an ara::core::InstanceSpecifier. This constructor is noexcept and thread-safe [AP_SWS_Fw_82002].

The state change is requested by SwitchFirewallState(EnumT firewallState). The method is noexcept and returns a ara::core::Future<void>. The errors specified for it, FwErrc::kServiceNotAvailable and FwErrc::kInvalidStateDependentFirewall, therefore return via the future and not as an exception [AP_SWS_Fw_82008].

The "Switch Firewall State" scenario shows the internal sequence in three steps (EXP_SWArchitecture p. 232):

1. The application calls SwitchFirewallState() on the FC Firewall.
2. In a loop "foreach FirewallRule", the cluster calls applyRule() on the operating system in each iteration.
3. Only after the loop does the response return to the application.

applyRule() is marked there as «aapInformative». How the rules are activated in the operating system is not defined as a platform API in the payload. The R22-11 version showed the same sequence as a successful scenario (EXP_SWArchitecture p. 158). After the switch, only the rules of the active state check and filter (EXP_PlatformDesign p. 92).

Sequence diagram: The state change is reported back asynchronously via a future. Internally, the cluster applies each rule individually. Sources: EXP_SWArchitecture p. 232, [AP_SWS_Fw_82002], [AP_SWS_Fw_82008]

Lifetime, Copy, and Move Rules of the Interface Class

The special member functions of FirewallStateSwitchInterface specify how instances may be passed on ([AP_SWS_Fw_82003] to [AP_SWS_Fw_82007]):

Element	Specification	Thread safety
Constructor from InstanceSpecifier	explicit, noexcept [AP_SWS_Fw_82002]	thread-safe
Copy constructor / copy assignment	=delete [AP_SWS_Fw_82004] [AP_SWS_Fw_82005]	–
Move constructor / move assignment	noexcept [AP_SWS_Fw_82006] [AP_SWS_Fw_82007]	not thread-safe
Destructor	noexcept [AP_SWS_Fw_82003]	not thread-safe

From this follow three rules for usage:

• An instance cannot be duplicated, but can only be passed on via move [AP_SWS_Fw_82004] [AP_SWS_Fw_82006].
• Move and destruction must be protected by the application itself against concurrent access [AP_SWS_Fw_82003].
• Interpretation: A source object after a move should presumably no longer be used for SwitchFirewallState, because the requirements describe only the transfer, but not the residual state [AP_SWS_Fw_82007]. Question Q-ccf0737ee5133103 (open)

The requirement text makes no statement regarding the thread safety of SwitchFirewallState itself [AP_SWS_Fw_82008].

State diagram: An instance is created from an InstanceSpecifier, transferred only via move, and finally destroyed. Sources: [AP_SWS_Fw_82002], [AP_SWS_Fw_82003], [AP_SWS_Fw_82006], [AP_SWS_Fw_82007]

Packet Filtering in the Active State and Reporting of Security Events

Firewall rules can be assigned to a firewall state. To check a packet, only the rules of the currently active state are used (EXP_PlatformDesign p. 92). For each state, the StateDependentFirewall provides the ordered rule properties and the optional defaultAction (TPS_ManifestSpecification p. 679).

The SWS version R23-11 describes the mapping of Security Events in more detail (SWS_Firewall p. 31):

• If a packet does not match any rule, the default action applies.
• If the default action blocks the packet, the cluster determines the diverging protocol. The decisive factor is the rule with the most matching ISO/OSI layers, counted starting from the lowest layer. The first non-matching layer above it determines the protocol.
• For this protocol, an SEv is reported to the IdsM, such as SEV_FW_PACKET_BLOCKED_DATALINKLAYER_MISMATCH (Ethernet), SEV_FW_PACKET_BLOCKED_IPV4_MISMATCH, SEV_FW_PACKET_BLOCKED_IPV6_MISMATCH, or SEV_FW_PACKET_BLOCKED_ICMP_MISMATCH.

These details originate from R23-11. The associated requirements are not part of the R25-11 payload and are therefore reproduced here explanatorily, not normatively. According to the architecture description, the principle that blocked messages are sent as SEvs to the IdsM also applies to R25-11 (EXP_PlatformDesign p. 92).

Activity diagram: A packet is checked against the rules of the active state. A default block results in a protocol-specific SEv to the IdsM. Sources: EXP_PlatformDesign p. 92, SWS_Firewall p. 31 (R23-11)

Behavior in the event of an error

The module's error codes are defined by FwErrc in the header ara/fw/fw_error_domain.h: kServiceNotAvailable=1 and kInvalidStateDependentFirewall=2 [AP_SWS_Fw_83001]. Both are specified as possible errors for SwitchFirewallState [AP_SWS_Fw_82008]. Interpretation of the names, since the requirements do not state any trigger conditions:

• kServiceNotAvailable is likely to report that the daemon-based FC Firewall cannot provide the service. Question (open)
• kInvalidStateDependentFirewall is likely to report that no valid StateDependentFirewall exists for the requested state. Question (open)

The error domain follows the usual ara::core pattern:

• GetFwErrorDomain() returns the domain in a thread-safe manner [AP_SWS_Fw_83002]. The default constructor of FwErrorDomain is deleted [AP_SWS_Fw_83009].
• MakeErrorCode creates an ara::core::ErrorCode [AP_SWS_Fw_83003].
• Name() and Message() provide domain name and error text [AP_SWS_Fw_83010] [AP_SWS_Fw_83011].
• The aliases Errc and Exception refer to FwErrc and FwException [AP_SWS_Fw_83007] [AP_SWS_Fw_83008].

Those working with exceptions can convert an error code into an FwException via ThrowAsException. This function is noexcept(false) and classified as "not exception safe" [AP_SWS_Fw_83012] [AP_SWS_Fw_83005]. In contrast, blocked packets are not an API error. They appear as Security Events at the IdsM (EXP_PlatformDesign p. 92).

Activity diagram: The result of the state change is evaluated via the future. Errors are handled via FwErrorDomain and can optionally be thrown as FwException. Sources: [AP_SWS_Fw_82008], [AP_SWS_Fw_83001], [AP_SWS_Fw_83011], [AP_SWS_Fw_83012]

Further detailed evidence

The following locations support the statements of this guide; the requirements are normative for R25-11 ([AP_SWS_Fw_82008]).

• [AP_SWS_Fw_82008]: sole functional operation with return type and error list.
• [AP_SWS_Fw_82002], [AP_SWS_Fw_82003]: construction and destruction of the interface class including thread safety.
• [AP_SWS_Fw_81001], [AP_SWS_Fw_81002]: generated state types.
• [AP_SWS_Fw_83001], [AP_SWS_Fw_83012]: error codes and conversion into exceptions.
• EXP_SWArchitecture p. 126, EXP_SWArchitecture p. 197: interface and use cases.
• EXP_SWArchitecture p. 232: sequence of the state change. The preceding version from R22-11 is in EXP_SWArchitecture p. 158.
• TPS_ManifestSpecification p. 263, TPS_ManifestSpecification p. 679: state machine and rule model.
• TPS_SystemTemplate p. 644: short description of StateDependentFirewall. The version from R23-11 is in TPS_SystemTemplate p. 583.
• SWS_Firewall p. 31: SEv assignment for default blocking, only in version R23-11.