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

0

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


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