X.509 Certificate setup

From AdvanNet-2.10.14, using a X.509 certificate authentication is possible.

This guide focuses on how to create a client certificate and private key to connect to our secure MQTT broker using X.509 certificate authentication.

To connect your device, you need a unique client certificate(.crt) and its private key(.key), both signed by our Certificate Authority (CA).

Step 1: Generate Your Client's Private Key

This key is unique to your client and must be kept highly confidential.

1. Create a dedicated directory for your client's certificates (e.g., /home/keonn/my_new_client_certs/):

mkdir -p /home/keonn/my_new_client_certs/

cd /home/keonn/my_new_client_certs/

2. Generate the private key:
   openssl genrsa -out my_client_device.key 2048

This creates my_client_device.key.

Step 2: Generate Your Client's Certificate Signing Request (CSR)

The CSR contains your client's public key and identifying information.

Create the CSR:

openssl req -new -key my_client_device.key -out my_client_device.csr -subj "/C=XX/ST=XXXX/L=XXXX/O=XXXX/OU=XXXX/CN=YourUniqueClientName/emailAddress=your_email@example.com"

1. • Important: YourUniqueClientName will be your client's username in Mosquitto's ACLs. This creates my_client_device.csr.

Each of those fields in the -subj string represents part of the Distinguished Name (DN) in the certificate, which uniquely identifies the entity the certificate is issued to:

• C = Country, Two-letter ISO 3166 country code (e.g., Spain = ES)

• ST = State or Province, Full name of the state or province

• L = Locality, City or locality name

• O = Organization, Legal name of your organization or company

• OU = Organizational Unit, Department or division (e.g., IT, Clients, DevOps)

• CN = Common Name, Usually the name of the server or client (e.g., domain name, device ID)

• emailAddress = Contact email for the certificate subject

Step 3: Get Your CSR Signed by the CA (Administrator's Task)

This step must be performed by the broker administrator, who has access to the CA's private key.

1. Copy my_client_device.csr to the CA directory on the BeagleBone (e.g., /home/keonn/etc/mqtt/certs/custom-ca/).

2. Navigate to the CA directory:
   cd /home/keonn/etc/mqtt/certs/custom-ca/

3. Sign the CSR using the CA:

openssl x509 -req \ 

-in my_client_device.csr \ 

-CA /home/keonn/etc/mqtt/certs/custom-ca/self_signed_ca.crt \ 

-CAkey /home/keonn/etc/mqtt/certs/custom-ca/privateKey_ca.key \ 

-CAcreateserial \ 

-out my_client_device.crt \ 

-days 365 -sha256

This creates my_client_device.crt.

4. Move signed certificate back: Copy my_client_device.crt to /home/keonn/my_new_client_certs/.

You now have my_client_device.key and my_client_device.crt.

Connecting Your MQTT Client

With your client certificate (my_client_device.crt), its private key (my_client_device.key), and our CA's public certificate (/home/keonn/etc/mqtt/certs/custom-ca/self_signed_ca.crt), you can configure your MQTT client.

1. Copy files: Transfer my_client_device.key, my_client_device.crt, and self_signed_ca.crt to a secure location on your client device.

   • The CA's public certificate (self_signed_ca.crt) is located at /home/keonn/etc/mqtt/certs/custom-ca/self_signed_ca.crt on the BeagleBone.

2. Update Mosquitto ACLs (Administrator's Task): Edit /etc/mosquitto/aclfile.acl on the BeagleBone to grant YourUniqueClientName permissions, then restart Mosquitto: 

sudo systemctl restart mosquitto

3. Configure Your MQTT Client: Provide these parameters to your client library or tool:

   • Broker Address: ssl://<BEAGLEBONE_IP_ADDRESS>:8883

   • Port: 8883

   • Client ID: Unique ID (e.g., MyClientApp).

   • SSL/TLS Enabled: Yes

   • CA Certificate: Path to self_signed_ca.crt (to trust the broker).

   • Client Certificate: Path to my_client_device.crt (to identify your client).

   • Client Private Key: Path to my_client_device.key (to authenticate).

Example mosquitto_pub:

mosquitto_pub --host <BEAGLEBONE_IP_ADDRESS> --port 8883 --cafile /path/to/self_signed_ca.crt --cert /path/to/my_client_device.crt --key /path/to/my_client_device.key --qos 1 --topic "devices/YourUniqueClientName/status" --message "Hello!"

Example mosquitto_sub:

mosquitto_sub --host <BEAGLEBONE_IP_ADDRESS> --port 8883 --cafile /path/to/self_signed_ca.crt --cert /path/to/my_client_device.crt --key /path/to/my_client_device.key --qos 1 --topic "devices/YourUniqueClientName/#"

AdvanNet configuration

To use the X.509 Certificate Authentication, we need to navigate to MQTT Service, where we can find a checkbox with the name "Uses X.509 certificate?". Once checked, the MQTT Service will try to use the certificates to authenticate.