Sysclient protocol

The sysclient protocol is used for devices to register in the Devices App and to tunnel HTTP connections to access the device UI through the Devices App.
Binary websocket messages are used for the communication.

Table of contents

• DevicesApp
• Binary protocol
• Sysclient message header
• Admin message header
• Tunnel message header

The Devices App provides a URL to which so called "sysclients" can connect to. The URL e.g. looks like this: wss://app-platform-dns/domain.com/devices/sysclients
Any sysclient which connects to this URL will not be added to any domain inside the Devices App as long as it can't answer the challenge request successfully.

The first byte of each message contains the sysclient message type.

// An sysclient message has the following format (depending on the value of the message type - SMT = sysclient message type):
//
// SMT | Byte offset
//     |  0      1      2      3      4      5      6      7      8      9     ...
//     +------+------+------+------+------+------+------+------+------+------+------+
//  1  | Msg- |   Adm-Msg   | Data.........
// --- | Type +------+------+------+------+------+------+------+------+------+------+
//  2  |      |        Session-ID         |         Event-Type        |  Data.....
//     +------+------+------+------+------+------+------+------+------+------+------+

Message flow of admin messages

• The sysclient connects to the Devices App.
• The sysclient sends the identify admin message.
• The sysclient receives a challenge admin message from the Devices App if already inside a domain.
• The sysclient sends the identify admin message with the calculated digest.
• The sysclient receives a admin password message from the Devices App if already inside a domain and the domain provides its password to all devices.
  This message can be always received, e.g. if the domain password gets changed.
• If the sysclient is added to a domain during this session, an admin sysclient password message is received.

Parameters

Example JSON object

{
  "id": "009033460af2",
  "product": "IP222",
  "version": "13r2 dvl [13.4250\/131286\/1300]",
  "fwBuild": "134250",
  "bcBuild": "131286",
  "major": "13r2",
  "fw": "ip222.bin",
  "bc": "boot222.bin",
  "mini": false,
  "platform": {
    "type": "PHONE"
  },
  "digest": "f3d37205d8eb93a4ccdd236b5a957c98d629d925aa58fe03b770035853c12984",
  "ethIfs": [
    {
      "if": "ETH0",
      "ipv4": "172.16.4.141",
      "ipv6": "2002:91fd:9d07:0:290:33ff:fe46:af2"
    }
  ]
}

Parameters

Parameters

Digest calculation

class hash hash;
byte digest_bin[HASH_SIZE_SHA256];
char digest[HASH_SIZE_SHA256 * 2 + 1];
hash.init(HASH_SHA256);
hash.update(id, strlen(id));
hash.update(":", 1);
hash.update(product, strlen(product));
hash.update(":", 1);
hash.update(version, strlen(version));
hash.update(":", 1);
hash.update(challenge, strlen(challenge));
hash.update(":", 1);
hash.update(password, strlen(password));
hash.final(digest_bin);
str::from_hexmem(digest_bin, HASH_SIZE_SHA256, digest);

Parameters

Password decryption

size_t len = strlen(pwdEncrypted);
size_t outLen = len / 2 + 1;
char * k = (char *)alloca(strlen(seed) + strlen(sysclientPassword) + 2);
char * pwdDecrypted = (char *)alloca(outLen);
byte * i = (byte *)alloca(outLen);
len = str::to_hexmem(pwdEncrypted, i, outLen);
_sprintf(k, "%s:%s", seed, sysclientPassword);
Cipher c;
c.Init(CIPHER_RC4, (const byte *)k, strlen(k), false);
c.Crypt(i, (byte*)pwdDecrypted, len);
pwdDecrypted[len] = '\0';

Parameters

Parameters

Parameters

Message flow of socket messages

• A socket send is received with a new session id.
• The sysclient sends a socket send result with the session id.
• A socket send is received if further data must be sent to the local webserver. Answer with socket send results in this case.
• A socket recv is received to receive new data from the local webserver.
• The sysclient sends a socket recv result with the session id and the data from the local webserver.
• A socket recv might be received multiple times until all data is read.
• A socket shutdown is received to indicate that this HTTP request is finished.
• A socket shutdown is sent from the sysclient as a confirmation.