TLS Certs

6min
Overview
Transport Layer Security (TLS) can be used to establish a secure, encrypted connection between the LE Sparkplug Edge Node and your MQTT broker(s). This requires providing specific certificate information during configuration.
Prerequisites
To configure TLS, you will need the following files, typically provided by your MQTT broker administrator or your organization's security team:
CA Certificate (ca_cert): The certificate of the Certificate Authority (CA) that signed the MQTT broker's server certificate. This is used to verify the broker's identity.
Client Certificate (client_cert): The public certificate for this specific LE Sparkplug Edge Node client. The broker uses this to verify the client's identity (mutual TLS/mTLS).
Client Private Key (client_key): The corresponding private key for the client certificate. This must be kept secret.
Step 1: Encode Certificates to Base64
The application requires the content of these certificate/key files to be provided as Base64-encoded strings within the configuration.
Encoding Methods:
Online Tools:
Open your certificate or key file (e.g., my_ca.pem, client.crt, client.key) in a text editor.
Copy the entire content, including the -----BEGIN...----- and -----END...----- lines.
Paste the content into an online Base64 encoder (like base64encode.org) and click "Encode".
Copy the resulting Base64 string.
Repeat for each required file (CA cert, client cert, client key).
Command Line (Linux/macOS):
Bash
# Example for CA certificate
base64 -w 0 my_ca.pem

# Example for client certificate
base64 -w 0 client.crt

# Example for client private key
base64 -w 0 client.key
# Example for CA certificate
base64 -w 0 my_ca.pem

# Example for client certificate
base64 -w 0 client.crt

# Example for client private key
base64 -w 0 client.key
﻿
(The -w 0 flag prevents line wrapping in the output)
Command Line (Windows PowerShell):
PowerShell
# Example for CA certificate
[Convert]::ToBase64String([IO.File]::ReadAllBytes("my_ca.pem"))

# Example for client certificate
[Convert]::ToBase64String([IO.File]::ReadAllBytes("client.crt"))

# Example for client private key
[Convert]::ToBase64String([IO.File]::ReadAllBytes("client.key"))
# Example for CA certificate
[Convert]::ToBase64String([IO.File]::ReadAllBytes("my_ca.pem"))

# Example for client certificate
[Convert]::ToBase64String([IO.File]::ReadAllBytes("client.crt"))

# Example for client private key
[Convert]::ToBase64String([IO.File]::ReadAllBytes("client.key"))
﻿
Step 2: Add Base64 Strings to Configuration
Once you have the Base64-encoded strings, add them to your configuration:
Method 1: Configuration File (config.json)
Add the ca_cert, client_cert, and client_key fields to the relevant server object within the mqtt.servers array. Also, ensure the url starts with ssl:// or tls:// (depending on broker requirements) and includes the correct TLS port (e.g., 8883).
JSON
{
    "edge_api_token": "0iriyynzv5xjac1aupqxm4j2tzuls5pf",
    "mqtt": {
        "servers": [
            {
                "url": "ssl://mqtt.example.com:8883",
                "user": "myuser",
                "password": "mypassword",
                "ca_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUtCk1JSUVkakNDQWRZQ0...",
                "client_cert": "LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tpRd0lC...",
                "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktUlCRXdF...",
                "skip_cert_verify": false
            },
            {
                "url": "tcp://192.168.56.1:1883",
                "username": "",
                "password": ""
            }
        ],
        "client_id": "",
        "client_id_suffix": "",
        "connect_timeout": "30s",
        "write_timeout": "3s",
        "keepalive": 30
    },
    "group_id": "LE-Group",
    "node_id": "LE-Node",
    "primary_host_support": true,
    "primary_host_id": "LE-97IS6VF",
    "le_logging_level": "info"
}
{
    "edge_api_token": "0iriyynzv5xjac1aupqxm4j2tzuls5pf",
    "mqtt": {
        "servers": [
            {
                "url": "ssl://mqtt.example.com:8883",
                "user": "myuser",
                "password": "mypassword",
                "ca_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FUtCk1JSUVkakNDQWRZQ0...",
                "client_cert": "LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtFWS0tpRd0lC...",
                "client_key": "LS0tLS1CRUdJTiBSU0EgUFJJVkFURSBLRVktUlCRXdF...",
                "skip_cert_verify": false
            },
            {
                "url": "tcp://192.168.56.1:1883",
                "username": "",
                "password": ""
            }
        ],
        "client_id": "",
        "client_id_suffix": "",
        "connect_timeout": "30s",
        "write_timeout": "3s",
        "keepalive": 30
    },
    "group_id": "LE-Group",
    "node_id": "LE-Node",
    "primary_host_support": true,
    "primary_host_id": "LE-97IS6VF",
    "le_logging_level": "info"
}
﻿
Method 2: Environment Variable (MQTT_SERVERS)
Embed the Base64 strings directly into the JSON string assigned to the MQTT_SERVERS environment variable. Remember to handle shell escaping carefully.
Bash
# Example docker run fragment
docker run ... \
  -e MQTT_SERVERS='[{\"url\":\"ssl://mqtt.secure.com:8883\",\"user\":\"myTlsUser\",\"password\":\"myTlsPassword\",\"ca_cert\":\"LS0tLS1CR...\",\"client_cert\":\"LS0tLS1C...\",\"client_key\":\"LS0tLS1C...\",\"skip_cert_verify\":false}]' \
  ...
# Example docker run fragment
docker run ... \
  -e MQTT_SERVERS='[{\"url\":\"ssl://mqtt.secure.com:8883\",\"user\":\"myTlsUser\",\"password\":\"myTlsPassword\",\"ca_cert\":\"LS0tLS1CR...\",\"client_cert\":\"LS0tLS1C...\",\"client_key\":\"LS0tLS1C...\",\"skip_cert_verify\":false}]' \
  ...
﻿
(Base64 strings abbreviated for clarity. Ensure the entire string is included.)
TLS Configuration Fields
ca_cert (String, Base64): The CA certificate used to verify the server.
client_cert (String, Base64): The client's public certificate.
client_key (String, Base64): The client's private key.
skip_cert_verify (Boolean): Defaults to false. If set to true, the client will not verify the broker's certificate against the provided ca_cert. This disables protection against man-in-the-middle attacks and should only be used for specific testing scenarios, never in production.
﻿
Environment Variables
DH Historian Agent