Overview

This guide will show you how to create a device certificate to use the MQTT API. In this guide 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.

With these files you can then connect to the MQTT API.

You can also use the drivr-certificate-client which bundles the process of creating the CSR and uploading it to DRIVR. More information about this can be found here.

Prerequisites

In order to follow this guide successfully, you need a DRIVR domain. If you don't have one yet, you can create one for free here.

You also need to have a recent version of OpenSSL installed on your machine. You can check if you have OpenSSL installed by running the following command:

openssl version

If you don't have OpenSSL installed, you can download it from the OpenSSL website or preferably install it via your package manager.

On macOS you can install OpenSSL via Homebrew:

brew install openssl@3

Create a Certificate Signing Request (CSR)

First we need to create a Certificate Signing Request (CSR) that will be uploaded to DRIVR to get a signed device certificate.

Create 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

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.

Open a shell and run the following commands to create the CSR.

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

Create the CSR

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

Now you have created a CSR in the file device-certificate.csr that can be uploaded to DRIVR via the DRIVR UI or the GraphQL API to get a signed device certificate.

Create and download the Certificate in DRIVR

With the CSR created, you can now upload it to DRIVR to get a signed device certificate. Using the DRIVR UI is by far the easiest way to do this.

DRIVR UI

In the DRIVR UI browse to the system or component the certificate should be created for and find the Certificates tab on the left side. Click on the "Create Certificate" button and upload the device-certificate.csr file.

When signing finished you can download the certificate and the CA certificate of the issuer.

GraphQL API

Find the Issuer to use

In order to create the certificate in DRIVR, we need to know the issuer that will sign the certificate. You can find the issuer by running the following query:

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

Most likely you will only have one issuer named default. Make a note of the UUID of the issuer, as it will be needed in the next step.

Create the certificate via GraphQL

Head over to GraphiQL to create a Certificate from your CSR. Alternatively you can use the curl command to send the request to the GraphQL API.

Run the following mutation, adjusting the values accordingly:

```graphql
mutation create {
  createCertificate(
    name: "my-certificate", 
    issuerUuid: "<issuer uuid from the last step>", 
    entityUuid: "<the uuit of the system or component this certificate should be bound to>",
    csr: "<the content of the device-certificate.csr file without newlines see below>"
  ) {
    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

Make a note of the uuid of the certificate, as it will be needed in the next step.

Download the Certificate

Signing the certificate can take a few seconds. To download the certificate, run the following query:

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

The response will contain the certificate in PEM format with escaped newline characters. If not retry in a couple of seconds.

Save the certificate to a file replacing escaped newline characters with actual newlines.

You can achieve this by running the following command:

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

Download the Issuer's CA Certificate

In order to connect to the MQTT API, you need the CA certificate of the issuer. You can download the CA certificate by running the following query:

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