Home-Security

CcspHomeSecurity is the RDK-B component responsible for providing Home Network Administration Protocol (HNAP) server functionality for managing home security devices and settings. This component serves as a protocol adapter that bridges HNAP requests from external clients to the CCSP data model infrastructure, enabling remote management and configuration of home security devices through standardized HNAP interfaces. CcspHomeSecurity implements HNAP 1.0 protocol specifications and provides device abstraction layer for accessing various device settings, network configurations, and security parameters through XML-based SOAP messaging.

The component acts as a standalone HTTP server listening for HNAP requests and translating them into CCSP message bus calls to access the underlying data model. It handles authentication, request parsing, method dispatching, and response generation for all supported HNAP operations.

graph LR
    subgraph "External Systems"
        Remote[Remote Management<br/>HNAP Clients]
    end

    subgraph "RDK-B Middleware Layer"
        HomeSecurity[CcspHomeSecurity<br/>HNAP Server]
        CR[Component Registry<br/>CcspCr]
        PandM[CcspPandM<br/>Provisioning & Management]
        WiFi[WiFi Agent<br/>CcspWiFiAgent/OneWifi]
        PSM[PSM<br/>Configuration Storage]
    end

    subgraph "System Layer"
        MBus[CCSP Message Bus]
        Syscfg[Syscfg<br/>Local Storage]
    end

    Remote -->|HTTP POST /HNAP1<br/>SOAP XML| HomeSecurity
    HomeSecurity -->|Component Discovery| CR
    HomeSecurity -->|Message Bus<br/>Parameter Access| MBus
    MBus -->|DeviceInfo, Time, UserInterface<br/>NAT, Users, DHCP, DNS| PandM
    MBus -->|WiFi Radio, AccessPoint| WiFi
    MBus -->|TR-181 Persistence| PSM
    HomeSecurity -->|syscfg_get| Syscfg

    classDef external fill:#f9d5e5,stroke:#c75b7a,stroke-width:2px;
    classDef rdkb fill:#e3f2fd,stroke:#1976d2,stroke-width:2px;
    classDef system fill:#f1f8e9,stroke:#558b2f,stroke-width:2px;

    class Remote external
    class HomeSecurity,CR,PandM,WiFi,PSM rdkb
    class MBus,Syscfg system

Key Features & Responsibilities:

• HNAP Protocol Server: Implements HNAP 1.0 server functionality including HTTP request handling, SOAP/XML parsing, and response generation for home network device management operations
• Device Settings Management: Provides access to device configuration parameters including network settings, wireless configurations, firmware information, and administrative credentials through HNAP interfaces
• Authentication and Security: Implements HTTP Basic Authentication for HNAP requests with hardcoded credential validation to ensure secure access to device management functions
• CCSP Data Model Integration: Translates HNAP method calls into CCSP message bus operations for reading and writing TR-181 data model parameters across multiple RDK-B components
• Network Management APIs: Exposes HNAP methods for network configuration including LAN settings, wireless settings, port mappings, MAC filtering, and connected device enumeration

Design

CcspHomeSecurity follows a request-response architecture designed around the HNAP protocol specification. The design emphasizes protocol compliance, secure authentication, and seamless integration with the CCSP middleware infrastructure. The component operates as a single-threaded HTTP server that processes HNAP requests synchronously, parsing incoming XML payloads, dispatching to appropriate method handlers, and generating XML responses.

The architecture separates HNAP protocol handling from device-specific operations through a well-defined abstraction layer. The core protocol engine manages HTTP communication, XML serialization/deserialization, and SOAP message processing, while the Abstract Device Interface (ADI) layer provides device-agnostic implementations of HNAP methods. The device glue layer connects ADI implementations to the CCSP message bus for accessing the underlying data model.

The northbound interface accepts HTTP POST requests on the /HNAP1 endpoint, with SOAP Action headers identifying the requested method. The southbound interface utilizes CCSP message bus APIs for component discovery, parameter retrieval, and parameter modification across the RDK-B middleware stack. The component registers with the message bus as a client and discovers component destinations through the Component registry. TR-181 parameter persistence is handled by data model components (CcspPandM, CcspWiFiAgent/OneWifi) through PSM integration after HNAP-initiated parameter changes are committed.

graph LR
    subgraph ExternalSystems ["External Systems"]
        CR[Component Registry<br/>CcspCr]
        PandM[CcspPandM]
        WiFi[CcspWiFiAgent/OneWifi]
        PSM[PSM]
        Syscfg[Syscfg]
    end

    subgraph CcspHomeSecurity ["CcspHomeSecurity"]
        subgraph HTTPServer ["HTTP/HNAP Protocol Handler"]
            HNAPServer[HNAP Server<br/>hnapd.c]
            HDKCore[HDK Core<br/>hdk.c]
            HDKContext[Context Manager<br/>hdk_context.c]
        end

        subgraph MethodDispatch ["Method Dispatch Layer"]
            HDKMethods[Method Handlers<br/>hdk_methods.c]
            HDKADI[Abstract Device Interface<br/>hdk_adi.c]
        end

        subgraph DataAccess ["Data Access Layer"]
            HDKDevice[Device Glue<br/>hdk_device.c]
            HDKMBus[Message Bus Client<br/>hdk_ccsp_mbus.c]
        end

        subgraph Utilities ["Utilities"]
            HDKEncode[Encoding Utilities<br/>hdk_encode.c]
            HDKData[Data Structures<br/>hdk_data.c]
        end

        HNAPServer -->|Parse Request| HDKCore
        HDKCore -->|Method Dispatch| HDKMethods
        HDKMethods -->|Call ADI| HDKADI
        HDKADI -->|Device Operations| HDKDevice
        HDKDevice -->|CCSP APIs| HDKMBus
        HDKCore -->|XML Processing| HDKEncode
        HDKCore -->|Data Types| HDKData
        HDKContext -->|Manage State| HNAPServer
    end

    CR -->|Component Discovery| HDKMBus
    PandM -->|TR-181 Parameters| HDKMBus
    WiFi -->|TR-181 Parameters| HDKMBus
    PSM -.->|TR-181 Persistence| PandM
    PSM -.->|TR-181 Persistence| WiFi
    Syscfg -->|Config Flags| HDKDevice

    classDef external fill:#fce4ec,stroke:#c2185b,stroke-width:2px
    classDef server fill:#e1f5fe,stroke:#0277bd,stroke-width:2px
    classDef dispatch fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
    classDef data fill:#fff3e0,stroke:#ef6c00,stroke-width:2px
    classDef util fill:#e8f5e8,stroke:#2e7d32,stroke-width:2px

    class CR,PandM,WiFi,PSM,Syscfg external
    class HNAPServer,HDKCore,HDKContext server
    class HDKMethods,HDKADI dispatch
    class HDKDevice,HDKMBus data
    class HDKEncode,HDKData util

Prerequisites and Dependencies

Build-Time Flags and Configuration:

RDK-B Platform and Integration Requirements:

• Build Dependencies: libxml2, ccsp-common-library, utopia, curl, mountutils (from ccsp-home-security.bb)
• Note: utopia integration is handled through CcspPandM component
• RDK-B Components:
• CcspCr (Component Registry) – required for dynamic component discovery
• CcspPandM (Provisioning and Management) – provides TR-181 data model namespaces required for HNAP device management operations:
  • Device.DeviceInfo.* – Model name, manufacturer, description, firmware version for HNAP GetDeviceSettings/GetDeviceSettings2 responses
  • Device.UserInterface.* – Remote access settings (HTTP/HTTPS enable, ports), language/locale for HNAP ManageRemote and GetRouterSettings operations
  • Device.Time.* – Timezone and daylight saving configuration for HNAP SetRouterSettings/GetRouterSettings time management
  • Device.NAT.PortMapping.* – Port forwarding rules management for home security VLAN (filter by 192.168.106.* prefix) in HNAP GetPortMappings/SetPortMappings methods
  • Device.Users.User.* – Admin username and password retrieval for HNAP authentication and device settings operations
  • Device.DHCPv4.Server.Pool.* (via X_CISCO_COM_MultiLAN paths) – DHCP server configuration including IP range, lease time, static reservations for HNAP LAN and DHCP management
  • Device.DNS.* – DNS server settings for WAN configuration in HNAP SetWanSettings/GetWanSettings operations
  • Device.X_CISCO_COM_MultiLAN.* – Home security VLAN-specific paths for DHCP pool, WiFi AP, and radio mappings enabling isolation of home security network
• CcspWiFiAgent/OneWifi – provides Device.WiFi data model namespace for wireless configuration
• PSM (Persistent Storage Manager) – optional for TR-181 parameter persistence
• HAL Dependencies: HAL interaction through CcspPandM and CcspWiFiAgent/OneWifi components
• Systemd Services:
• Component Registry service must be active before CcspHomeSecurity starts
• CcspPandM must be running to provide Device.DeviceInfo, Device.Time, Device.UserInterface, Device.NAT, Device.Users, Device.DHCPv4, Device.DNS parameters
• CcspWiFiAgent/OneWifi must be running to provide Device.WiFi parameters
• Message Bus: CCSP message bus client registration using CCSP_Message_Bus_Init() from hdk_ccsp_mbus.c
• Configuration Files: Syscfg configuration database for HomeSecurityEthernet4Flag flag (read-only access)
• Startup Order: Initialize after message bus, Component Registry, CcspPandM, and CcspWiFiAgent/OneWifi are operational

Threading Model:

CcspHomeSecurity implements a single-threaded architecture centered around a synchronous HTTP request processing loop.

• Threading Architecture: Single-threaded with blocking I/O
• Main Thread: Handles all HTTP server operations including socket accept, request parsing, HNAP method execution, and response generation in a sequential manner
• Synchronization: Single-threaded design eliminates need for explicit synchronization mechanisms

Component State Flow

Initialization to Active State

CcspHomeSecurity follows a straightforward initialization sequence focused on establishing message bus connectivity and starting the HTTP server.

sequenceDiagram
    autonumber
    participant System as System Startup
    participant Component as CcspHomeSecurity
    participant MBus as Message Bus
    participant Syscfg as Syscfg
    participant Socket as Network Socket

    System->>Component: Start Process
    Note over Component: State: Initializing

    Component->>MBus: Initialize Message Bus Client
    MBus-->>Component: Bus Handle
    Note over Component: State: Message Bus Connected

    Component->>MBus: Register Component
    MBus-->>Component: Registration Success

    Component->>Syscfg: Load Configuration
    Syscfg-->>Component: Configuration Data

    Component->>Socket: Create Listen Socket
    Note over Socket: Port specified via<br/>command-line argument
    Socket-->>Component: Socket Descriptor

    Component->>Socket: Bind and Listen
    Socket-->>Component: Ready
    Note over Component: State: Active - Accepting Connections

    loop HTTP Request Processing
        Socket->>Component: Accept Connection
        Component->>Component: Process HNAP Request
        Component->>Socket: Send Response
        Component->>Socket: Close Connection
    end

    System->>Component: Shutdown Signal
    Component->>Socket: Close Listen Socket
    Component->>MBus: Disconnect
    Note over Component: State: Terminated

Runtime State Changes and Context Switching

During normal operation, CcspHomeSecurity maintains a steady state while processing HNAP requests sequentially.

State Change Triggers:

• Message bus disconnection events requiring reconnection attempts to restore data model access
• Configuration parameter changes through TR-181 data model affecting device settings
• Network socket errors causing server restart or connection handling failures

Context Switching Scenarios:

• Switching between authenticated and unauthenticated request handling based on HNAP method requirements
• Transitioning between read-only operations (GetDeviceSettings) and write operations (SetDeviceSettings) requiring different data model access patterns

Call Flow

Initialization Call Flow:

sequenceDiagram
    participant Init as Main Function
    participant MBus as Message Bus Module
    participant Server as HTTP Server
    participant Syscfg as Syscfg

    Init->>MBus: MBus_Create()
    MBus-->>Init: MBus Object

    Init->>Syscfg: syscfg_init()
    Syscfg-->>Init: Success

    Init->>Server: HTTP_ServerInit()
    Server->>Server: socket(), bind(), listen()
    Server-->>Init: Ready

    Init->>Server: HTTP_ServerRun()
    Note over Server: Enter main accept() loop
    Server-->>Init: Initialization Complete (Active State)

Request Processing Call Flow:

The most critical flow is processing an HNAP GetDeviceSettings request, which demonstrates the complete request-response cycle.

sequenceDiagram
    participant Client as HNAP Client
    participant Server as HTTP Server<br/>(hnapd.c)
    participant Core as HNAP Core<br/>(hdk.c)
    participant Method as Method Handler<br/>(hdk_methods.c)
    participant ADI as Abstract Device<br/>(hdk_adi.c)
    participant Device as Device Glue<br/>(hdk_device.c)
    participant MBus as Message Bus<br/>(hdk_ccsp_mbus.c)
    participant CR as Component Registry<br/>CcspCr
    participant PandM as CcspPandM
    participant WiFi as CcspWiFiAgent/OneWifi

    Client->>Server: HTTP POST /HNAP1<br/>SOAPAction: GetDeviceSettings
    Server->>Server: HTTP_ParseHeaders()
    Server->>Server: HTTP_AuthDecode()
    Note over Server: Validate credentials via syscfg

    Server->>Core: HDK_HandleRequest()
    Core->>Core: HDK_Request_Init()
    Note over Core: Parse SOAP XML request

    Core->>Method: HDK_Method_PN_GetDeviceSettings()
    Method->>ADI: HDK_ADI_PN_GetDeviceSettings()

    ADI->>Device: HDK_Device_GetValue(DeviceInfo.ModelName)
    Device->>MBus: MBus_GetParamVal("Device.DeviceInfo.ModelName")
    MBus->>CR: CcspBaseIf_discComponentSupportingNamespace()
    CR-->>MBus: Component: com.cisco.spvtg.ccsp.pam
    MBus->>PandM: CcspBaseIf_getParameterValues()
    PandM-->>MBus: Value: "XB6"
    MBus-->>Device: Value
    Device-->>ADI: Value

    ADI->>Device: HDK_Device_GetValue(UserInterface.RemoteAccess)
    Device->>MBus: MBus_GetParamVal("Device.UserInterface...")
    MBus->>CR: CcspBaseIf_discComponentSupportingNamespace()
    CR-->>MBus: Component: com.cisco.spvtg.ccsp.pam
    MBus->>PandM: CcspBaseIf_getParameterValues()
    PandM-->>MBus: Value
    MBus-->>Device: Value
    Device-->>ADI: Value

    ADI->>Device: HDK_Device_GetValue(WiFi Settings)
    Device->>MBus: MBus_GetParamVal("Device.WiFi.Radio...")
    MBus->>CR: CcspBaseIf_discComponentSupportingNamespace()
    CR-->>MBus: Component: com.cisco.spvtg.ccsp.wifi
    MBus->>WiFi: CcspBaseIf_getParameterValues()
    WiFi-->>MBus: Value
    MBus-->>Device: Value
    Device-->>ADI: Value

    ADI->>ADI: Build response struct
    ADI-->>Method: Response struct
    Method-->>Core: Response struct

    Core->>Core: HDK_EncodeResponse()
    Note over Core: Generate SOAP XML response
    Core-->>Server: XML response

    Server->>Client: HTTP 200 OK<br/>SOAP XML Response

Internal Modules

CcspHomeSecurity is organized into specialized modules handling protocol processing, method dispatch, and data access layers.

Component Interactions

CcspHomeSecurity maintains interactions with CCSP middleware components and system services for data model access and configuration management.

Interaction Matrix

Events Published by CcspHomeSecurity:

CcspHomeSecurity operates as a request-response service processing HNAP requests synchronously. Event notifications to other components are handled by the data model components (CcspPandM, CcspWiFiAgent/OneWifi) after parameter commits.

IPC Flow Patterns

Primary IPC Flow – HNAP Parameter Get with Dynamic Component Discovery:

sequenceDiagram
    participant Client as HNAP Client
    participant Server as CcspHomeSecurity
    participant MBus as Message Bus<br/>(hdk_ccsp_mbus.c)
    participant CR as Component Registry<br/>CcspCr
    participant PandM as CcspPandM

    Client->>Server: HNAP Request (GetDeviceSettings)
    Note over Server: Parse SOAP XML request

    Server->>MBus: MBus_GetParamVal("Device.DeviceInfo.ModelName")
    MBus->>MBus: MBus_Process(MBUS_GETPARAM)
    MBus->>CR: CcspBaseIf_discComponentSupportingNamespace<br/>("Device.DeviceInfo.", subsystem)
    Note over CR: Query component registry<br/>for namespace owner
    CR-->>MBus: componentStruct: com.cisco.spvtg.ccsp.pam<br/>dbusPath: /com/cisco/spvtg/ccsp/pam

    MBus->>PandM: CcspBaseIf_getParameterValues<br/>(["Device.DeviceInfo.ModelName"])
    Note over PandM: Retrieve parameter from<br/>internal data model
    PandM-->>MBus: parameterValStruct: "XB6"
    MBus-->>Server: Value: "XB6"

    Note over Server: Build HNAP response struct
    Server->>Server: HDK_EncodeResponse()
    Server-->>Client: HTTP 200 OK (SOAP XML Response)

Configuration Update Flow with Multi-Component Interaction:

sequenceDiagram
    participant Client as HNAP Client
    participant Server as CcspHomeSecurity
    participant Syscfg as Syscfg Storage
    participant MBus as Message Bus
    participant CR as Component Registry
    participant PandM as CcspPandM
    participant WiFi as CcspWiFiAgent/OneWifi

    Client->>Server: HNAP Request (SetWiFiRadioSettings)
    Note over Server: Parse and validate request

    alt Authentication Update (Local)
        Server->>Syscfg: syscfg_set("admin_password", value)
        Syscfg-->>Server: Success
        Server->>Syscfg: syscfg_commit()
        Syscfg-->>Server: Persisted to flash
    end

    alt Remote Access Port (PandM)
        Server->>MBus: MBus_SetParamVal<br/>("Device.UserInterface...HttpPort", 8080)
        MBus->>CR: CcspBaseIf_discComponentSupportingNamespace<br/>("Device.UserInterface.")
        CR-->>MBus: Component: CcspPandM
        MBus->>PandM: CcspBaseIf_setParameterValues<br/>(commit=true)
        PandM->>PandM: Update parameter & commit
        PandM-->>MBus: Success
        MBus-->>Server: Success
    end

    alt WiFi Radio Enable (WiFi)
        Server->>MBus: MBus_GetParamVal<br/>("Device.X_CISCO_COM_MultiLAN.HomeSecurityWiFiRadio")
        Note over MBus: Get WiFi radio instance path
        MBus->>CR: Discover component
        CR-->>MBus: Component: CcspPandM
        MBus->>PandM: Get parameter
        PandM-->>MBus: Path: "Device.WiFi.Radio.2."
        MBus-->>Server: Radio path

        Server->>MBus: MBus_SetParamVal<br/>("Device.WiFi.Radio.2.Enable", true)
        MBus->>CR: CcspBaseIf_discComponentSupportingNamespace<br/>("Device.WiFi.Radio.2.Enable")
        CR-->>MBus: Component: CcspWiFiAgent/OneWifi
        MBus->>WiFi: CcspBaseIf_setParameterValues
        WiFi->>WiFi: Configure radio hardware
        WiFi-->>MBus: Success
        MBus-->>Server: Success
    end

    Server->>Server: Build success response
    Server-->>Client: HTTP 200 OK (SetWiFiRadioSettingsResponse)

Implementation Details

HAL Integration

HAL Integration Through Data Model:

CcspHomeSecurity accesses hardware functionality through data model components that provide HAL abstraction:

• WiFi Hardware Operations: Delegated to CcspWiFiAgent/OneWifi component via Device.WiFi.* TR-181 parameters
• Network Hardware Operations: Managed by CcspPandM component via Device.NAT., Device.DHCP., Device.DNS.* parameters
• Device Hardware Information: Retrieved from CcspPandM via Device.DeviceInfo.* parameters

CcspHomeSecurity operates as a protocol adapter layer, translating HNAP protocol requests into TR-181 data model operations through CCSP message bus. This design allows the component to access hardware functionality indirectly through data model components (CcspPandM, CcspWiFiAgent/OneWifi), which handle the actual HAL API interactions.

Message Bus APIs Integration

CcspHomeSecurity utilizes CCSP message bus APIs for accessing the TR-181 data model across RDK-B components.

Core Message Bus Wrapper APIs:

Key Implementation Logic

• HTTP Server Engine: Single-threaded HTTP server implementation in hnapd.c using standard POSIX socket APIs with blocking accept/read/write operations for processing HNAP requests with configurable port specified as command line argument
• HNAP Protocol Processing: XML-based SOAP message parsing and generation implemented in hdk.c using custom XML parser, with method dispatch based on SOAPAction header matching to registered HNAP method handlers
• Authentication Mechanism: HTTP Basic Authentication validation implemented in hnapd.c with Base64-decoding of Authorization header and hardcoded credential verification in hdk_context.c using username “hnapadmin”
• Device Abstraction Layer: Abstract Device Interface in hdk_adi.c provides device-agnostic implementations of HNAP methods, delegating device-specific operations to hdk_device.c glue layer for CCSP data model mapping
• Error Handling Strategy: HNAP error codes mapped to HDK_Enum_Result enumeration with HTTP 200 responses containing SOAP fault details for protocol-level errors, and component-level error propagation through message bus return codes
• Logging & Debugging: Syslog-based logging using chs_log.h macros with severity levels (LOG_ERR, LOG_WARNING, LOG_INFO) for request processing, message bus operations, and error conditions

Key Configuration Files