本页目录

• DTLS configuration using PEM certificates file
• SSL configuration using Java keystore (deprecated)
• Additional configuration properties
• Self-signed certificates generation
  • PEM certificate file
  • Java keystore
• Client Examples

ThingsBoard provides the ability to run LwM2M server over DTLS. Platform supports Pre-Shared Key, Raw Public Key and X.509 Certificate credentials over DTLS. DTLS provisioning requires valid ECDSA certificates. ECDSA keys are smaller than RSA keys and thus more preferable for constrained devices. See comparison article for more details. We recommend to use valid SSL certificates generated using trusted CA authorities and avoid spending time on resolving issues with self-signed certificates. See instructions below on how to configure SSL for certificates stored in PEM file format or Java Keystore.

DTLS configuration using PEM certificates file

Configure the following environment variables via configuration file, docker-compose or kubernetes scripts. We will use thingsboard.conf for example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
...
export LWM2M_SERVER_CREDENTIALS_ENABLED=true
export LWM2M_SERVER_CREDENTIALS_TYPE=PEM
export LWM2M_SERVER_PEM_CERT=server.pem
export LWM2M_SERVER_PEM_KEY=server_key.pem
export LWM2M_SERVER_PEM_KEY_PASSWORD=secret
# To enable Bootstrap and Bootstrap over DTLS
export LWM2M_ENABLED_BS=true
export LWM2M_BS_CREDENTIALS_ENABLED=true
export LWM2M_BS_CREDENTIALS_TYPE=PEM
export LWM2M_BS_PEM_CERT=server.pem
export LWM2M_BS_PEM_KEY=server_key.pem
export LWM2M_BS_PEM_KEY_PASSWORD=secret
...

where:

• LWM2M_SERVER_CREDENTIALS_ENABLED - Enable/disable X509 Certificate/RPK credentials support;
• LWM2M_SERVER_CREDENTIALS_TYPE - Server credentials type. PEM - pem certificate file; KEYSTORE - java keystore;
• LWM2M_SERVER_PEM_CERT - Path to the server certificate file. Holds server certificate or certificate chain, may also include server private key;
• LWM2M_SERVER_PEM_KEY - Path to the server certificate private key file. Optional by default. Required if the private key is not present in server certificate file;
• LWM2M_SERVER_PEM_KEY_PASSWORD - Optional server certificate private key password.

After completing the setup, start or restart the ThingsBoard server.

Make sure the certificate files are reachable by ThingsBoard process:

• Linux: use /etc/thingsboard/conf folder. Make sure the files have same permissions as thingsboard.conf; Use relative file path, e.g. server.pem;
• Docker Compose: mount or use existing volume to /config folder of the container; Use full file path, e.g. /config/server.pem;
• K8S: mount separate volume to /https-config or similar folder. Use full file path, e.g. /https-config/server.pem;
• Windows: use C:\Program Files (x86)\thingsboard\conf\ folder. Make sure the files have same permissions as thingsboard.conf; Use relative file path, e.g. server.pem;

SSL configuration using Java keystore (deprecated)

Configure the following environment variables via configuration file, docker-compose or kubernetes scripts. We will use thingsboard.conf for example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
...
export LWM2M_SERVER_CREDENTIALS_ENABLED=true
export LWM2M_SERVER_CREDENTIALS_TYPE=KEYSTORE
export LWM2M_SERVER_KEY_STORE_TYPE=JKS
export LWM2M_SERVER_KEY_STORE=server.jks
export LWM2M_SERVER_KEY_STORE_PASSWORD=secret
export LWM2M_SERVER_KEY_ALIAS=server
export LWM2M_SERVER_KEY_PASSWORD=secret
# To enable Bootstrap and Bootstrap over DTLS
export LWM2M_ENABLED_BS=true
export LWM2M_BS_CREDENTIALS_ENABLED=true
export LWM2M_BS_CREDENTIALS_TYPE=JKS
export LWM2M_BS_KEY_STORE=server.jks
export LWM2M_BS_KEY_STORE_PASSWORD=secret
export LWM2M_BS_KEY_ALIAS=server
export LWM2M_BS_KEY_PASSWORD=secret
...

where:

• LWM2M_SERVER_CREDENTIALS_ENABLED - Enable/disable X509 Certificate/RPK credentials support;
• LWM2M_SERVER_CREDENTIALS_TYPE - Server credentials type. PEM - pem certificate file; KEYSTORE - java keystore;
• LWM2M_SERVER_KEY_STORE_TYPE - Type of the key store supported by your Java distribution. PKCS12 is recommended.
• LWM2M_SERVER_KEY_STORE - Path to the key store that holds the SSL certificate. Holds server certificate or certificate chain and the private key;
• LWM2M_SERVER_KEY_STORE_PASSWORD - Password to access the key store;
• LWM2M_SERVER_KEY_ALIAS - Optional alias of the private key; If not set, the platform will load the first private key from the keystore;
• LWM2M_SERVER_KEY_PASSWORD - Optional password to access the private key. If not set, the platform will attempt to load the private keys that are not protected with the password;

After completing the setup, start or restart the ThingsBoard server.

Make sure the certificate files are reachable by ThingsBoard process:

• Linux: use /etc/thingsboard/conf folder. Make sure the files have same permissions as thingsboard.conf; Use relative file path, e.g. keystore.p12;
• Docker Compose: mount or use existing volume to /config folder of the container; Use full file path, e.g. /config/keystore.p12;
• K8S: mount separate volume to /https-config or similar folder. Use full file path, e.g. /https-config/keystore.p12;
• Windows: use C:\Program Files (x86)\thingsboard\conf\ folder. Make sure the files have same permissions as thingsboard.conf; Use relative file path, e.g. keystore.p12;

Additional configuration properties

You may configure following additional environment variables via configuration file, docker-compose or kubernetes scripts.

• LWM2M_SECURITY_BIND_ADDRESS - the bind address for the secure LwM2M server. Default value 0.0.0.0 indicates all interfaces;
• LWM2M_SECURITY_BIND_PORT - the bind port for the secure LwM2M server. Default value is 5686;
• TB_LWM2M_SERVER_SECURITY_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT - Skip certificate validity check for client certificates. Default value is false.
• LWM2M_BS_SECURITY_BIND_ADDRESS - the bind address for the secure LwM2M Bootstrap server. Default value 0.0.0.0 indicates all interfaces;
• LWM2M_BS_SECURITY_BIND_PORT - he bind port for the secure LwM2M Bootstrap server. Default value is 5688;

Self-signed certificates generation

Use instructions below to generate your own certificate files. Useful for tests, but time consuming and not recommended for production.

PEM certificate file

Note This step requires Linux based OS with openssl installed.

To generate a server self-signed PEM certificate and private key, use the following command:

1
2
openssl ecparam -out server_key.pem -name secp256r1 -genkey
openssl req -new -key server_key.pem -x509 -nodes -days 365 -out server.pem 

You can also add -nodes (short for no DES) if you don’t want to protect your private key with a passphrase. Otherwise, it will prompt you for “at least a 4 character” password.

The days parameter (365) you can replace with any number to affect the expiration date. It will then prompt you for things like “Country Name”, but you can just hit Enter and accept the defaults.

Add -subj ‘/CN=localhost’ to suppress questions about the contents of the certificate (replace localhost with your desired domain).

Self-signed certificates are not validated with any third party unless you import them to the browsers previously. If you need more security, you should use a certificate signed by a certificate authority (CA).

Java keystore

Note This step requires Linux based OS with Java installed.

Download server.keygen.sh from the official ThingsBoard repository to your working directory.

Download keygen.properties file to your working directory and populate it with desired values. For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
DOMAIN_SUFFIX="$(hostname)"
SUBJECT_ALTERNATIVE_NAMES="ip:127.0.0.1"
ORGANIZATIONAL_UNIT=ThingsBoard
ORGANIZATION=ThingsBoard
CITY="San Francisco"
STATE_OR_PROVINCE=CA
TWO_LETTER_COUNTRY_CODE=US

SERVER_KEYSTORE_PASSWORD=password
SERVER_KEY_PASSWORD=password

SERVER_KEY_ALIAS="serveralias"
SERVER_FILE_PREFIX="server"
SERVER_KEY_ALG="EC"
SERVER_KEY_GROUP_NAME="secp256r1"
SERVER_KEYSTORE_DIR="/etc/thingsboard/conf"

where

• DOMAIN_SUFFIX - Corresponds to CN value of the certificate. Must correspond to the target server domain (wildcards are allowed). Defaults to the current hostname
• ORGANIZATIONAL_UNIT - Corresponds to OU value of the certificate.
• ORGANIZATION - Corresponds to O value of the certificate.
• CITY - Corresponds to L value of the certificate.
• STATE_OR_PROVINCE - Corresponds to ST value of the certificate.
• TWO_LETTER_COUNTRY_CODE - Corresponds to C value of the certificate.
• SERVER_KEYSTORE_PASSWORD - Server Keystore password
• SERVER_KEY_PASSWORD - Server Key password. May or may not be the same as SERVER_KEYSTORE_PASSWORD
• SERVER_KEY_ALIAS - Server key alias. Must be unique within the keystore
• SERVER_FILE_PREFIX - Prefix to all server keygen-related output files
• SERVER_KEYSTORE_DIR - The default location where the key would be optionally copied. Can be overriden by -d option in server.keygen.sh script or entered manually upon the scrip run

The rest of the values are not important for the server keystore generation

To run the server keystore generation, use following commands.

1
2
chmod +x server.keygen.sh
sudo ./server.keygen.sh

You may run this script with no arguments, or alternatively, you can specify the following optional arguments:

• -c | –copy - Specifies if the keystore should be copied to the server directory. Defaults to true
• -d | –dir - Server keystore directory, where the generated SERVER_FILE_PREFIX.jks keystore file will be copied. If specified, overrides the value from the properties file
• -p | –props | –properties - Specifies the relative path to the properties file. Defaults to ./keygen.properties

This script will run keytool using the configuration specified. It will generate the following output files:

• SERVER_FILE_PREFIX.jks - Java keystore file. This is the file which will be used by ThingsBoard MQTT Service
• SERVER_FILE_PREFIX.cer - Server public key file. It will be then imported to client’s .jks keystore file.
• SERVER_FILE_PREFIX.pub.pem - Server public key in PEM format, which can be then used as a keystore or imported by non-Java clients.

Client Examples

See following resources:

• Access Token based authentication for example of one-way SSL connection;
• X.509 Certificate based authentication for example of two-way SSL connection.