Networking and Security
Gecko OS 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.
For each networking client and server there are configuration variables, and commands and procedures to start and stop the client or server.
- DHCP client
- DHCP server
- DNS client
- DNS server
- HTTP client
- HTTP server with RESTful API
- HTTPS client
- NTP client
- TCP client
- TCP server
- TLS 1.0 - 1.2
- SSL/TLS client
- UDP client
- UDP server
When a network connection is established, Gecko OS opens a network stream to write and read data. See Network Connections and Streams .
Other network features include ...
- Network status indication using GPIOs
- Remote Terminal Access
- Broadcast status announcement
- Captive Portal
Security features include ...
- SSL/TLS client
- HTTPS webserver
- HTTPS file upload and download
- CA certificate store
DHCP Client
The Gecko OS DHCP client obtains an IP address from the WLAN DHCP server when the network is brought up with the
wlan
interface.
Configure the DHCP client with the variables:
Bring the network up by issuing any command that requires the network, or use the command:
DHCP Server
The Gecko OS DHCP server supplies IP addresses to clients connecting to the soft AP when the network is brought up with the
softap
interface.
Configure the DHCP server with the variables:
The soft AP starts on reboot when configured to auto-start with the softap.auto_start variable.
You can bring up the soft AP with the
network_up
command. Either specify the
softap
interface, or set the
network.default_interface
variable to
softap
.
The soft AP starts automatically when you use Web Setup .
DNS Client
The DNS Client works with all the network protocols, including HTTP, TCP and UDP.
There are no configuration variables for the DNS Client.
The wlan.network.dns variable returns a list of addresses currently in use by the WLAN interface.
DNS Server
DNS Server features are available for the Soft AP interface.
Configuration options for the soft AP DNS server are:
The setup.web.url variable defines a list of URLs that clients can use to connect to the Web App.
HTTP Client
The HTTP Client consists of a group of commands for HTTP methods:
For a secure TLS transaction, the url scheme specified with the command must be
https
. See
HTTPS Client
.
The
http_get
,
http_post
and
http_head
commands have an option to queue the request, prior to sending. While the request is queued, use the
http_add_header
to add custom headers as required, as shown in the example below. Use the
stream_write
command to add data to the body of a POST request.
Use the
http_read_status
command to read the HTTP response after a request is completed.
Connection timeout for the HTTP client commands is controlled by the tcp.client.connect_timeout variable.
Stream Type
:
HTTP
. See
Network Connections and Streams, Stream Types
.
HTTP POST Example
The following (fictitious) HTTP POST example shows how to post data to an HTTP web server using the Gecko OS 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 Client File Upload and Download
The HTTP Client feature includes commands to handle file upload and download, between the Gecko OS device file system and an HTTP/S host:
The
http_upload
and
http_download
commands use HTTP POST requests in the background.
For a secure TLS transaction, the url scheme specified with the command must be
https
.
See:
HTTP Server with RESTful API
The Gecko OS HTTP webserver may be configured to run as a service on either the softAP or WLAN interface.
There is no network stream associated with the HTTP server. An HTTP client issues a request and the HTTP server sends a response. The client and server do not read or write data outside the request.
Gecko OS provides a simple RESTful API on top of the HTTP server. The API allows for a remote HTTP(S) client to issue any Gecko OS command. The result of the command is returned in a simple JSON format.
The RESTful API can be used in a number of ways:
- GET and POST requests - see the HTTP Server RESTful API app note
- The Web App provides complete control of a module via the RESTful API
The HTTP Server is configured with the following variables:
- http.server.api_enabled
- http.server.cors_origin
- http.server.enabled
- http.server.interface
- http.server.max_clients
- http.server.notfound_filename
- http.server.port
- http.server.root_filename
A client can use the RESTful API to issue Gecko OS 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 Web App provides a complete demonstration of the HTTP Server RESTful API, and can be customized as required. See Customizing the Web App .
Notes
- Request size is limited to 4 KBytes, not including headers.
- The HTTP server does not check headers.
Command Request/Response
The API supports either a simple GET request or a slightly more complex POST request.
GET Request
GET /command/<Gecko OS command>
POST Request
POST /command
{
"flags" : <flags>,
"command" : "<Gecko OS command>",
"data" : "<command data>"
}
where:
-
<flags>
-
0x01
- "command" field is base64 encoded -
0x02
- base64 encode response data -
0x04
- "data" field is base64 encoded
-
-
<Gecko OS command>
- any Gecko OS serial command -
<command data>
- optional, specific to certain Gecko OS commands that require additional data (write, file_create, etc)
With the REST API, the procedure for issuing commands is:
- Open HTTP socket to server
- POST JSON formatted command to device
- Device processes request
- Device returns a JSON formatted response
- HTTP connection closed
To issue another command, repeat steps 1-5.
HTTP Response Codes
-
200
- the command transaction executed successfully -
400
- malformed request -
500
- server error
Response body
{
"id" : <unique id>,
"code" : <response code>,
"flags" : <flags>,
"response" : "<command response>"
}
where:
-
<unique id>
- unique id given to each command. -
<response code>
- the Gecko OS command response code. -
<flags>
-
0x01
- the command response is base64 encoded
-
-
<command response>
- the command response data
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
-
200
- the command transaction executed successfully -
400
- malformed request
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
-
200
- the command transaction executed successfully -
400
- malformed request -
404
- no available stream handles
CORS (Cross Origin Resource Sharing)
The Gecko OS 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.
Setting the
http.server.cors_origin
results in the Gecko OS HTTP server inserting a corresponding CORS Access-Control-Allow-Origin (ACAO) response header into resources it delivers. It also results in the Gecko OS HTTP server responding to an
OPTION
request with a set of options supporting remote control.
HTTPS Client
HTTPS client commands include:
The HTTP client commands use TLS when the URL supplied has the scheme
https
.
The TLS CA certificate is supplied as a command argument or by default configured with the variables:
- network.tls.ca_cert
- network.tls.client_cert
- network.tls.client_key
- network.tls.handshake_timeout
- network.tls.version
NTP Client
Network Time Management
Gecko OS devices can obtain time data from an NTP (Network Time Protocol) server.
Configure NTP with the variables:
Time related variables are:
If NTP is enabled, time.last_set returns the seconds since the time was last set by NTP.
To read the time, get time.rtc and to determine the time zone, get time.zone .
TCP Client
Configure the TCP client with the variables:
- tcp.client.auto_interface
- tcp.client.auto_retries
- tcp.client.auto_start
- tcp.client.connect_timeout
- tcp.client.connected_str
- tcp.client.disconnected_str
- tcp.client.local_port
- tcp.client.remote_host
- tcp.client.remote_port
- tcp.client.retries
- tcp.client.retry_period
- tcp.client.tls_enabled
Start the TCP client with the command:
Stream Type
:
TCPC
. See
Network Connections and Streams, Stream Types
.
TCP Client Auto Connect
To connect automatically to a remote host when the network is brought up, configure TCP client auto-connect with the variables:
- tcp.client.auto_interface
- tcp.client.auto_retries
- tcp.client.auto_start
- tcp.client.remote_host
- tcp.client.remote_port
To auto start with a TLS connection, set tcp.client.tls_enabled = TRUE. See TLS Client .
TCP Client Connection Retry Sequence
The TCP client connection retry sequence is shown in the following diagram. Click to enlarge:
TCP Server
Configure the TCP server with the variables:
- tcp.server.auto_interface
- tcp.server.auto_start
- tcp.server.connected_gpio
- tcp.server.data_gpio
- tcp.server.idle_timeout
- tcp.server.port
Start and stop the TCP server with the TCP server command:
Stream Type
:
TCPS
. See
Network Connections and Streams, Stream Types
.
TLS 1.0-1.2 Support
Gecko OS supports TLS 1.0 to TLS 1.2.
Supported TLS Cipher Suites
Gecko OS supports the following Cipher Suites for TLS 1.0 - 1.2:
OpenSSL Name | Key Exchange | Encryption | Hashing Algorithm |
---|---|---|---|
TLS-ECDHE-RSA-WITH-AES-128-CBC-SHA | ECDHE RSA | AES-128 | SHA-1 |
TLS-ECDHE-RSA-WITH-AES-256-CBC-SHA | ECDHE RSA | AES-256 | SHA-1 |
TLS-ECDHE-RSA-WITH-AES-128-CBC-SHA256 | ECDHE RSA | AES-128 | SHA-256 |
TLS-ECDHE-RSA-WITH-AES-128-GCM-SHA256 | ECDHE RSA | AES-256 | SHA-256 |
TLS-RSA-WITH-AES-128-GCM-SHA256 | RSA | AES-128 | SHA-256 |
TLS-RSA-WITH-AES-128-CBC-SHA256 | RSA | AES-256 | SHA-256 |
TLS-RSA-WITH-AES-256-CBC-SHA256 | RSA | AES-256 | SHA-256 |
TLS-RSA-WITH-AES-128-CBC-SHA | RSA | AES-128 | SHA-1 |
TLS-RSA-WITH-AES-256-CBC-SHA | RSA | AES-256 | SHA-1 |
TLS-RSA-WITH-AES-256-CCM | RSA | AES-256 | SHA-256 |
TLS-RSA-WITH-AES-256-CCM-8 | RSA | AES-256 | SHA-256 |
TLS-RSA-WITH-AES-128-CCM | RSA | AES-128 | SHA-256 |
TLS-RSA-WITH-AES-128-CCM-8 | RSA | AES-128 | SHA-256 |
TLS-ECDH-RSA-WITH-AES-128-CBC-SHA | ECDH RSA | AES-128 | SHA-1 |
TLS-ECDH-RSA-WITH-AES-256-CBC-SHA | ECDH RSA | AES-256 | SHA-1 |
TLS-ECDH-RSA-WITH-AES-128-CBC-SHA256 | ECDH RSA | AES-128 | SHA-256 |
TLS-ECDH-RSA-WITH-AES-128-GCM-SHA256 | ECDH RSA | AES-128 | SHA-256 |
Acronyms Used in Above Table
- AES - Advanced Encryption Standard
- CBC - Cipher Block Chaining
- CCM - Cipher Block Chaining - Message Authentication Code
- DH - Diffie-Hellman
- DHE - Diffie-Hellman Ephemeral
- EC - Elliptic Curve
- GCM - Galois/Counter Mode
- RSA - Rivest, Shamir, Adleman
- SHA - Secure Hash Algorithm
TLS Memory Requirements
Increasing Available Memory for TLS
TLS connections require a considerable amount of RAM. Low memory may result in TLS errors.
To establish a TLS connection, other memory intensive features may need to be disabled. You can return the device to the default state with a factory reset .
TLS client handshake may require up to 85% of the available dynamic memory to complete. This memory requirement dictates the ability to run TLS client and other network streams simultaneously.
Auto-start
If TLS client auto-start is enabled, other streams with auto-start variable enabled will not start.
Run-time via command API
The TLS client will not start if other streams are opened. Other streams may be started after TLS client is opened (has completed its handshake).
TLS Client
TLS client commands include:
See also HTTPS Client .
TLS details must be supplied as a command argument or configured with the variables:
- network.tls.ca_cert
- network.tls.client_cert
- network.tls.client_key
- network.tls.handshake_timeout
- network.tls.version
To manually initiate a TLS connection with the TCP client, use the tls_client command.
To auto-start the TCP client with TLS, set:
- tcp.client.auto_start = TRUE
- tcp.client.tls_enabled = TRUE
See TCP Client Auto Connect .
The TCP client, with TLS enabled, has the features described in the TCP Client documentation.
Stream Type
:
TLSC
. See
Network Connections and Streams, Stream Types
.
OTA always uses TLS.
Connect timeout for the TLS client command is controlled by the tcp.client.connect_timeout variable.
UDP Client
Configure the UDP client with the variables:
Start the UDP client with the command:
Stream Type
:
UDPC
. See
Network Connections and Streams, Stream Types
.
UDP Client Auto Connect
Configure the UDP client auto-connect with the variables:
UDP Server
Configure the UDP server with the variables:
- udp.server.auto_interface
- udp.server.auto_start
- udp.server.data_gpio
- udp.server.lock_client
- udp.server.port
- udp.server.remote_host
- udp.server.remote_port
Start and stop the UDP server with the command:
The
udp_server
has subcommands to
read
and
write
. These are equivalent to the stream
read
and
write
commands, with the added option of determining the client address and port.
The UDP server uses a single stream for multiple clients. Using the stream read and write commands applies to all clients. Using the UDP server subcommands allows writing to and reading from a specific client.
Stream Type
:
UDPS
. See
Network Connections and Streams, Stream Types
.
UDP Server Auto Connect
Configure the UDP server auto-connect with the variables:
Network Connections and Streams
Streams are associated with:
- network connections, including HTTP, HTTPS, TCP, TLS, WebSocket and UDP client and server connections
- open files
When Gecko OS opens a network connection, file, or serial connection, it returns a stream handle. The stream commands act on a stream handle to perform actions such as read, write, poll and close. You can list open streams. Each stream has a specific type. See Stream Types .
Stream Handles
When a stream is open, it is assigned a handle number. This handle is used to read/write/poll/close the stream.
Stream Commands
Refer to the following stream commands to use the stream handle:
- stream_list - list open streams by stream handle, with stream type and related information
- stream_read - read stream specified by stream handle
- stream_write - write to stream specified by stream handle
- stream_close - close stream specified by stream handle
- stream_poll - determine status of stream specified by stream handle, or all streams
Use the stream_list command to view open streams. For example:
> 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/gecko-os.css.gz-1.0.1.3 (22670, 0)
>
Ready
>
Serial STREAM Mode
In serial STREAM mode, a single network connection (TCP/TLS/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, Stream Mode .
STREAM mode does not support the following stream types :
-
FILE
Note : When in STREAM mode, a TCP server is limited to one client connection.
The STREAM mode enabled stream appears in the stream list. Reading and writing data to the stream is not permitted.
Stream Limitations
At any moment, Gecko OS supports one UDP stream. Gecko OS supports up to 8 TCP client streams. Depending on available memory, Gecko OS can support several simultaneous file streams and the TCP Server can support multiple clients.
Each stream type in the Stream Types table below uses a single stream, with the following exceptions and qualifications:
- External UDP clients connecting to a Gecko OS UDP server do not use an additional stream. That is, a single UDP server takes only one stream and allows an unlimited number of UDP clients to be connected.
- The TCP server, with no client connected, uses no streams. Each external TCP client connecting to a Gecko OS TCP uses an additional stream.
- Only one TLS stream can be open at a time.
- When in STREAM mode , the 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 stream operations it supports.
Type | Associated Commands | Stream Operations | Description |
---|---|---|---|
FILE | file_open / file_create -o | read / poll / close | File system handle. See File system |
HTTP | http_get / http_post / http_head | read / write / poll / close | HTTP Client |
HTTPS | http_get / http_post / http_head | read / write / poll / close | Secure HTTP Client |
TCPC | tcp_client | read / write / poll / close | TCP Client |
TCPS | tcp_server | read / write / poll / close | TCP Server client stream. Note that one stream is used per client |
TLSC | tls_client | read / write / poll / close | TLS Client |
UDPC | udp_client | read / write / poll / close | UDP Client |
UDPS | udp_server | read / write / poll / close | UDP Server . Note that one stream is used for all server clients |
Streams Can Close Automatically
Use the stream.auto_close variable to set up stream auto-close. This allows streams to be available for re-use when closed remotely. See stream.auto_close .
Auto-start Network streams
The following variables allow setting up an automatic connection with a specified remote host.
- TCP/TLS Client - connection triggers when network starts
- UDP Client - connection triggers when network starts
- IO Connection - connection triggers on GPIO assertion
When an auto_start connection is configured, you must trigger the auto_start connection as specified. You cannot use the corresponding client command ( tcp_client or udp_client ) to open the connection.
Auto-start network streams are opened in the following order:
- TCP/TLS client. If TLS client auto starts, other streams will not start.
- UDP client
- TCP server
- IO connection
Network Status Indication Using GPIOs
You can configure GPIOs to act as indicators of networking states, such as the state of the WLAN connection, the Soft AP connection, or DHCP progress. You can configure a selection of blink rates to indicate states.
See variables:
See Peripherals, System Indicator Functions .
Remote Terminal Access
You can control a Gecko OS device with a TCP/IP telnet connection via a remote terminal, connected to the device via the Soft AP interface or the WLAN interface.
Configure the remote terminal with the variables:
- remote_terminal.enabled
- remote_terminal.interface
- remote_terminal.password
- remote_terminal.port
- remote_terminal.timeout
See the Wi-Fi Remote Terminal application note .
Broadcast Status Announcement
A Gecko OS device broadcasts its 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.
Configure broadcast with the variables:
- broadcast.data
- broadcast.http.host
- broadcast.interface
- broadcast.interval
- broadcast.udp.ip
- broadcast.udp.remote_port
See also the Broadcast UDP Packet Application Note .
Captive Portal
Captive portal is supported during websetup and optionally for the soft AP. When the HTTP Server receives certain requests, it redirects to the root HTTP server web page. See softap.captive_portal_enabled .