UDP Server

UDP can be used to submit sensor data, access small documents, and get asynchronous notifications when a document changes.

The protocol targets low-bandwidth applications, e.g. a sensor submitting 1 kB of sensor data per minute. For such applications, it is much more efficient than HTTP/REST requests.

Configuration

To use the UDP server, add a UDP port in the configuration file:

The port number may be the same as for HTTP, which uses TCP as underlying protocol.

Message format

UDP packets have the following structure:

Every device accessing via UDP should use a unique 8-byte device ID. Every device ID is configured as account with the prefix UDP/.... The corresponding account key is used to encrypt the payload and produce the MAC.

Since the same key is used to encrypt all packets, every packet must use a different slice of the Ctr range. The Ctr value is constructed using the current timestamp in milliseconds since epoch. Some requests expect this value to be monotonically increasing to establish an order, or thwart against replay attacks.

The server uses the same Ctr value to create a response, but sets the leftmost bit to 1. The client may use this to map responses to requests.

Malformed messages, or messages with a wrong MAC are silently ignored.

Packet loss

UDP packets are sent and forgotten, but may get lost or delayed in the network. The sender should therefore retransmit a request if it does not receive any response within a certain amount of time.

Note that either the request or the response packet may have gotten lost. The protocol is stateless, and can handle duplicates.