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.
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):
Navigate to httpbin.org, locate the lock symbol in the address field, and click on
Connection is secure
.Click on
Certificate is valid
.
- Go to
Details
in the pop-up, select the top level in the certificate hierarchy, and click export. This will download the CA certificate.
Open the file in a text editor and copy the contents to the clipboard.
Upload the
provision.ino
sketch from the examples folder of the AVR-IoT Cellular Library and open up a serial terminal.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.
- Choose to provision
To test the setup, modify the
https.ino
example sketch by setting the domain tohttpbin.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.
- Windows
- macOS
- Linux
Powershell or Command Prompt
Run Win + R, enter powershell
followed by Open
The Terminal App
You can find it under Applications/Terminal
In Ubuntu, you can open the Gnome Terminal
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 usemar
. 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.
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.
- Choose to provision MQTT.
- Select
Azure IoT Hub
. - Select which CA to use. If unsure, check which CA is used in your Azure IoT Hub.
- 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. - In your IoT Hub, select devices and click
Add Device
.
- Input the device ID printed in the serial terminal. It should be on the following form:
snXXXXXXXXXXXXXXXX
. - 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.
- Choose to provision MQTT.
- When asked which service to use, choose
Other
. - Choose
MQTT TLS unauthenticated or with username and password
. - Choose TLS version. The default of TLS 1.2 is sufficient for this example.
- Leave the ciphers to utilize blank so that the ciphers will be detected automatically.
- Choose to load a custom CA by inputting
y
and pressing enter. - Head to test.mosquitto.org and download the certificate authority file in PEM format.
- 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.
- Choose to provision MQTT.
- When asked which service to use, choose
Other
. - Choose
MQTT TLS with public and private key pair certificates
. - Choose TLS version. The default of TLS 1.2 is sufficient for this example.
- Leave the ciphers to utilize blank so that the ciphers will be detected automatically.
- Choose to load a custom CA by inputting
y
and pressing enter. - Head to test.mosquitto.org and download the certificate authority file in PEM format.
- Paste the contents of the file into the serial terminal and press enter.
- Choose
y
(yes) for using the ECC and press enter. - 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.
- 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.
- Choose to provision MQTT.
- When asked which service to use, choose
Other
. - Choose
MQTT TLS with public and private key pair certificates
. - Choose TLS version. The default of TLS 1.2 is sufficient for this example.
- Leave the ciphers to utilize blank so that the ciphers will be detected automatically.
- Choose to load a custom CA by inputting
y
and pressing enter. - Head to test.mosquitto.org and download the certificate authority file in PEM format.
- Paste the contents of the file into the serial terminal and press enter.
- Choose
n
(no) for using the ECC and press enter. - 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
. - Open the downloaded certificate file in a text editor and paste the contents into the serial text interface.
- 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
.