Skip to content

Managing CA Certificates using MindConnect MQTT API

Overview

MQTT agents which want to connect with the MindSphere tenant need to authenticate themselves by a unique certificate identity.

You can upload up to two X.509 based public certificates to MindSphere. 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.

  • MindSphere Tenant: You need a MindSphere tenant. Within this document, parameter $TENANT is the name of your MindSphere tenant.

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

Abbreviations

  • MDSP: MindSphere
  • 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

    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> : MindSphere tenant
    • <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:

    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:

      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.

  2. Upload Tenant CA certificate to MindSphere

    The created certificate ($TENANT.pem) needs to be uploaded to MindSphere 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:

    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:

    {
    "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.

  3. Tenant CA Certificate verification

    For MindSphere 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 MindSphere 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:

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

    Sample response:

    {
    "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:

    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:

    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:

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

Any questions left?

Ask the community


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


Last update: August 3, 2022