Managing CA Certificates using MindConnect MQTT API - Developer Documentation
Skip to content

Managing CA Certificates using MindConnect MQTT API

Overview

MQTT agents which want to connect with the Insights Hub environment need to authenticate themselves by a unique certificate identity.

You can upload up to two X.509 based public certificates to Insights Hub. The MQTT agent needs to authenticate with an agent certificate.

Prerequisites

  • OpenSSL: You will need to create certificates for backend configuration and device authentication. OpenSSL is the tool used in this document to accomplish those tasks. You may use some other tool as well. Commands in this document are tested with OpenSSL v1.1.1k.

  • Insights Hub environment: You need a Insights Hub environment. Within this document, parameter $TENANT is the name of your Insights Hub environment.

  • Gawk: Certificate content as JSON string, you need to escape newline characters in your certificate file. You can print the escaped version.

Abbreviations

  • MDSP: Insights Hub
  • CA: Certificate authority
  • CN: Common Name

Registering CA Certificate

The MindConnect MQTT API is currently available in regions EU1 and EU2.

  1. Create Tenant CA certificate
  2. Upload Tenant CA certificate
  3. Tenant CA Certificate verification

Create Tenant CA certificate

You need to create a CA certificate and upload it to MDSP to enable agent onboarding. This certificate (and its private key) should be used for issuing agent certificates.

Info

Intermediate certificates are not supported during the agent onboarding process.
The Common Name (CN) for CA certificate can be of any value, but it is recommended to select a name that is easy to recognize, like a name that contains your tenant id.

Prerequisite: Update following fields with appropriate values before using the given sample in this section:

  • <tenant> : Insights Hub environment
  • <countryCode> : ISO 3166-1 alpha-2 Country Code
  • <city> : Abbreviation of the city
  • <organization> : Abbreviation of the organization

Successful execution of the following list of commands results in creation of private key first. Then it creates a new, self-signed, X.509 certificate valid for 3650 days with CN set to tenant name using the private key.

LINUX:

```cmd
export TENANT=<tenant>
export COUNTRY_CODE=<countryCode>
export CITY=<city>
export ORGANIZATION=<organization>
```

openssl genrsa -out $TENANT.key 2048

openssl req -x509 -new -nodes -key $TENANT.key -sha256 -days 3650 -out $TENANT.pem -subj "/C=$COUNTRY_CODE/ST=$CITY/O=$ORGANIZATION/OU=IT/CN=$TENANT"

WINDOWS:

  • Download the OpenSSL installer.

  • Run the OpenSSL installer to install: Execute the downloaded installer file and install the OpenSSL on the Windows machine.

  • Open command prompt.

  • Set environment variable:

set OPENSSL_CONF=C:\Program Files\OpenSSL-Win64\bin\openssl.cfg
set Path= C:\Program Files\OpenSSL-Win64\bin

  • Run the following commands:
    ```cmd
    set TENANT=<tenant>
    set COUNTRY_CODE=<countryCode>
    set CITY=<city>
    set ORGANIZATION=<organization>
    ```
    

openssl genrsa -out %TENANT%.key 2048

openssl req -x509 -new -nodes -key %TENANT%.key -sha256 -days 3650 -out %TENANT%.pem -subj "/C=%COUNTRY_CODE%/ST=%CITY%/O=%ORGANIZATION%/OU=IT/CN=%TENANT%"

Warning

The generated private key is confidential to your tenant. You must secure it. Please refer to your own corporate policies about generating and securing your key material.

Upload Tenant CA certificate

The created certificate ($TENANT.pem) needs to be uploaded to Insights Hub via MindConnect MQTT API. You need to make a POST request to caCertificates with the following JSON payload:

Info

You need to give a name to your certificate with the name attribute and provide the content of your certificate with the caCartificate attribute of the JSON body. Notice that, to pass certificate content as JSON string, you need to escape newline characters in your certificate file. You can print the escaped version with the following command:
LINUX:
awk -v ORS='\\n' '1' $TENANT.pem
WINDOWS:
awk -v ORS='\\n' '1' %TENANT%.pem
Sample output:
-----BEGIN CERTIFICATE-----\nMIICnjCCAYYCCQCCzHoCkvdWIDANBgkqhkiG9w0BAQsFADARMQ8wDQYDVQQDDAZj\nb25uYXowHhcNMjEwNTMxMTMwMTEwWhcNMjQwMzIwMTMwMTEwWjARMQ8wDQYDVQQD\nDAZ..GV2kDKM7Wg9+uzYgeU8wDyvXVFaozWSsW9EZ\nPx8=\n-----END CERTIFICATE-----\n

Prerequisite:

  • <TOKEN> header parameter needs to be replaced by an actual token.
  • name payload parameter needs to be replaced by an actual name.
  • caCertificate payload parameter needs to be replaced by awk command response.

Sample HTTP request body:

```json
POST/api/mindconnectmqtt/v3/caCertificates HTTP/1.1
Host: gateway.eu1.mindsphere.io
Content-Type: application/json
Authorization: Bearer <TOKEN>
{
"name":"SampleCACertificate",
"caCertificate":"CopyPasteAwkCommandResponse"
}
```

Sample response:

```json
{
"id":"60b5fccd440b1513205d80ba",
"name":" SampleCACertificate",
"expiration":"2031-05-30T09:22:55.000Z",
"commonName":"tenant"
}
```

The CA certificate is uploaded but not verified yet. It needs to be verified before it can be used for onboarding.

Tenant CA Certificate verification

For Insights Hub to make sure that the certificate uploader also possesses the corresponding private key, the user needs to prove possession of the private key by issuing a verification certificate with a CN provided by Insights Hub using the private key.

As the first step, the user needs to get the registration code to use as the CN of the verification certificate. Registration code needs to be fetched per CA certificate and is available at api/mindconnectmqtt /v3/caCertificates/<id>/registrationCode endpoint. Sample request and response are given below:

Info

<id> parameter needs to be replaced by an actual id which is returned inside the response of the upload CA Certificate step.
<TOKEN> header parameter needs to be replaced by an actual token.

Sample HTTP request body:

```cmd
GET /api/mindconnectmqtt/v3/<id>/registrationCode HTTP/1.1
Host: gateway.eu1.mindsphere.io
Authorization: Bearer <TOKEN>
```

Sample response:

```json
{
"registrationCode":"registrationCode"
}
```

Now, create a temporary private key (line 1), and use it to create a self-signed Certificate Signing Request(CSR) with CN set to the registration code (line 2). Then issue the verification certificate using CSR, CA certificate, and CA private key (line 3):

LINUX:

openssl genrsa -out verificationCert.key 2048

openssl req -new -key verificationCert.key -out verificationCert.csr -subj /CN=$REGISTRATION_CODE

openssl x509 -req -in verificationCert.csr -CA $TENANT.pem -CAkey $TENANT.key -CAcreateserial -out verificationCert.pem -days 7 -sha256

WINDOWS:

openssl genrsa -out verificationCert.key 2048

openssl req -new -key verificationCert.key -out verificationCert.csr -subj /CN=%REGISTRATION_CODE%

openssl x509 -req -in verificationCert.csr -CA %TENANT%.pem -CAkey %TENANT%.key -CAcreateserial -out verificationCert.pem -days 7 -sha256

Now a new certificate is created with the required subject common name and stored in verificationCert.pem.

Contents of the verificationCert.pem file need to be escaped to be used in the JSON payload. You can use the awk command:

LINUX / WINDOWS:

```cmd
awk -v ORS='\\n' '1' verificationCert.pem`
```

Sample output:

`-----BEGIN CERTIFICATE-----\nMIICnjCCAYYCCQCCzHoCkvdWIDANBgkqhkiG9w0BAQsFADARMQ8wDQYDVQQDDAZj\nb25uYXowHhcNMjEwNTMxMTMwMTEwWhcNMjQwMzIwMTMwMTEwWjARMQ8wDQYDVQQD\nDAZ..GV2kDKM7Wg9+uzYgeU8wDyvXVFaozWSsW9EZ\nPx8=\n-----END CERTIFICATE-----\n`

Info

<TOKEN> header parameter needs to be replaced by an actual token.
<id> parameter needs to be replaced by an actual id which returned inside the response of the upload CA Certificate step.
verificationCertificate payload parameter needs to be replaced by awk command response.

Sample HTTP request body:

```json
POST/api/mindconnectmqtt/v3/caCertificates/<id>/verify HTTP/1.1
Host: gateway.eu1.mindsphere.io
Authorization: Bearer <TOKEN>
Content-Type: application/json
{
"verificationCertificate":"CopyPasteAwkCommandResponse"
}
```

After a successful execution, the certificate is marked as verified.

Sample response:

```json
{
"id":"60b61664946b9d187cd2b7c9",
"name":"SampleCACertificate",
"expiration":"2031-05-30T11:10:49.000Z",
"commonName":"tenant",
"isVerified":true
}
```

Last update: January 15, 2024

Except where otherwise noted, content on this site is licensed under the Development License Agreement.