Securely Connect Your Application with HTTPS

Connect your application with HTTPS

Get your application ThingPark Connected using ThingPark Tunnel Interface

ThingPark offers multiple options to connect to IoT applications: if you chose HTTPS as the protocol to retrieve the data of your devices, this guide is for you!

In this page, we will see point by point how to connect ThingPark to your application using HTTPS and how to handle uplinks and downlinks messages.

Connect ThingPark to your MQTT server

To create an HTTPS connection with your application, go to the Application menu on ThingPark admin console, click on Create and select HTTPS – Generic Application. To complete the creation of the connection, complete the form with the required information and Save.

Name:
Friendly Name to Identify your application on ThingPark.
Example: My_Application

URL:
URL of the application server where your device data will be sent. On ThingPark Community, it must be an HTTPS URL.

Content Type:
3 possibilities: JSON, JSON untyped and XML. JSON is the recommended option, unless your application does not support it.

Tunnel Interface Authentication Key:
This key is automatically generated by ThingPark and is used to secure communications between ThingPark and your application. Save it NOW as this key can not be retrieved at a later stage – a new one can be generated though.

Additional information:
Any detail you want to add to your application that you want to remember. This field is also optional.

Receive uplink messages

Route sensor’s data to your application

Now that your ThingPark application is created and that you have linked it to your broker and server, you need to link your device to your application.
In order to do that:

Go to ThingPark Community in the category “Devices”>“Create” to create your device on ThingPark. Here is a link to a tutorial on how to create a device on ThingPark.
Once it is created, find it in the device list and click on it.

Click on “ADD AN APPLICATION” and select your newly created HTTPS application.

Do not forget to confirm your choice to save it.

NS -> AS HTTP POST

In case of uplink messages (NS to AS) – beyond the information of the XML/JSON message bodies – the NS provides further data as query parameters. This is represented by the following curl command.

curl \ -X POST \ -H "Content-type:application/json" \ -d '{ "DevEUI_uplink": { ... "DevEUI": "000000000F1D8693", "FPort": "2", "FCntUp": "7011", "payload_hex": "0027bd00", "CustomerID": "100000507" ... } }' \ "?LrnDevEui=000000000F1D8693&LrnFPort=2&LrnInfos=UPHTTP_LAB_LORA&AS_ID=app1.sample.com&Time=2016-01-11T14%3A11%3A11.333%2B02%3A00&Token=fd0b0b00464aa798a59282d64eaa70813e33bff87682880db49638569d096aad"

Please note that Thinkpark does not use curl for sending POST messages. The above code snippet is used only for demonstration purpose. The information provided as query parameters can be used to verify the integrity of the message body. This will be explained later under the “Securing the HTTP connection” title. If you want to set up a “quick and dirty” demo environment without security, you can ignore query parameters.

Send downlink messages

AS -> NS HTTP POST

A typical AS to NS message is a Downlink Frame Request message that can be sent by the following curl command.

curl \ -X POST \ -H "Content-type:application/x-www-form-urlencoded" \ "?DevEUI=000000000F1D8693&FPort=1&Payload=00&AS_ID=app1.sample.com&Time=2016-01-11T14%3A28%3A00.333%2B02%3A00&Token=ea8f31d2299cbece8e180a3012766c4df15fe3cf2e142d9fdf4035b5894ec886"

All parameters that are supposed to be part of the message body are provided as query parameters. This is optional. Using query parameters instead of JSON message body would just makes a bit easier to write the curl command in a command line interface.

Securing the HTTP connection

HTTPS

The obvious way of securing a HTTP REST API is utilizing the PKI infrastructure and accessing the AS via HTTPS. HTTPS enabled web sites require a certificate validated by a CA that is part of the PKI infrastructure. If your AS does not have a certificate yet, you can get one for free from Let’s Encrypt.

Checking the integrity of messages received from the NS

Utilizing HTTPS and the PKI infrastructure for uplink messages will just secure the identity of the AS. This is not enough. We also need a way to secure the identity of the NS. The AS has to be able to check if the received message was really sent by the NS and not by someone else.

For that the NS generates a unique Token for every uplink message and sends it as a query parameter like it was illustrated by the above presented curl command.

Once the AS receives a new message it has to recalculate the token and compare it with the one received as a query parameter. If the 2 tokens are the same, the message integrity is correct, otherwise the AS has to drop the message.

The Token Verification Procedure is as follows:

The NS sends the following message to the AS

The AS cuts out the queryParameters subsring from the original query string of the http request without the Token

queryParameters = "LrnDevEui=000000000F1D8693&LrnFPort=2&LrnInfos=UPHTTP_LAB_LORA&AS_ID=app1.sample.com&Time=2016-01-11T14%3A11%3A11.333%2B02%3A00"

The AS builds the bodyElements string as the concatenation – without separator – of the following values taken from the http request body:

bodyElements = CustomerID + DevEUI + FPort + FCntUp + payload_hex

The AS re-computes the Token as:

Token = SHA-256(bodyElements + queryParameters + AsKey)
Where: AsKey is the 128 bits pre-shared Tunnel Interface Authentication Key (lower case hexadecimal string representation) between the AS and the NS as defined in the Generic Application configuration.

The AS compares the calculated Token with the received token (in the query string). If the two are not the same the AS drops the uplink frame.

Message Types

ThingPark Network Server (tpNS) sends/receives the following types of messages to/from the application server (AS). Regardless of the applied integration option (http, mqtt, etc.) the message bodies are always text documents in either JSON or XML format.

Uplink Frame Report

Direction: tpNS→AS
Uplink Frame Reports include information about standard LoRaWAN® Data Uplink messages including the Payload, FPort, and RF parameters.
Message body examples: uplink_frame.xml, uplink_frame.json

Notification Report

Direction: tpNS→AS
Notification Reports notify the AS about “Device Reset” event, “Successful Join Procedure” event and “Battery status”.
Message body examples: notification_report.xml, notification_report.json

Location Report

Direction: tpNS→AS
In case Network Geo-localisation Service is active, ThingPark sends location reports to the AS.
Message body examples: location_report.xml, location_report.json

Downlink Frame Request

Direction: AS→tpNS
Downlink Frame Requests are sent by the AS to the NS to schedule a downlink message on the NS. The NS will enqueue the message and send it as soon as all earlier messages in the queue have been sent and the device opened an RX window.
Message body examples: downlink_frame.xml, downlink_frame.json

Downlink Frames Sent Report

Direction: tpNS→AS
A Downlink Frame Sent Report notifies the AS about the event that the Network Server has sent a scheduled downlink message to a device. Please note that this notification does not necessarily mean that the device has successfully received the downlink message.
Message body examples: downlink_frame_sent_report.xml, downlink_frame_sent_report.json

Additional resources

For more parameters to put in your queries, you can check the following document: List of parameters

Learn about LoRaWAN®

What is LoRaWAN®?

Learn about Actility and ThingPark

Learn about Actility and ThingPark

Build your first end-to-end use case

Build your first end-to-end use case

Application provider

Application provider

Students and Academicians

Students and Academicians

Device maker

Device maker

System integrator

Solutions Partner

Hands on Labs

Application provider

Application provider

Students and Academicians

Students and Academicians

Device maker

Device maker

System integrator

Solutions Partner

Hands on Labs

Connect your application with HTTPS

Connect ThingPark to your MQTT server

Receive uplink messages

Send downlink messages

Securing the HTTP connection

Message Types

Additional resources

ThingPark Community

Journey

Actility Websites

About