LogoLogo
  • KPN THINGS USER GUIDE
    • Introduction
    • Getting started
      • Registration and setup
      • Device simulator app
      • Connect devices
        • SIM cards
        • Supported devices and KPN Devices
        • SODAQ R412M
        • Smartrak
        • Marvin development board
        • LoPy5
        • Arduino MKR WAN 1300/1310
        • Arduin MKR NB 1500
    • All videos
    • Tutorials
      • Configure a flow
      • Connect a HTTPs destination
      • Create a simple IoT web applicationPage
      • Send instruction to LoRa DevicePage
      • Send your data to Azure SQL
      • Technical overview
        • Management data model
        • Uplink communication
        • Downlink communication
        • Location data
      • Accounts and projects
        • Customer accounts and users
        • Projects
        • Customer management
        • Cost overview and contract
    • Frequently asked
      • Multi Factor Authentication
  • GENERAL FUNCTIONS
    • Quick reference videos
    • APIs
  • THE PORTAL EXPLAINED
    • Things Manager
      • Devices
        • Bulk operations
      • Data
        • Device data graph
      • Connectivity
        • LoRa connectivity configuration
      • Bulk reports
    • Things Creator
    • Support
      • News
      • Release notes
      • Real-time status
      • Service reports
      • Documents
      • Support tickets
      • Invoices
      • Contact info
    • Shop
  • BUILDING BLOCKS
    • Devices
      • Sensors
        • KPN Conditionsensor CO2 II
        • KPN Conditionsensor CO2 III
        • KPN Conditionsensor CO2 III motionPage 1
        • KPN FillTag I
        • KPN FillTag II
        • 1M2M ED1608
        • Elsys ERS
        • Device Simulator (Mobile Phone app)
        • Generic Device (Internet connected)
        • Generic LoRa device (preset connectivity)
        • Generic LoRa device (programmable)
        • Generic M2M device
        • Generic M2M device (with Internet connection)
      • Trackers
        • KPN Global Tracker Autonomous
        • KPN Global Tracker Wired
        • KPN LocationTag I
        • KPN LocationTag II
        • KPN LocationTag II v2
        • KPN LocationTag II v2 Expert Mode
        • KPN LocationTag II v3
        • KPN LocationTag III (with GPS)
        • KPN LocationTag III (without GPS)
        • KPN LocationTag III v2
        • KPN LocationTag III v2 Buffer
        • KPN LocationTag III v3
        • KPN LocationTag III v4
        • KPN LocationTag V
        • KPN LocationTag VI
        • KPN LocationTag WS
        • Streamline LoRa
        • Streamline M2M
        • Viloc
      • Routers
      • Gateways
        • KPN FSK Basestation
      • Device SDK
    • Connectivity
      • Connecting LoRa devices
        • LoRa connectivity configuration
      • Connecting M2M devices
      • Connecting Internet devices
      • Connecting MQTT Devices
    • Data Processing
      • ThingsML and SenML
        • ThingsML
        • SenML
          • Understanding and Interpreting SenML Data
          • Changes in KPN SenML
      • Device Twin
      • Decoders and encoders
        • Common measurements list
        • Decoder migrations
        • DIY Decoder
          • DIY decoder scripts
      • Merger
      • Device data
      • Devices
    • Destinations
      • HTTPS destination
      • MQTT broker
      • Cumulocity IoT Platform
      • Azure Event Hubs
      • Azure IoT Hub
      • Test Endpoint
      • ThingsBoard
      • Datacake
      • AWS Lambda
      • Google Cloud Run functions
  • IOT LINE UP
    • Freemium
      • Test SIM cards
    • Explorer
    • Modular
    • Tailored
    • Terms and Conditions
Powered by GitBook

© 2024 KPN - All rights reserved.

On this page
  • Connect an HTTPS destination
  • The request
  • Things-Message-Token
  • Request body
  • TLS/SSL Requirements
  • Trusted certificate
  • Up to date TLS version
  • Safe cipher suite
  • Example HTTPS request
  • Setup test endpoint

Was this helpful?

Export as PDF
  1. BUILDING BLOCKS
  2. Destinations

HTTPS destination

Forward your device data to your server through an HTTPS request

Connecting an HTTPS destination enables you to forward IoT data from KPN Things to your server through an HTTPS connection.

Connect an HTTPS destination

The following parameters are available to connect an HTTPS destination:

Parameter

Description

Example value

name

*

The name of the destination

My Server

description

Description of the destination

Endpoint of my server

url

*

HTTPS URL of your destination. Should

start with https://, no custom ports

are supported (only default 443), query

parameters are allowed

https://example.com/ thingsdata

httpMethod

*

The HTTP method to use (GET or POST)

POST

additional Headers

Object of static key-value pairs.

Caution! Do not put white space characters in your header name!

{

"header1":"value1",

"header2": "value2"

}

authentication method

  • None - no authentication

  • Basic Authentication - Authentication via a user name and password

  • Bearer token - Authentication using a cryptic string as bearer token

  • X-API-key - Authentication using an API-key

expected ResponseCode

The HTTP response code to be expected after the HTTPS request is done. When a response code not equal to 2XX is returned, it is assumed that the delivery was not succesful. At most three delivery attempts are done with an increasing timeout before the data is discarded.

200

sharedSecret

*†

Shared secret should be at least 32 characters long and should contain at least: - 1 uppercase character - 1 lowercase character - 1 number - 1 special character (#?!@$%^&(){}:.,/+*;)

Generate your own by hitting 32 random keys

*) required value †) secret value, can only be written

The request

  • {xx} is a destination parameter

  • <xx> is a variable filled by the system for each request

{method} {url(path)} HTTP/1.1
Host: {url(domain)}
Things-Plug-UUID: <plugUUID>
Things-Message-Token: <token>
Content-type: application/json
{additional-headers}

<senML>
  • plugUUID is the unique identifier of the destination connection that allows you to lookup the shared secret in your own database that should be used to check the Things-Message-Token

  • token must be used to verify the authenticity of the request data. It is a SHA-256 hash calculated over the SenML body in the request and a shared secret unique for this destination. Since only KPN Things and you know this secret, the authenticity of the message is verified.

  • senML is the device data

Things-Message-Token

It is very important to implement the token check before accepting the sent data in your application.

The HTTPS request contains a Things-Message-Tokenheader which allows you to verify the origin of the request. The token is a hash, calculated as following:

token = sha256({senMLBody}{sharedSecret})

Where {senMLBody} is the body of the request, and sharedSecret is the password set when adding the destination. The shared secret should at least be 30 characters long.

You must generate and fill in your own shared secret when adding the destination. Since the token is stored securely in our system, it is not possible to retrieve the shared secret from the destination configuration after creation. It is only possible to renew the secret.

Request body

The body of the HTTPS request will contain the SenML object in JSON formatting. It will contain the device identifier and the measurement data. Learn more on the SenML object here:

TLS/SSL Requirements

Trusted certificate

Up to date TLS version

Your server should use TLSv1.2 or higher. Older protocols are not supported because they are not considered safe.

Safe cipher suite

Your server should support at least one of the cipher suites stated below. The cipher suites in this table are considered safe.

Standard code

Standard + SSLLabs cipher suite name

0x16B9

TLS_CECPQ1_RSA_WITH_AES_256_GCM_SHA384

0x16B7

TLS_CECPQ1_RSA_WITH_CHACHA20_POLY1305_SHA256

0x67

TLS_DHE_RSA_WITH_AES_128_CBC_SHA256

0x6b

TLS_DHE_RSA_WITH_AES_256_CBC_SHA256

0xc09e

TLS_DHE_RSA_WITH_AES_128_CCM

0xc09f

TLS_DHE_RSA_WITH_AES_256_CCM

0xc0a2

TLS_DHE_RSA_WITH_AES_128_CCM_8

0xc0a3

TLS_DHE_RSA_WITH_AES_256_CCM_8

0x9e

TLS_DHE_RSA_WITH_AES_128_GCM_SHA256

0x9f

TLS_DHE_RSA_WITH_AES_256_GCM_SHA384

0xbe

TLS_DHE_RSA_WITH_CAMELLIA_128_CBC_SHA256

0xc4

TLS_DHE_RSA_WITH_CAMELLIA_256_CBC_SHA256

0xccaa

OLD_TLS_DHE_RSA_WITH_CHACHA20_POLY1305_SHA256

0xc027

TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

0xc028

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384

0xc02f

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

0xc030

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

0xc076

TLS_ECDHE_RSA_WITH_CAMELLIA_128_CBC_SHA256

0xc077

TLS_ECDHE_RSA_WITH_CAMELLIA_256_CBC_SHA384

0xcc13

OLD_TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

0xcca8

TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256

0x16BA

TLS_CECPQ1_ECDSA_WITH_AES_256_GCM_SHA384

0x16B8

TLS_CECPQ1_ECDSA_WITH_CHACHA20_POLY1305_SHA256

0xc023

TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256

0xc024

TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384

0xc0ac

TLS_ECDHE_ECDSA_WITH_AES_128_CCM

0xc0ad

TLS_ECDHE_ECDSA_WITH_AES_256_CCM

0xc0ae

TLS_ECDHE_ECDSA_WITH_AES_128_CCM_8

0xc0af

TLS_ECDHE_ECDSA_WITH_AES_256_CCM_8

0xc02b

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

0xc02c

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

0xc072

TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_CBC_SHA256

0xc073

TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_CBC_SHA384

0xcc14

OLD_TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

0xcca9

TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256

0xC086

TLS_ECDHE_ECDSA_WITH_CAMELLIA_128_GCM_SHA256

0xC087

TLS_ECDHE_ECDSA_WITH_CAMELLIA_256_GCM_SHA384

0xC07C

TLS_DHE_RSA_WITH_CAMELLIA_128_GCM_SHA256

0xC07D

TLS_DHE_RSA_WITH_CAMELLIA_256_GCM_SHA384

0xC08A

TLS_ECDHE_RSA_WITH_CAMELLIA_128_GCM_SHA256

0xC08B

TLS_ECDHE_RSA_WITH_CAMELLIA_256_GCM_SHA384

Example HTTPS request

Variable

Value

url

https://www.example.com/thingsdata

httpMethod

POST

additionalHeaders

{

"Test-header": "Hello world"

}

sharedSecret

C03fajLBWj$nbvOnQlV9N49zVFEobV# This is an example value! Don't use it for your own destination!

Properties

Value

plugUUID

fbc063cb-4dd4-41b3-917a-e2d1ea907f75

exampleHTTPS
POST /thingsdata HTTP/1.1
Host: www.example.com
Things-Plug-UUID: fbc063cb-4dd4-41b3-917a-e2d1ea907f75
Things-Message-Token: a7939780a487b036d5f41edf29ee3e087b14c121302e321326865255de8ea9c9
Content-type: application/json
Content-length: 106
Test-header: Hello world

[{"bn":"urn:dev:DEVEUI:0000000000000000:","bt":1.58565075E9},{"n":"temperature","v":21.22,"u":"Celsius"}]

Setup test endpoint

If you do not have an HTTPS endpoint in your back pocket, you could use services like webhook.site to setup your first endpoint to receive your IoT data.

When you open the webhook.site website you will get a unique URL that you can use as endpoint for your HTTPS destination:

PreviousDestinationsNextMQTT broker

Last updated 3 months ago

Was this helpful?

With the shared secret your destination can verify that Things has sent the data and not someone else, because with the shared secret a unique is calculated for each message.

KPN Things does not facilitate unsafe connections. For the definition of a safe connection we follow the . There are three aspects you need to take into account when configuring TLS/SSL on the endpoint where you want to deliver your IoT Data.

We do not support self-signed certificates. Your HTTPS certificate should be signed by a root certificate authority (CA) that is trusted by the default Java trust store. You can use the to check if your certificate is trusted by the Java trust store:

SenML
KPN Security Policy
SSL Server Test from Qualys
Things-Message-Token
LogoWebhook.site - Test, process and transform emails and HTTP requests
The result of the SSL Server Test indicating the certificate is trusted by Java
Use the red bordered value as URL for your HTTPS destination