General

This page documents the general configuration.

Configuration file fields

This section is autogenerated from the Rule Schema.


Device device

Meta data device.properties.meta

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

type: string minLength: 0 maxLength: 30

Security security

Server public key security.properties.kpub

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

type: string minLength: 0 maxLength: 100

Debug debug

Debug functionality for use during installation and troubleshooting.

System log debug.properties.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: integer default: 0 options: 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 for use in encrypting secure fields - see the CANedge Intro.

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