Network Communications

Introduction

GEISA allows applications to make use of 2 types of off-device communications:

Message based via LwM2M

This type of communication is available on every device and is typically, though not exclusivly, transported over the proprietary radio technology between devices and other operator equipment. GEISA uses the administrative LwM2M connection for these messages.

Delivery of messages may be significantly delayed or lost. The operating environment is responsible for queuing these messages and reporting back to the Application if and when they are delivered.

Applications use the message bus to send and receive these messages to/from the operating environment which in turn makes use of LwM2M to transport them. The applications themselves are unaware of any LwM2M details.

Application developers make use of operator run proxies and APIs in the operator's cloud to receive from and send messages to devices. These proxies and APIs should provide statistics regarding the amount of delay and loss to/from any device.

This type of communication is bi-directional and messages can be sent unsolicited by either side.

IP socket based to local devices, private clouds, or public clouds

Applications can also make use of traditional IP socket based real-time communications on devices equipped with cellular, WiFi, or other IP connectivity. Applications must specify the endpoints they need to communicate to (IP/Port) in their Application Manifest so that those policies can be approved by operators and implemented in the operating environment using firewall rules.

Applications must also specify the expected volume of data per day per destination class.

Once a network interface is online, the Application may use outbound-initiated AF_INET/AF_INET6 sockets from within the container environment to reach the specified endpoints.

Inbound connections towards the Application may be defined by policy but are discouraged as inbound port mappings can conflict between applicaions and accepting inbound connections open the Application to additional security concerns.

This form of communication may not be available on all devices or in all deployments. If there is a lack of connectivity, applicaions must either fall back to using message based communications or may refuse to function depending on their use case and design.

Interface Types

The method of connectivity that a device provides can vary from a home WiFi providing Internet connectivity, to private WiFi for partner integrations, or to a variety of operator maintained connectivity options such as shared WiFi hotspots, cellular, mesh, or proprietary interfaces.

Applications need to know which of these (or multiple of these) are available and online at any given time however enumerating both the technology and the allowable use cases that they can transport can become complex quickly.

Example types of network interfaces:

• WiFi - Home (device is client)

• WiFi - Meter (device is AP)

• WiFi - Operator/Partner-Hotspot (device is client)

• Cellular - Internet APN

• Cellular - Private APN

• Ethernet - Home

• Ethernet - Private/Partner Devices

• Field Area Network

Other network interfaces that may be available (but out of scope of “IP socket” based communication in GEISA at this time) are:

• Bluetooth / Bluetooth LE

• 802.15.4 technologies (Zigbee, Thread, etc…)

• Other wired connectivity or peripherals: RS232/485, USB connected devices, etc…

Destination Classes

The device may have zero, one, or multiple interfaces online at any given time. Applications should not be required to know these details but instead only need to know if their desired endpoints are reachable and what volume limits are in place.

Each endpoint an application defines falls into one of these categories:

• Internet Endpoint (ex: Public Cloud)

• Operator Endpoint (ex: Private Cloud)

• Local Endpoint (something off-device, but on-net and private)

• Message based (LwM2M)

For each of these classes, applications have a defined volume limit for when that class is metered.

Network State

For each destination class, applications have a network state that tells the application if and how much communication is available.

The network state includes:

• status: disabled, enabled-down, or enabled-up

• protocol: ipv4, ipv6, or both (N/A to message based class)

• volume: zero, metered, unlimited

• latency: real-time, delayed

An application can request communication with more than one class of endpoint and would need a network status indicator for each class seperately. For example, it may communicate with both Internet Endpoints as well as Local Endpoints.

Applications may report statistics and logs to the operating environment for troubleshooting and logging. For example, if the operating environment has reported that Internet Endpoints should be reachable but the Application cannot reach any, it may report this error.

Volume Limits

Each destination class can be metered depending on which underlying technology transports the data. A Home WiFi would normally be considered unlimited where as a cellular connection would be metered to keep the device under a monthly volume limit.

An application developer must define volume limits per destination class in their Application Manifest. These limits may be overridden by the operator at deployment time when converting the Application Manifest into a Deployment Manifest.

These volume limits are specified as a per day (24 hour period) limit in bytes. Both transmit and receive data counts toward the application's limit. The operator may define a daily rollover mechanism, and a reset period (ex: day of the month). GEISA does not define if or how header and encapsulation bytes count towards volume limits.

The application can query the network manager via the message bus to deterine remaining volume limits and when the next reset occurs.

If an application exhausts its volume quota for one or more destination classes, it will be sent a network state update with the volume field set to ‘zero’ for those classes. When this condition is cleared (on the next day or reset period), the application will be sent another network status update returning the volume field to ‘metered’

Volume limits do not apply to destination classes when the volume field set to ‘unlimited’.

Security considerations

For message based communications, the operating environment will provide encryption and authentication for data passed between the device and head-end via LwM2M, applications may, but are not required to, perform further encryption and/or authentication on top of what the operating environment provides.

For IP socket based communications, the application is responsible for encryption and authentication of data passed between the device and its endpoints where needed.

Connectivity

The operating environment is responsible for providing network connectivity between each Application container environment, the operating environment, and network interfaces.

The operating environemnt and network manager are responsbile for both implementing policy (by firewall and forwarding rules), and providing connectivity between these components.

GEISA does not mandiate a specific technology that the implementer of the operating environment must use to acomplish this, but does recommend the use of Linux network namespaces, veth interfaces, and iptables/nftables for filtering, NAT, and accounting. The implementer may also make use of on-device transparent proxies if desired, however the Application must be able to use AF_INET/AF_INET6 sockets from within the container environment with any encoding and protocol within.

The operating environment must provide a lo interface within the container environment for each application. The lo interface must be up and configured with both 127.0.0.1 and ::1 addresses. An /etc/hosts file containing a localhost entry must also be provided within each container environment. Many libraries make use of localhost connections for inter-process or other local communications.

Policy Rules

The Application and Deployment manifests include a set of Endpoints the Application is expecting to communicate with. An example policy could be:

• Class: Internet Endpoint

  • Outbound, destination 2001:db8:44:12::/64, port: tcp/443

  • Outbound, destination 203.0.113.66/32, port: tcp/999

  • Volume: 30MiB/day

• Class: Operator Endpoint

  • Outbound, destination 3fff:421:32:11::/64, port: tcp/4242

  • Outbound, destination 3fff:421:2:661::/64, port: tcp/443

  • Outbound, destination 198.51.100.0/24, port: tcp/443

  • Volume: 1MiB/day

• Class: Local Endpoint

  • Outbound, destination ipv4-directed-broadcast, port: udp/9999

  • Outbound, destination local-network, port: udp/9999

  • Inbound, source local-network, port: udp/9999

  • Inbound, source local-network, port: udp/20002

  • Outbound, destination local-network, port: tcp/502

  • Volume: 100MiB/day

• Class: Message based

  • Volume: 50KiB/day

DNS

While policy rules are defined using IP addresses, Applications may use DNS queries to avoid hard-coded IP literals within their application source or configuration files.

The Operating Environment and Network manager must provide DNS services for applications to use, however the scope of resolution may be limited perticurarly for devices that are not or are poorly Internet connected.

GEISA highly recommends that the Operating Environment implement a caching local resolver that honors TTL to reduce network traffic off-device due to repeated application lookups for the same name.

The application must be able to reach DNS services from within the container environment by using standard Linux libraries (i.e.: libnss/resolvconf/etc…)

Local Endpoint Considerations

Local Endpoints are defined to allow an Application to access local resources on a connected network. Typically this would be for local device integration such as smart plugs, EVSE, Solar Inverter and battery storage equipment and so on. This type of class is typically only available for devices that are connected to a home WiFi, a Meter hosted WiFi, or wired connection.

As the IP addressing of the connected network are not known and not static between devices, the Application Manifest cannot list destination/source IP addresses for policy rules.