The following guide explains how to create a device certificate for your System. The generated files will then allow your device to securely connect to the MQTT API.

There are three different ways in order to obtain a Certificate: 1. In the config section of your System within the DRIVR-UI you can request, manage, and download certificates for your System. 2. You can manually create a Certificate Signing Request (CSR), submit it to DRIVR, and retrieve the signed certificate, private key, and CA certificate. This approach is compatible with all platforms. 3. Alternatively, for a more efficient process, use the drivr-certificate-client tool, which automates the creation and management of certificates. This tool is currently supported on Linux systems. More details on each individual method are outlined below.

Prerequisites

Your DRIVR Domain exists. If you don’t have one yet, please create it for free using our customer portal here. Afterwards, you can use the DRIVR UI (https://{slug}.ui.drivr.cloud) or use the GraphQL API (https://{slug}.api.drivr.cloud). Please replace {slug} with your domain identifier for performing the steps mentioned in this guide.

Methods for creating device certificates

Using DRIVR UI :

Follow these steps to create and download a System or Component Certificate using the DRIVR UI (https://{slug}.ui.drivr.cloud, please replace {slug} with your domain identifier).

1. Navigate to the system or component where the certificate is needed.
2. Click on the Config tab.
3. On left-hand side, click on Certificates. Go to the Add Certificates tab.
4. Add a name, click on Start from scratch and add expiration date.
5. Click on Create. Save the private key and click on Done.
6. Once the signing process is complete, download the signed certificate and the CA certificate.

Using a certificate signing request(CSR) :

In this section we will create the needed certificate signing request (CSR). This CSR then can be uploaded to DRIVR via the GraphQL API or DRIVR UI. After signing finished the resulting certificate, the private key and the CA certificate will be downloaded from DRIVR via the GraphQL API or DRIVR UI.

Prerequisites:

OpenSSL Installed: If OpenSSL is not installed, you can download it from the OpenSSL website or install it using your package manager. For macOS, run:

brew install openssl@3

Step 1: Create a Certificate Signing Request (CSR)

1.1: Generate a Private Key

First we need to create a private key. This key will be used to sign the CSR and later to authenticate with the MQTT API. You can create a private key with the following command:

openssl genrsa -out private.key 4096

1.2: Create the CSR

With the private key we can now create the CSR. The CSR contains information about the device that will be used to create the certificate. The CSR's Common Name (CN) must be a UUID and will be used to identify the device it must not be reused.

Create a CSR Configuration File

cat << EOF > csr.conf
[ req ]
default_bits = 4096
default_md = sha256
prompt = no
encrypt_key = no
distinguished_name = dn

[ dn ]
C = DE
O = xcnt
CN = $(python -c 'import sys,uuid; sys.stdout.write(str(uuid.uuid4()))')
EOF

Generate the CSR

openssl req -new -key private.key -config csr.conf -out device-certificate.csr

You now have a CSR file (device-certificate.csr) ready to upload to DRIVR.

Step 2: Upload the CSR and Download the Certificate

You can upload the CSR and download the signed certificate using either the DRIVR UI or the GraphQL API.

Option A: Using the DRIVR UI

1. Navigate to the system or component where the certificate is needed.
2. Click on the Config tab.
3. On left-hand side, click on Certificates. Go to the Add Certificates tab.
4. Since we generated the certificate, click on Use existing Public/Private Key.
5. Click on Browse to upload CSR. Upload the device-certificate.csr file.
6. Once the signing process is complete, download the signed certificate and the CA certificate.

Option B: Using the GraphQL API

1: Find the Issuer

Run this query to get the issuer details:

query getIssuers {
  issuers {
    items {
      uuid
      name
    }
  }
}

Note the UUID of the issuer (e.g., default).

2: Create the Certificate

Run the following mutation, replacing placeholders with actual values:

mutation create {
  createCertificate(
    name: "my-certificate", 
    issuerUuid: "<issuer uuid>", 
    entityUuid: "<system or component uuid>",
    csr: "<CSR content without newlines>"
  ) {
    uuid
    name
    status
  }
}

Typically, the PEM formatted CSR file will contain newlines. You need to remove these newlines and escape the remaining newlines with a backslash. You can do this with the following command:

awk '{printf "%s\\n", $0}' device-certificate.csr

3: Download the Certificate

Wait a few seconds for the signing process to complete, then run this query:

query getCertificate {
  certificate(uuid: "<certificate uuid>") {
    certificate
  }
}

Save the certificate to a file, replacing escaped newlines with actual newlines:

echo "<certificate content>" | sed 's/\\n/\n/g' > device-certificate.pem

4: Download the CA Certificate

Run this query to get the CA certificate:

query getCA {
  issuer(uuid: "<issuer uuid>") {
    ca
  }
}

Save the CA certificate for use with the MQTT API.

For Linux using drivr-certificate-client :

Prerequisites:

You should have a DRIVR API Token generated and set as the ENV variable as follows, or added to the command. Refer this guide for generation of User API Token.

The drivr-certificate-client simplifies the process of creating and managing device certificates.

Step 1: Download and install the drivr-certificate-client

1. Download the latest release from GitHub.

2. Unpack the archive:

   tar xf drivr-certificate-client_<version>_<platform>.tar.gz
   

3. Move the binary to your PATH:

   sudo install drivr-certificate-client /usr/local/bin
   

Step 2: Create a Device Certificate

Run the following command to request a certificate for a system or component:

drivr-certificate-client create certificate --name <name> [--system-code <system code> | --component-code <component code>] --drivr-api <DRIVR API URL>

Example: For a Component

drivr-certificate-client create certificate --name coffeemaker --component-code coffeemaker --drivr-api https://cafe.api.drivr.cloud

Example: For a System

drivr-certificate-client create certificate --name coffeemachine --system-code coffeemachine --drivr-api https://cafe.api.drivr.cloud

The tool will generate:

1. <name>.crt: The signed device certificate.
2. private.key: The private key for the certificate.

Step 3: Download the CA Certificate

To connect to the MQTT API, you also need the CA certificate of the issuer. Use the following command:

drivr-certificate-client fetch ca --drivr-api <DRIVR API URL> --api-key <API Token>

Example

drivr-certificate-client fetch ca --drivr-api https://cafe.api.drivr.cloud --api-key <API Token>

The CA certificate will be saved as ca.crt.

API URL and key can also be exported via the environment variables DRIVR_GRAPHQL_API and DRIVR_API_KEY.

You’ve successfully created and downloaded a device certificate. Use the private key, signed certificate, and CA certificate to securely connect your device to the MQTT API.

Whether you have used the DRIVR UI, provided a CSR, or the drivr-certificate-client, your device is now ready for secure communication with DRIVR.