LoRa Basics™ Station 2.0.5 documentation

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.

CUPS Protocol

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 a binary blob in the following 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

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 are 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.

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 which 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.