General
This page documents the general configuration.
Table of Contents
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): |
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 |
120 |
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:
Below we explain the sequence:
Load device public key field (
kpub
) from thedevice.json
fileDecode the device public key (base64)
Generate random user key pair (public and private) using curve
secp256r1
Calculate shared secret using device public key and user private key
Derive shared symmetric key using HMAC-SHA256 with “config” as data and shared secret as key. Use the first 16 bytes of the output
Encode user public key (used by the device to calculate the same shared symmetric key for decryption)
Set the encoded user public key in the device configuration file
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:
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:
Disabled
Error: Critical issues
Warning (+ Error): Temporary or less critical issues
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.