Skip to main content

Provisioning for HTTPS and MQTTS

Provisioning in IoT refers to pairing or preparing the device for a cloud service with accompanying permissions (i.e. connecting the board to your AWS account). A provisioning is needed to use HTTPS and MQTTS. The following user guide describes how to set up HTTPS with a certificate authority (CA) and MQTTS with authentication and a CA.

Provisioning HTTPS​

To provision the board for HTTPS, program the board with the provision.ino example sketch. Thereafter, open a serial terminal. A text-based interface will be presented.

Choose to provision HTTP in the text-based interface and follow the steps outlined. The kit comes bundled with a default CA, but there is also functionality for loading a custom CA certificate.

tip

The board can automatically detect which ciphers to use for TLS. If you're unsure of which cipher to use, please leave this field blank.

Using HTTPS with a custom CA​

For httpbin.org, the CA can be found by for example utilizing a web browser. In Chrome, the procedure is as follows (which shouldn't deviate much from other web browers):

  1. Navigate to httpbin.org, locate the lock symbol in the address field, and click on Connection is secure.

  2. Click on Certificate is valid.

  1. Go to Details in the pop-up, select the top level in the certificate hierarchy, and click export. This will download the CA certificate.

  1. Open the file in a text editor and copy the contents to the clipboard.

  2. Upload the provision.ino sketch from the examples folder of the AVR-IoT Cellular Library and open up a serial terminal.

  3. In the serial terminal, do the following:

    • Choose to provision HTTP.
    • Choose which TLS version to use. The default one of TLS 1.2 is fine for this example.
    • Choose y (yes) when asked about loading a custom CA.
    • Paste the contents of the certificate file into the serial terminal. The provisioning is now done.

  4. To test the setup, modify the https.ino example sketch by setting the domain to httpbin.org and performing e.g. a GET request to /, as shown in the following code snippet:

#include <Arduino.h>
#include <http_client.h>
#include <led_ctrl.h>
#include <log.h>
#include <lte.h>

#define DOMAIN "httpbin.org"

void setup() {
    LedCtrl.begin();
    LedCtrl.startupCycle();

    Log.begin(115200);
    Log.info(F("Starting HTTPS example"));

    // Start modem and connect to the operator
    if (!Lte.begin()) {
        Log.error(F("Failed to connect to the operator"));
        return;
    }

    Log.infof(F("Connected to operator: %s\r\n"), Lte.getOperator().c_str());

    // --- HTTPS ---
    Log.info(F("---- Testing HTTPS ----"));

    if (!HttpClient.configure(DOMAIN, 443, true)) {
        Log.info(F("Failed to configure https client\r\n"));
        return;
    }

    Log.info(F("Configured to HTTPS"));

    HttpResponse response = HttpClient.get("/get");
    Log.infof(F("GET - HTTP status code: %u, data size: %u\r\n"),
              response.status_code,
              response.data_size);

    response = HttpClient.post("/post", "{\"hello\": \"world\"}");
    Log.infof(F("POST - HTTP status code: %u, data size: %u\r\n"),
              response.status_code,
              response.data_size);

    // Add some extra bytes for termination
    String body = HttpClient.readBody(response.data_size + 16);

    if (body != "") {
        Log.infof(F("Body: %s\r\n"), body.c_str());
    }
}

void loop() {}

Provisioning MQTTS​

The board can be provisioned for AWS, Azure IoT Hub and custom brokers.

Provisioning for AWS​

1. Installing the IoT Provisioning Tool​

Download: IoT Provisioning Tool

The IoT Provisioning Tool from Microchip is a command-line interface that provisions any PIC & AVR IoT board to a supported cloud service. Download the tool, extract it and open the extracted folder in a terminal.

Which terminal to use?

Powershell or Command Prompt

Run Win + R, enter powershell followed by Open

2. Installing & Configuring the AWS CLI​

Download: AWS Command Line Interface

In order for the provisioning tool to upload device certificates to AWS, the AWS Command Line Interface must be installed and configured. Follow the official user guide from Amazon.

3. Running the Tool​

The provisioning tool has many different variables and settings that can be applied, but the default setting works for most use cases. Two of the most important settings are

  • -c {aws}: Sets which cloud to use. Keep in mind that the provided cloud must be supported by the board, which at the time of writing is only AWS for the AVR-IoT Cellular boards.
  • -m {sandbox,custom,jitr,mar}: Sets the provisioning method. Most users will use mar. For a more detailed explanation of these options, see the A More Thorough Look into the Provisioning Process article for the AVR-IoT WiFi boards.

The tool automatically detects any IoT boards connected to the computer.

Provision the Board with AWS using MAR: ./iotprovision-bin -m mar -c aws

Now the provisioning is complete and the board is ready for being used with your AWS account.

Factory Reset (if needed)

If there is need to reset the board back to the factory settings with the sandbox (landing page) application, this can be done with running the provisioning tool with the -m flag set to sandbox: ./iotprovision-bin -m sandbox -c aws

Provisioning for Azure IoT Hub​

In order to provision for Azure IoT Hub, program the board with the provision.ino example sketch. Thereafter, open the serial terminal and a text-based interface will be presented.

  1. Choose to provision MQTT.
  2. Select Azure IoT Hub.
  3. Select which CA to use. If unsure, check which CA is used in your Azure IoT Hub.
  4. Enter your Azure IoT Hub name, it sould be on the form <my iot hub>.azure-devices.net. The provisioning is now complete on the device side.
  5. In your IoT Hub, select devices and click Add Device.
  1. Input the device ID printed in the serial terminal. It should be on the following form: snXXXXXXXXXXXXXXXX.
  2. Select X.509 Self-Signed and paste in the thumbprint from the serial terminal as primary and secondary thumbprint.

In order to test the setup, program the mqtt_azure.ino example sketch to the board. Verify that the MQTT messages arrive by opening an Azure cloud shell and inputting the command az iot hub monitor-events -n <your iot hub name>.

Provisioning for custom brokers​

In order to provision for custom brokers, program the board with the provision.ino example sketch. Thereafter, open the serial terminal and a text-based interface will be presented. For MQTTS with custom brokers, there is a range of choices:

  • MQTTS unauthenticated (but still with TLS)
  • MQTTS with username and password
  • MQTTS with public-private key pairs

In the following examples with a custom broker, test.mosquitto.org is used, but the methods should be applicable to other MQTT brokers as well.

Provisioning for test.mosquitto.org unauthenticated (but with TLS)​

When MQTTS is provisioned as unauthenticated with TLS, the messages will be encrypted, but no authentication is required when connecting to the broker.

  1. Choose to provision MQTT.
  2. When asked which service to use, choose Other.
  3. Choose MQTT TLS unauthenticated or with username and password.
  4. Choose TLS version. The default of TLS 1.2 is sufficient for this example.
  5. Leave the ciphers to utilize blank so that the ciphers will be detected automatically.
  6. Choose to load a custom CA by inputting y and pressing enter.
  7. Head to test.mosquitto.org and download the certificate authority file in PEM format.
  8. Paste the contents of the file into the serial terminal and press enter. The provisioning is now done.

In order to test the setup, open up the mqtt_custom_broker.ino example sketch, change MQTT_PORT to 8883 and MQTT_USE_TLS to true and program the sketch to the board.

Provisioning for test.mosquitto.org with username and password​

The setup for provisioning against test.mosquitto.org with username and password is the same as provisioning unauthenticated, so the steps outlined in the above example are identical besides which sketch file to utilize. Instead of testing with mqtt_custom_broker.ino, open up mqtt_password_authentication.ino and change MQTT_PORT to 8885 and MQTT_USE_TLS to true.

Provisioning for test.mosquitto.org with public-private key pairs and the ATECC chip​

The AVR-IoT Cellular Mini board comes bundled with an ATECC chip. The ATECC is a cryptography chip that provides more security than simply storing the certificates in non-volatile memory of the GM02S modem. Both methods are however possible, but using the ATECC is recommended.

  1. Choose to provision MQTT.
  2. When asked which service to use, choose Other.
  3. Choose MQTT TLS with public and private key pair certificates.
  4. Choose TLS version. The default of TLS 1.2 is sufficient for this example.
  5. Leave the ciphers to utilize blank so that the ciphers will be detected automatically.
  6. Choose to load a custom CA by inputting y and pressing enter.
  7. Head to test.mosquitto.org and download the certificate authority file in PEM format.
  8. Paste the contents of the file into the serial terminal and press enter.
  9. Choose y (yes) for using the ECC and press enter.
  10. Choose y (yes) for issuing a certificate signing request (CSR). Now a CSR will be made with the ECC's private key. Follow the steps and provide the country, state and city. Copy the certificate signing request from the serial text interface and paste the contents into the text field on test.mosquitto.org (as outlined in the image below) and click submit.
  1. A certificate file should be downloaded. Open up this file with a text editor and paste the contents into the serial text interface. The provisioning is now done.

Test the setup by running the mqtt_custom_broker.ino example sketch and change MQTT_PORT to 8884, MQTT_USE_TLS to true and MQTT_USE_ECC to true.

Provisioning for test.mosquitto.org with public-private key pairs stored in non-volatile memory of the GM02S modem.​

  1. Choose to provision MQTT.
  2. When asked which service to use, choose Other.
  3. Choose MQTT TLS with public and private key pair certificates.
  4. Choose TLS version. The default of TLS 1.2 is sufficient for this example.
  5. Leave the ciphers to utilize blank so that the ciphers will be detected automatically.
  6. Choose to load a custom CA by inputting y and pressing enter.
  7. Head to test.mosquitto.org and download the certificate authority file in PEM format.
  8. Paste the contents of the file into the serial terminal and press enter.
  9. Choose n (no) for using the ECC and press enter.
  10. Head to test.mosquitto.org/ssl and follow the steps to create a private key and a CSR with OpenSSL. Press submit when the CSR is pasted into the text field. If you are using newer versions of OpenSSL, remember to pass the traditional flag when creating the private key: openssl genrsa -out client.key -traditional.
  11. Open the downloaded certificate file in a text editor and paste the contents into the serial text interface.
  12. Paste the contents of the created private key (here named client.key if the exact instructions provided by test.mosquitto.org were followed) into the serial text interface. The provisioning is now done.

Test the setup by running the mqtt_custom_broker.ino example sketch and change MQTT_PORT to 8884, MQTT_USE_TLS to true and make sure that MQTT_USE_ECC is set to false.