Networking and Security

ZentriOS includes a full IPv4 networking stack that supports a range of popular networking protocols including TCP, UDP, DNS, DHCP. Additional network application libraries are provided for native HTTP and secure cloud access.

Network features include ...

DHCP Client and Server

DHCP Server

The ZentriOS DHCP server supplies IP addresses to clients connecting to the soft AP when the network is brought up with the softap interface.

See command:

DHCP Client

The ZentriOS DHCP client obtains an IP address from the wlan DHCP server when the network is brought up with the wlan interface.

See command:

TCP Client and Server and UDP Client

See also Network Connections and Streams.

See commands:

TCP Client Auto Connect

See variables:

UDP Client Auto Connect

See variables:

HTTP Library

The HTTP Library provides commands for HTTP methods:

HTTP Post Example

The following (fictitious) HTTP post example shows how to post data to an HTTP web server using the ZentriOS HTTP API. The HTTP body data posted in this example is a small piece of JSON (sent using stream_write 0 7). Since the -o option is used with the http_post command, a connection stream to the HTTP server is opened, but the HTTP post is queued locally on the module.

Queuing the HTTP post locally provides the ability to add HTTP headers using the http_add_header command, and to post data in the HTTP body using the stream_write command. Once all headers and body data are queued, the HTTP post is sent to the server and completed using the http_post command.

Any response data received from the server may be read using stream_read.

> http_post -o example.com/hello application/json
[2014-04-23 | 19:40:23: Opening: example.com]
Request POST /hello
Connecting (HTTP): example.com:80
[2014-04-23 | 19:40:23: Opened: 0]
0
> stream_write 0 7
... JSON data goes here ...
Success
> http_read 0
HTTP response: 200
Chunked response
200
> stream_read 0 1000
{
  "response": "howdy!"
}
> stream_close 0
Closing: 0
[2014-04-23 | 19:40:40: Closed: 0]
Success

HTTP Server with RESTful API

The ZentriOS HTTP webserver may be configured to run as a service on either the softAP or wlan interface. The server supports HTTP Basic Authentication with (or without) HTTPS security.

ZentriOS provides a simple RESTful API on top of the HTTP server. The API allows for a remote HTTP(S) client to issue any ZentriOS command. The result of the command is returned in a simple JSON format.

The RESTful API can be used in a number of ways:

The HTTP Server is configured with the following variables:

A client can use the RESTful API to issue ZentriOS commands and receive responses, and also for retrieval of module log messages.

The available requests are as follows:

GET  /command
POST /command
GET  /log
POST /stream

See the HTTP Server RESTful API application note for low-level examples.

The ZentriOS Web App provides a complete demonstration of the HTTP Server RESTful API, and can be customized as required. See Customizing the ZentriOS Web App.

Notes

Command Request/Response

The API supports either a simple GET request or a slightly more complex POST request.

GET Request

GET /command/<ZentriOS command>

POST Request

POST /command
{
   "flags"   : <flags>,
   "command" : "<ZentriOS command>",
   "data"    : "<command data>"
}

where:

HTTP Response Codes

Response body

{
   "id"       : <unique id>,
   "code"     : <response code>,
   "flags"    : <flags>,
   "response" : "<command response>"
}

where:

Log Request/Response

The API also buffers log messages. This is the request to retrieve the log messages.

GET Request

GET /log

HTTP Response Codes

Response

{
  "logs" : [ "<log data>", "<log data>", ....] }
}

Note: the log buffer has limited space. Older logs are replaced by newer ones. This should be called periodically to avoid losing logs.

HTTP Response Codes

HTTP Server Security and Authorization

The HTTP server is secured using HTTP Basic Authentication. This requires that a client supplies a username and password. Note that the username/password are sent in the HTTP request header which is encrypted only if the HTTP request itself is encrypted.

Protecting or Securing a File

When client authorization is enabled, authorization is required to download all files (except unprotected files). To unprotect a file, the -u (unprotected) flag must be explicitly specified when the file is created using the file_create or http_download commands.

When client authorization is disabled, all files may be downloaded from the ZentriOS web server.

Securing the REST API, Whitelisting API Calls

When the authorization feature is enabled all REST API calls require authorization. It is possible to 'whitelist' certain API calls.

This is done by creating the file: http_whitelist.csv which contains a comma separated list of REST API calls that do not require authorization.

This file also supports a trailing wildcard character *. Some examples of this file are as follows:

CORS (Cross Origin Resource Sharing)

The ZentriOS HTTP server supports CORS (Cross-Origin Resource Sharing).

The http.server.cors_origin variable allows you to specify origins for which the same-origin policy is relaxed.

This allows control of the module, via the HTTP server, from a remote site provided the module has originally been set up with a http.server.cors_origin domain that allows access from that site. Via the ZentriOS HTTP server ZentriOS JavaScript API, the remote site can issue all ZentriOS commands, including reboot.

Setting the http.server.cors_origin results in the ZentriOS HTTP server inserting a corresponding CORS Access-Control-Allow-Origin (ACAO) response header into resources it delivers. It also results in the ZentriOS HTTP server responding to an OPTION request with a set of options supporting remote control.

HTTP Server Security Variables

Network Status Indication Using GPIOs

See Peripherals, System Indicator Functions.

See variables system.indicator.gpio and system.indicator.state.

Network Connections and Streams

Streams are associated with:

Stream Limitations

At any moment, ZentriOS-WL supports one TCP client stream, one TCP server stream and one UDP stream. It can support up to 18 simultaneous file streams.

> stream_list
! # Type  Info
# 0 TCPS 10.5.6.146:3000 10.5.6.131:63835
# 1 UDPC  107.170.222.80:50007 (15672)
# 2 TCPC  107.170.222.80:50007 (13171)
# 3 FILE  webapp/unauthorized.html-1.0.1.3  (9530, 0)
# 4 FILE  favicon.ico.gz-1.0.1.3  (733, 0)
# 5 FILE  webapp/zentrios.css.gz-1.0.1.3  (22670, 0)
# 6 FILE  webapp/index.html-1.0.1.3  (1995, 0)
# 7 FILE  .recovery.html-1.0.1.3  (7599, 0)
# 8 FILE  webapp/zentrios.js.gz-1.0.1.3  (71988, 0)
# 9 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 10 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 11 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 12 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 13 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 14 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 15 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 16 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 17 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
# 18 FILE  gpio_config_init.csv-1.0.0.0  (183, 0)
>
Ready
>

Each stream type in the table below uses a single stream, with the following exceptions and qualifications:

Stream Handles

When a stream is open, it is assigned a handle number. This handle is used to read/write/poll/close the stream. ZentriOS supports many types of streams.

Stream Commands

Refer to the following stream commands to use the stream handle:

Serial STREAM Mode

In serial STREAM mode, a single network connection (TCP/UDP client/server) streams to the serial bus. No stream read or write commands are required, as data flows automatically between the serial bus and the open stream. See Serial Interface, Serial Bus Mode.

STREAM mode does not support the following streams:

Note: When in STREAM mode, a TCP server is limited to one client connection.

Stream Types

List the currently open streams with the stream_list command. Streams are listed with stream handle, type, and information about the stream source.

Note that some stream types support a limited set of operations. The following is a list of stream types, and for each type the command to create it, and the operations it supports.

TypeRelated CommandsStream OperationsDescription
UDPCudp_clientread/write/poll/closeUDP client
TCPCtcp_clientread/write/poll/closeTCP client
TCPStcp_serverread/write/poll/closeTCP server client stream. Note that one stream is used per client
FILEfile_open/file_create -oread/poll/closeFile system handle

Remote Terminal Access

See the Wi-Fi Remote Terminal application note and the Remote Terminal variables.

Broadcast Status Announcement

ZentriOS devices broadcast module properties in JSON format. The properties can be sent either as UDP packets to a UDP host or by a post request to an HTTP host. Properties include by default the IP address and the MAC address.

See Broadcast variables:

See also the Broadcast UDP Packet Application Note.

Network Time Management

ZentriOS devices can obtain time data from an NTP (Network Time Protocol) server.

See NTP variables: