The CUPS Protocol

The LoRa Basics™ Station periodically queries the CUPS server for updates. The protocol is HTTP/REST, using the client/server authentication methods described in Credentials. With each query, the Station provides information about its current state and receives a binary blob containing updates for its LNS and CUPS credentials, along with a generic data segment with arbitrary updates.

The format of the generic data segment is platform-dependent. The Station simply executes this file after downloading it. Usually it is a self-extracting shell script. However, it may also be a binary executable.

HTTP POST Request

The URI of the CUPS update end point is constructed from the contents of the cups.uri file (or one of its fallback alternatives as described in Credentials). The path /update-info is added and an HTTP POST request is submitted with the body. The HTTP POST request contains the following JSON object:

{
  "router"      : ID6,
  "cupsUri"     : "URI",
  "tcUri"       : "URI",
  "cupsCredCrc" : INT,
  "tcCredCrc"   : INT,
  "station"     : STRING,
  "model"       : STRING,
  "package"     : STRING,
  "keys"        : [INT]
}

The router field is the ID6 representation of the gateway’s identity.

The values of the cupsUri and tcUri fields are the contents of the credential files cups.uri and tc.uri, respectively.

The cupsCredCrc and tcCredCrc fields are CRC32 checksums calculated over the concatenated credentials files cups.{trust,cert,key} and tc.{trust,cert,key}.

The station, model, and package fields describe the current version of the Station, the gateway model and the package version. The package version may contain information about the state of the underlying system and its configuration.

The keys field contains an array of CRC32 checksums for each of the signing keys installed on the firmware where the Station is running. The response from the server will provide a signed update, if available, with a signature matching one of these signing keys.

HTTP POST Response

The CUPS server shall respond with HTTP status code 200 and a binary response message. The Content-Type header is set to:

Content-Type: application/octet-stream

The response body shall be in the following binary format:

Bytes	Field	Description
1	cupsUriLen	Length of CUPS URI (cun)
cun	cupsUri	CUPS URI (cups.uri)
1	tcUriLen	Length of LNS URI (tun)
tun	tcUri	LNS URI (tc.uri)
2	cupsCredLen	Length of CUPS credentials (ccn)
ccn	cupsCred	Credentials blob
2	tcCredLen	Length of LNS credentials (tcn)
tcn	tcCred	Credentials blob
4	sigLen	Length of signature for update blob plus size of the keyCRC field (4)
4	keyCRC	CRC of the key used for the signature
sig	sig	Signature over the update blob
4	updLen	Length of generic update data (udn)
udn	updData	Generic update data blob

The length fields shall be encoded in little endian. If any of the length fields is zero, there is no update for that particular component. If CUPS returns a blob where all length fields are zero, there is no update pending.

Note

The CUPS null response consists of 14 zero bytes: (HEX) 0000000000000000000000000000.

The credentials blob is a concatenation of trust/cert/key, which is able to encode client authentication using X509 certificates and using tokens.

For client authentication using X509 certificates, all credentials are encoded in DER format:

• trust is the certificate of the trusted certificate authority (CA)

• cert is the personal certificate for the gateway

• key is the personal private key for the gateway

For token-based authentication, trust is the same DER as above; however:

• the private cert is not required, and, if absent, the response will contain four “zero” octets for this part

• The key is an authorization token that must be added to the subsequent requests to CUPS as part of the headers for the HTTP POST request

The Station unpacks non-empty fields into their respective local credential files. If generic update data is present and the signature is verified, the update gets saved into a file named update.bin and is executed once downloaded successfully.

This executable/script may replace the Station binary. It may then update the configuration file and the underlying system before restarting the Station process or rebooting the gateway.

Error Conditions

The CUPS server may respond with an error condition. In an error response, the HTTP status code in the response shall not be 200 and the reason text in the status line is rendered in a log message and can be used to give a hint as to hwy the request failed. The message body of a non 200 response is discarded.