módulo ara::fw — Firewall

O Functional Cluster Firewall filtra pacotes de rede de acordo com conjuntos de regras dependentes de estado provenientes do manifesto e reporta pacotes bloqueados como Security Events ao IdsM (EXP_PlatformDesign p. 92). Aplicações selecionam o estado ativo de Firewall via FirewallStateSwitchInterface::SwitchFirewallState. O método retorna um ara::core::Future<void> e reporta erros como kServiceNotAvailable ou kInvalidStateDependentFirewall [AP_SWS_Fw_82008]. Os estados não são uma lista fixa, sendo gerados como enumeração para cada interface modelada. Instâncias da interface podem ser apenas movidas, não copiadas.

mais ›

O módulo fw especifica o Functional Cluster Firewall baseado em daemon da Adaptive Platform. Sua API de aplicação é a interface FirewallStateSwitchInterface com a operação SwitchFirewallState(), utilizada por uma Adaptive Application (EXP_SWArchitecture p. 126). O cluster possui duas tarefas: ele comuta o estado de Firewall e reporta Security Events ao Intrusion Detection System Manager (EXP_SWArchitecture p. 197).

Diagrama de contexto: o FC Firewall conecta configuração de manifesto, especificação de estado da aplicação, aplicação de regras no sistema operacional e notificação de SEv ao IdsM. Fontes: EXP_PlatformDesign p. 97, EXP_SWArchitecture p. 197

A filtragem é dependente de estado. O OEM define estados como dirigir, estacionar ou diagnóstico, e para um pacote aplicam-se apenas as regras do estado ativo (EXP_PlatformDesign p. 92). No manifesto, AdaptiveFirewallModuleInstantiation agrupa elementos StateDependentFirewall para essa finalidade. Cada um deles contém propriedades ordenadas de regra, um defaultAction opcional e referências aos estados correspondentes (TPS_ManifestSpecification p. 679). No código, os estados aparecem como enumeração gerada por interface em ara::fw::states [AP_SWS_Fw_81001].

A aplicação cria o objeto de interface a partir de um ara::core::InstanceSpecifier. Esse construtor é thread-safe [AP_SWS_Fw_82002]. SwitchFirewallState é noexcept e retorna um ara::core::Future<void> [AP_SWS_Fw_82008]. Internamente, segundo o cenário, o cluster aplica cada regra de Firewall individualmente no sistema operacional (EXP_SWArchitecture p. 232). Instâncias não podem ser copiadas, mas podem ser movidas. Move e destrutor não são thread-safe [AP_SWS_Fw_82004] [AP_SWS_Fw_82006].

Diagrama de sequência: a solicitação de mudança de estado retorna como Future. No intervalo, cada regra é aplicada individualmente. Fontes: EXP_SWArchitecture p. 232, [AP_SWS_Fw_82008]

Em caso de erro, o Future contém FwErrc::kServiceNotAvailable ou FwErrc::kInvalidStateDependentFirewall [AP_SWS_Fw_83001]. O significado só pode ser deduzido a partir dos nomes: o serviço presumivelmente não está disponível ou falta uma configuração válida de regras para o estado de destino. Pergunta Q-45e3225696efb3dc (aberta) Por meio de FwErrorDomain::ThrowAsException, um erro pode ser lançado como FwException [AP_SWS_Fw_83012]. Pacotes bloqueados não são um erro de API. Eles são reportados como Security Events ao IdsM, sendo distinguidos adicionalmente por protocolo divergente em R23-11 (SWS_Firewall p. 31).

mais ›

Papel do FC Firewall entre aplicação, sistema operacional e IdsM

O módulo fw descreve o Functional Cluster Firewall da Adaptive Platform. Ele é baseado em daemon e realiza a interface FirewallStateSwitchInterface com a operação SwitchFirewallState(). Uma Adaptive Application utiliza essa interface por meio de uma relação de «use» (EXP_SWArchitecture p. 126). Os casos de uso restringem o cluster a duas tarefas. «Switch Firewall State» é acionado pela Adaptive Application, com a participação do sistema operacional. «Report Security Event» destina-se ao Intrusion Detection System Manager, também baseado em daemon (EXP_SWArchitecture p. 197).

A visão geral da arquitetura separa configuração, controle e execução entre si:

• O Machine Manifest fornece as regras de filtragem.
• O FC Firewall configura com isso uma Firewall Engine.
• Uma aplicação OEM define o estado de Firewall.
• O cluster reporta Security Events (SEvs) ao IdsM (EXP_PlatformDesign p. 97).

Em primeiro plano estão dois casos de uso. O primeiro é a filtragem dependente de estado com estados específicos do OEM, como dirigir, estacionar ou sessão de diagnóstico. O segundo é o suporte ao Intrusion Detection System por meio de Security Events em caso de mensagens bloqueadas. Qualificação, encaminhamento a um SOC ou armazenamento persistente são assumidos pelo IdsM (EXP_PlatformDesign p. 92). A única API de aplicação do módulo é a mudança de estado [AP_SWS_Fw_82008].

Diagrama de contexto: o FC Firewall recebe configuração do Machine Manifest e especificações de estado da aplicação. Ele controla a engine e o sistema operacional e reporta SEvs ao IdsM. Fontes: EXP_PlatformDesign p. 97, EXP_SWArchitecture p. 197, EXP_SWArchitecture p. 232

Estados de Firewall: da máquina de estados no modelo à enumeração gerada

No metamodelo de manifesto, FirewallStateSwitchInterface especializa um PortInterface. Por meio do papel firewallStateMachine, ele agrega quantos elementos ModeDeclarationGroupPrototype forem necessários (0..*) (TPS_ManifestSpecification p. 263). Os estados individuais são ModeDeclarations com o atributo opcional value: PositiveInteger (TPS_ManifestSpecification p. 679).

Para cada interface modelada, gera-se a partir disso uma enumeração própria enum class {<fwssi-sn>} : std::uint32_t no namespace ara::fw::states. Ela é incluída via ara/fw/states/{<fwssi-sn>}.h [AP_SWS_Fw_81001]. Para cada estado de Firewall modelado, surge um enumerador {<symbol-fw-state>} = {<fw-state-value>} [AP_SWS_Fw_81002].

Para os usuários, isso significa: não há uma lista de estados fixa em toda a plataforma. Quais estados existem é determinado pelo modelo do OEM (EXP_PlatformDesign p. 92). SwitchFirewallState espera um parâmetro firewallState do tipo EnumT [AP_SWS_Fw_82008]. Interpretação: EnumT deve corresponder à enumeração de estados gerada para a respectiva interface. Pergunta Q-26dbe38f70cb0222 (aberta) A favor disso está o fato de que [AP_SWS_Fw_81001] os define expressamente como estados «for FirewallStateSwitchInterface».

Diagrama de contexto (modelo–código): os estados provêm da máquina de estados da interface no modelo. Para cada interface, é gerada uma enumeração em ara::fw::states. Fontes: TPS_ManifestSpecification p. 263, [AP_SWS_Fw_81001], [AP_SWS_Fw_81002], [AP_SWS_Fw_82008]

Configuração de manifesto: instância do módulo, conjuntos de regras dependentes de estado e mapeamento de portas

As configurações específicas de máquina do módulo Firewall são reunidas em AdaptiveFirewallModuleInstantiation. A definição correspondente possui o status DRAFT em R25-11 (TPS_ManifestSpecification p. 677). A instância do módulo especializa NonOsModuleInstantiation e referencia, por meio de stateDepFirewall, qualquer quantidade de elementos StateDependentFirewall.

Uma StateDependentFirewall contém:

• opcionalmente uma defaultAction do tipo FirewallActionEnum,
• firewallRuleProps ordenadas,
• referências, via firewallState (instanceRef), aos ModeDeclarations nos quais ela é válida (TPS_ManifestSpecification p. 679).

O System Template descreve-as de forma concisa como «Firewall rules that are defined in a firewall state» (TPS_SystemTemplate p. 644).

As regras em si são elementos FirewallRule com atributos como bucketSize e refillAmount. Além disso, o metamodelo apresenta NetworkLayerRule e TransportLayerRule, esta última, entre outros, com faixas de portas e checksumVerification. Um CouplingElement também pode agregar regras por meio de firewallRule (TPS_ManifestSpecification p. 679). Para obter detalhes, o System Template remete expressamente à especificação do manifesto (TPS_SystemTemplate p. 644).

A conexão com a aplicação é estabelecida por AdaptiveFirewallToPortPrototypeMapping. Ela mapeia a instância do módulo (referência firewall, 0..1) para o RPortPrototype da aplicação, tipificado pela interface de comutação de estado (TPS_ManifestSpecification p. 677). Aplicam-se duas restrições:

• A nota da classe denomina a interface de FirewallModeSwitchInterface, enquanto o título da figura e a API a denominam de FirewallStateSwitchInterface. Determinante para o código é o nome de [AP_SWS_Fw_82002].
• A classe de mapeamento e sua referência possuem o status candidate (TPS_ManifestSpecification p. 677).

Diagrama de contexto (metamodelo): a instância do módulo agrupa conjuntos de regras dependentes de estado. O mapeamento conecta-os à R-Port da aplicação. Fontes: TPS_ManifestSpecification p. 677, TPS_ManifestSpecification p. 679, TPS_ManifestSpecification p. 677

Fluxo de uma mudança de estado com SwitchFirewallState

No lado do código, a aplicação inclui ara/fw/firewall_state.h. Ela cria ara::fw::FirewallStateSwitchInterface por meio do construtor explícito a partir de um ara::core::InstanceSpecifier. Esse construtor é noexcept e thread-safe [AP_SWS_Fw_82002].

A mudança de estado é solicitada por SwitchFirewallState(EnumT firewallState). O método é noexcept e retorna um ara::core::Future<void>. Os erros FwErrc::kServiceNotAvailable e FwErrc::kInvalidStateDependentFirewall definidos para ele retornam, portanto, via Future e não como exceção [AP_SWS_Fw_82008].

O cenário «Switch Firewall State» mostra o fluxo interno em três etapas (EXP_SWArchitecture p. 232):

1. A aplicação chama SwitchFirewallState() no FC Firewall.
2. O cluster chama, em um loop «foreach FirewallRule», respectivamente applyRule() no sistema operacional.
3. Somente após o loop a resposta retorna à aplicação.

applyRule() está identificado ali como «aapInformative». A forma como as regras são ativadas no sistema operacional não está definida no payload como API da plataforma. A versão de R22-11 mostrava o mesmo fluxo como cenário bem-sucedido (EXP_SWArchitecture p. 158). Após a mudança, apenas as regras do estado ativo verificam e filtram (EXP_PlatformDesign p. 92).

Diagrama de sequência: a mudança de estado é retornada de forma assíncrona por meio de um Future. Internamente, o cluster aplica cada regra individualmente. Fontes: EXP_SWArchitecture p. 232, [AP_SWS_Fw_82002], [AP_SWS_Fw_82008]

Tempo de vida, regras de cópia e de movimentação da classe de interface

As funções especiais de FirewallStateSwitchInterface determinam como as instâncias podem ser repassadas ([AP_SWS_Fw_82003] a [AP_SWS_Fw_82007]):

Elemento	Definição	Segurança entre threads
Construtor de InstanceSpecifier	explicit, noexcept [AP_SWS_Fw_82002]	thread-safe
Construtor de cópia / Atribuição por cópia	=delete [AP_SWS_Fw_82004] [AP_SWS_Fw_82005]	–
Construtor de movimentação / Atribuição por movimentação	noexcept [AP_SWS_Fw_82006] [AP_SWS_Fw_82007]	not thread-safe
Destrutor	noexcept [AP_SWS_Fw_82003]	not thread-safe

Disso resultam três regras de utilização:

• Uma instância não pode ser duplicada, podendo apenas ser repassada via movimentação [AP_SWS_Fw_82004] [AP_SWS_Fw_82006].
• A própria aplicação deve proteger a movimentação e a destruição contra acessos concorrentes [AP_SWS_Fw_82003].
• Interpretação: um objeto de origem após uma movimentação presumivelmente não deve mais ser utilizado para SwitchFirewallState, pois os requirements descrevem apenas a transferência, mas não o estado remanescente [AP_SWS_Fw_82007]. Pergunta Q-ccf0737ee5133103 (aberta)

O texto do requirement não fornece nenhuma indicação sobre a thread-safety do próprio SwitchFirewallState [AP_SWS_Fw_82008].

Diagrama de estados: uma instância é criada a partir de um InstanceSpecifier, é transferida apenas por movimentação e, por fim, destruída. Fontes: [AP_SWS_Fw_82002], [AP_SWS_Fw_82003], [AP_SWS_Fw_82006], [AP_SWS_Fw_82007]

Filtragem de pacotes no estado ativo e notificação de Security Events

As regras de Firewall podem ser associadas a um estado de Firewall. Para a verificação de um pacote, são utilizadas apenas as regras do estado atualmente ativo (EXP_PlatformDesign p. 92). Por estado, a StateDependentFirewall disponibiliza as propriedades de regra ordenadas e a defaultAction opcional (TPS_ManifestSpecification p. 679).

A versão R23-11 da SWS descreve a atribuição de Security Events com mais detalhes (SWS_Firewall p. 31):

• Se um pacote não corresponder a nenhuma regra, a ação padrão (default) é aplicada.
• Se a ação padrão bloquear o pacote, o cluster determina o protocolo divergente. O critério determinante é a regra com o maior número de camadas ISO/OSI correspondentes, contadas a partir da camada mais baixa. A primeira camada acima que não corresponder define o protocolo.
• Para esse protocolo, um SEv é reportado ao IdsM, como SEV_FW_PACKET_BLOCKED_DATALINKLAYER_MISMATCH (Ethernet), SEV_FW_PACKET_BLOCKED_IPV4_MISMATCH, SEV_FW_PACKET_BLOCKED_IPV6_MISMATCH ou SEV_FW_PACKET_BLOCKED_ICMP_MISMATCH.

Estes detalhes são provenientes da R23-11. Os requirements associados não fazem parte do payload da R25-11 e são, portanto, reproduzidos aqui de forma explicativa, e não normativa. O princípio de que mensagens bloqueadas são enviadas como SEvs ao IdsM aplica-se, segundo a descrição da arquitetura, também à R25-11 (EXP_PlatformDesign p. 92).

Diagrama de atividades: um pacote é verificado em relação às regras do estado ativo. Um bloqueio por padrão resulta em um SEv específico do protocolo para o IdsM. Fontes: EXP_PlatformDesign p. 92, SWS_Firewall p. 31 (R23-11)

Comportamento em caso de erro

Os códigos de erro do módulo são definidos por FwErrc no cabeçalho ara/fw/fw_error_domain.h: kServiceNotAvailable=1 e kInvalidStateDependentFirewall=2 [AP_SWS_Fw_83001]. Ambos estão especificados para SwitchFirewallState como possíveis erros [AP_SWS_Fw_82008]. Interpretação dos nomes, uma vez que os requirements não mencionam condições de disparo:

• kServiceNotAvailable provavelmente reporta que o FC Firewall baseado em daemon não consegue prestar o serviço. Pergunta (aberta)
• kInvalidStateDependentFirewall provavelmente reporta que não existe uma StateDependentFirewall válida para o estado solicitado. Pergunta (aberta)

O domínio de erro segue o padrão usual de ara::core:

• GetFwErrorDomain() fornece o domínio de forma thread-safe [AP_SWS_Fw_83002]. O construtor padrão de FwErrorDomain foi excluído [AP_SWS_Fw_83009].
• MakeErrorCode cria um ara::core::ErrorCode [AP_SWS_Fw_83003].
• Name() e Message() fornecem o nome do domínio e o texto de erro [AP_SWS_Fw_83010] [AP_SWS_Fw_83011].
• Os aliases Errc e Exception referenciam FwErrc e FwException [AP_SWS_Fw_83007] [AP_SWS_Fw_83008].

Quem trabalha com exceções pode converter um código de erro em uma FwException por meio de ThrowAsException. Esta função é noexcept(false) e classificada como «not exception safe» [AP_SWS_Fw_83012] [AP_SWS_Fw_83005]. Em contrapartida, pacotes bloqueados não constituem erro de API. Eles aparecem como Security Events no IdsM (EXP_PlatformDesign p. 92).

Diagrama de atividades: o resultado da mudança de estado é avaliado por meio do Future. Os erros passam pela FwErrorDomain e podem ser lançados opcionalmente como FwException. Fontes: [AP_SWS_Fw_82008], [AP_SWS_Fw_83001], [AP_SWS_Fw_83011], [AP_SWS_Fw_83012]

Evidências mais detalhadas

As passagens seguintes sustentam as declarações deste guia; os requirements são normativos para a R25-11 ([AP_SWS_Fw_82008]).

• [AP_SWS_Fw_82008]: única operação técnica com tipo de retorno e lista de erros.
• [AP_SWS_Fw_82002], [AP_SWS_Fw_82003]: construção e destruição da classe de interface, incluindo segurança de threads.
• [AP_SWS_Fw_81001], [AP_SWS_Fw_81002]: tipos de estado gerados.
• [AP_SWS_Fw_83001], [AP_SWS_Fw_83012]: códigos de erro e conversão em exceções.
• EXP_SWArchitecture p. 126, EXP_SWArchitecture p. 197: interface e casos de uso.
• EXP_SWArchitecture p. 232: fluxo da mudança de estado. A versão anterior da R22-11 encontra-se em EXP_SWArchitecture p. 158.
• TPS_ManifestSpecification p. 263, TPS_ManifestSpecification p. 679: máquina de estados e modelo de regras.
• TPS_SystemTemplate p. 644: descrição concisa da StateDependentFirewall. A versão da R23-11 encontra-se em TPS_SystemTemplate p. 583.
• SWS_Firewall p. 31: mapeamento de SEv no bloqueio por padrão, apenas na versão R23-11.