KPN Things Developer Manual
↩ All Documentation
Search
⌃K
Links
Comment on page

HTTPS endpoint

Forward your device data to your server through an HTTPS request.
Connecting an HTTPS endpoint enabled you to forward IoT data from KPN Things to your server through an HTTPS connection.

Connect an HTTPS endpoint

The following parameters are available to connect an HTTPS endpoint:
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 endpoint. 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"
}
expected ResponseCode
​
The HTTP response code to be expected after the HTTPS request is done.
200
sharedSecret
*†
With the shared secret your endpoint can verify that Things has sent the data and not someone else, because with the shared secret a unique Things-Message-Token is calculated for each message.
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

KPN Things does not facilitate unsafe connections. For the definition of a safe connection we follow the KPN Security Policy. 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.

Trusted certificate

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 SSL Server Test from Qualys to check if your certificate is trusted by the Java trust store:
The result of the SSL Server Test indicating the certificate is trusted by Java.

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:
Use the red bordered value as URL for your HTTPS destination.
Destinations - Previous
Cumulocity environment
Next - Destinations
MQTT broker
Last modified 3yr ago