Networking and Security

WiConnect includes a full IPv4 networking stack and SSL/TLS security suite that supports a range of popular networking protocols including TCP, UDP, DNS, DHCP. Additional network application libraries are provided for native HTTP/S and secure cloud access using goHACK.me & the Sensors.com API.

Network features include ...

Security features include ...

DHCP Client and Server

DHCP Server

The WiConnect 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 WiConnect DHCP client obtains an IP address from the wlan DHCP server when the network is brought up with the wlan interface.

See command:

TCP, UDP and TLS Client and Server

See commands:

and:

TCP Client Auto Connect

See variables:

UDP Client Auto Connect

See variables:

UDP Server Auto Connect

See variables:

HTTP Library

HTTP Post Example

The following (fictitious) HTTP post example shows how to post data to an HTTP web server using the WiConnect 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 WiConnect 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.

WiConnect provides a simple RESTful API on top of the HTTP server. The API allows for a remote HTTP(S) client to issue any WiConnect 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 WiConnect 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

The WiConnect Web App provides a complete demonstration of the HTTP Server RESTful API, and can be customized as required. See Customizing the WiConnect 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/<wiconnect command>

POST Request

POST /command
{
   "flags"   : <flags>,
   "command" : "<wiconnect 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.

Web Socket Stream

Issuing the API call POST /stream opens a websocket and a 'stream' is created by WiConnect. An MCU can read/write data using the WiConnect stream_read and stream_write commands.

POST /stream
<raw data .... >

See HTTP Server Simple WebSocket Demonstration.

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.

Client Authorization

When the http server username/password settings are set, authorization is required to access certain files/api commands. Client authorization uses 'HTTP Basic Authentication'.

Client authorization requires a username and password that matches the http.server.username and http.server.password variables. If authorization fails, the server returns a 401 error code and the following response header: WWW-Authenticate: Basic realm=WiConnect

The authorization feature is enabled when both the http.server.username and http.server.password variables are set.

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 WiConnect 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:

Whitelist ALL REST API calls * Whitelist the log and stream API calls: /log,/stream Whitelist all get wlan calls: get wl* Whitelist the help variables and help commands commands: help variables,help commands Whitelist /stream, help, and all getters: /stream,help *,get *

CORS (Cross Origin Resource Sharing)

The WiConnect 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 WiConnect HTTP server WiConnect JavaScript API, the remote site can issue all WiConnect commands, including reboot.

Setting the http.server.cors_origin results in the WiConnect HTTP server inserting a corresponding CORS Access-Control-Allow-Origin (ACAO) response header into resources it delivers. It also results in the WiConnect 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

A maximum of 8 network connections is allowed.

All stream types in the table below use one stream, with the following exceptions and qualifications:

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

The currently opened streams may be listed with the stream_list command. Streams are listed with stream number, type, and information about the stream source.

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

TypeCommandOperationsDescription
UDPCudp_clientread/write/poll/closeUDP client
UDPSudp_serverread/write/poll/closeUDP server. Note that one stream is used for all server clients
TCPCtcp_clientread/write/poll/closeTCP client
TCPStcp_serverread/write/poll/closeTCP server client stream. Note that one stream is used per client
TLSCtls_clientread/write/poll/closeTLS client
TLSStls_serverread/write/poll/closeTLS server client stream. Note that one stream is used per client
HTTPhttp_get/http_post/http_headread/write/poll/closeHTTP client
HTTPShttp_get/http_post/http_headread/write/poll/closeSecure HTTP client
WEBS-read/write/poll/closeWebsocket opened by a network client
FILEfile_openread/poll/closeFile system handle
GHMghm_message get /ghm_message postread/write/poll/closegoHACK.me message
CMDbuffered commandsread/poll/closeBuffered command data. Select commands that are buffered when the variable system.cmd.buffered = '1'

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

Remote Terminal Access

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

Network Discovery

Overview

In simple terms, network discovery is used to give the module a name on the local network. So, for instance, if the module has a domain name mymodule.local, a remote client on the same network can connect to the module using the domain mymodule.local even though the domain mymodule.local is not registered with a DNS server. This is useful because the remote client doesn't need to know the IP address of the module.

WiConnect supports three network discovery protocols: mDNS (multicast Domain Name System), LLMNR (Link-Local Multicast Name Resolution) and NetBIOS. The latter two protocols are used by Windows systems only.

OS Support

The remote client must support one or more network discovery protocols for device discovery to work.

Apple

Mac OS X & iOS support mDNS by default, with Bonjour.

Windows

Windows has support for mDNS, but by default it uses the LLMNR and NetBIOS protocols. These protocols are very similar to mDNS so their basic domain resolution features are supported by the module as well. When a domain is entered into the web browser, Windows follows this sequence to resolve the domain: - Check local cache - Issue LLMNR query - Issue NetBIOS query - Issue DNS query

The LLMNR and NetBIOS queries are broadcast to the local network only. The DNS query is typically sent to the internet.

If network discovery is enabled on the module, the module will receive the LLMNR and NetBIOS queries, compare the query domain to its mdns.name, and if they match respond with the module's IP address. In this way the module can easily be found on the local network from a Windows machine.

A NetBIOS domain can have up to 15 characters (including the '.local'). If mdns.name is longer than 15 characters then the NetBIOS protocol is not used.

Finally, some ISPs hijack the .local domain for their own purposes, including advertising. This may cause a Windows PC to fail to resolve the domain. The solution (for Windows only) is to drop .local from the URL and simply use http://mymodule/ directly.

Linux

Linux needs an additional package installed for mDNS support. The most common package is Avahi.

Android

Unfortunately, Android does not support these (or apparently any ZeroConf protocol) by default. It recently added a mDNS SDK but most apps don't appear to use it. Consequently third party apps like Chrome on Android do not support mDNS but adding support to a custom app should be straight-forward.

In a Nutshell

Network discovery provides a way for remote clients to resolve the IP address of the module on a local network using a standard protocol. mDNS has other features which allow the module to advertise various services including HTTP, TCP & UDP servers. WiConnect supports configuration of these additional features with the mdns.service variable.

Commands

Variables

Broadcast Status Announcement

ACKme WiConnect modules 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

ACKme WiConnect modules can obtain time data from an NTP (Network Time Protocol) server.

See NTP variables:

Sending Email using SMTP

ACKme WiConnect modules can send email messages via an external SMTP server.

See email SMTP variables:

Sensors.com API

The goHACK.me web service provides a free introduction to the Sensors.com services.

See goHACK.me API.

See the goHACKme commands and goHACKme variables.