General

This page documents the general configuration.

Configuration file fields

This section is autogenerated from the Rule Schema.

Device general.device

Meta data general.device.meta

Optional meta data string. Displayed in device file and log file headers. Example: Site1; Truck4; ConfigRev12

Type

Min length

Max length

string

0

30

Security general.security

Server public key general.security.kpub

Server / user ECC public key in base64 format. Shall match the encryption used for all protected fields.

Type

Min length

Max length

string

0

100

Debug general.debug

Debug functionality for use during installation and troubleshooting.

System log general.debug.syslog

System events logged to the SD-card. The log levels are listed in order of increasing amount of information logged. Should only be enabled if needed during installation or troubleshooting.

Type

Default

Options

integer

1

Disable (0): 0 Error (1): 1 Error + Warning (2): 2 Error + Warning + Info (3): 3

Restart timer general.debug.restart_timer

Number of runtime hours after which the device automatically restarts (set 0 to disable). Example: Set to 24 to restart after one day of runtime.

Type

Default

Minimum

Maximum

integer

24

0

168

Configuration explained

This section contains additional information and examples.

Device meta data

The device meta data is an optional string copied to the device.json file and log file headers.

Security

Some configuration field values can be encrypted to hide sensitive data stored in the Configuration File (passwords etc.). In this section, we provide a technical summary and provide resource suggestions for implementing the encryption.

The field encryption feature uses a key agreement scheme based on Elliptic Curve Cryptography (ECC) (similar to the one used in a TLS handshake). The scheme allows the device and user to compute the same shared secret, without exposing any secrets. The shared secret is in turn used to generate a symmetric key, which is used to encrypt / decrypt protected field values.

The following sequence diagram illustrates the process of encrypting configuration fields:

sequenceDiagram participant Device (device.json) participant Device (config.json) participant User Device (device.json)->>User: 1. Load device public key (base64) User->>User: 2. Decode (base64) device public key User->>User: 3. Generate user ECC key pair User->>User: 4. Calculate shared secret User->>User: 5. Derive symmetric key from shared secret User->>Device (config.json): 6. Encode (base64) user public key User->>Device (config.json): 7. Set user public key in config loop 8. Set values User->>Device (config.json): 8a. Encrypt field value User->>Device (config.json): 8b. Concatenate iv and ct User->>Device (config.json): 8c. Encode (base64) User->>Device (config.json): 8d. Set value in config end

Below we explain the sequence:

  1. Load device public key field (kpub) from the device.json file

  2. Decode the device public key (base64)

  3. Generate random user key pair (public and private) using curve secp256r1

  4. Calculate shared secret using device public key and user private key

  5. Derive shared symmetric key using HMAC-SHA256 with “config” as data and shared secret as key. Use the first 16 bytes of the output

  6. Encode user public key (used by the device to calculate the same shared symmetric key for decryption)

  7. Set the encoded user public key in the device configuration file

  8. Use AES-128 CTR to encrypt protected fields using the symmetric key. The resulting initialization vector (iv) and cipher text (ct) are concatenated (iv + ct), base64 encoded and stored in the configuration file

Note

The symmetric key shall match the public key set by the user in the configuration and protected fields shall be encrypted with this symmetric key

Note

By storing the symmetric key it is possible to change specific protected fields - without updating the user public key (and in turn all other protected fields)

Encryption tools

Tools are provided with the CANedge which can be used to encrypt sensitive fields.

Example Python code

You can batch-encrypt passwords across multiple devices using e.g. Python. Below we provide a basic code sample to illustrate how Python can be used to encrypt plain-text data. The example code is tested with Python 3.7.2 and requires the pycryptodome crypto library:

Python example code

Debug

System log

A system log can be enabled to output system events to a file (syslog.txt) stored on the SD-card. The size of the log file is limited to 1 MB. The user can safely delete the log file at any time.

Note

Log levels 2-3 should only be enabled during installation or troubleshooting

System log verbosity levels:

  1. Disabled

  2. Error: Critical issues

  3. Warning (+ Error): Temporary or less critical issues

  4. Info (+ Error + Warning): Information generated by normal operation

Restart timer

The restart_timer can be used to restart the device automatically after a set number of hours. Set to zero to disable.

Note

Automatic restart of the device can help alleviate rare network issues.