Connexion basique

Aperçu

Le réseau central (serveurs LRC) met en œuvre une interface en mode tunnel. C'est une interface simple d'échange de messages entre la plateforme ThingPark qui implémente la couche MAC du réseau (serveurs LRC) et les serveurs d'application.

Une API est disponible :

• Interface de tunnel LoRaWAN®

Types de connexion

Un seul type de connexion est disponible pour l'interface de tunnel :

• HTTPS de base: HTTPS est utilisé pour les rapports du cluster LRC vers le serveur d'application et pour les paquets downlink du serveur d'application vers le cluster LRC. Voir Adding a basic HTTPS connection pour plus de détails.

HTTPS de base

L'interface de tunnel est basée sur HTTPS pour les rapports du cluster LRC vers le serveur d'application et pour les paquets downlink du serveur d'application vers le cluster LRC.

Les URLs de destination des rapports LRC sont définies pour chaque capteur dans la configuration de la connexion. Pour les capteurs LoRaWAN®, le routage basé sur le port peut être activé pour acheminer les Payloads en fonction de leur valeur FPort.

Il existe deux stratégies de routage vers les URLs de destination :

• Séquentiel : tenter le routage dans l'ordre défini des URLs et arrêter le routage vers les URLs suivantes une fois qu'une réponse 2xx est reçue de la dernière URL tentée.
• Par surcharge : les messages sont toujours routés vers toutes les URLs configurées.

Les rapports LRC sont transmis dans des requêtes HTTP/POST contenant des paramètres de requête et un Payload XML ou JSON. Des en-têtes HTTP personnalisés peuvent être définis dans la configuration de la connexion. Lors de la définition, des en-têtes HTTP personnalisés sont inclus dans toutes les requêtes HTTP transmises par le LRC.

La confidentialité des messages est gérée par une connexion HTTPS :

• La session HTTPS des rapports LRC est montée entre le cluster LRC et le serveur d'application.
• La session HTTPS de descente est montée entre le serveur d'application et le proxy HTTP inverse devant le cluster LRC.

Une couche d'authentification sécurise les rapports LRC et les paquets downlink. Le LRC partage une clé d'authentification d'interface de tunnel avec le serveur d'application :

• Le serveur d'application utilise la clé d'authentification d'interface de tunnel pour générer une signature ajoutée aux paquets downlink. Le LRC utilise la signature pour vérifier l'identité et l'autorisation du serveur d'application. Si l'identité ou l'autorisation ne peut être vérifiée, le paquet est abandonné.
• Le LRC utilise la clé d'authentification d'interface de tunnel pour générer une signature ajoutée aux rapports LRC. Le serveur d'application utilise la signature pour vérifier l'identité du LRC. Si l'identité ne peut être vérifiée, le serveur d'application abandonne le paquet.

Quand la clé d'authentification d'interface de tunnel est provisionnée, son entropie est calculée par la plateforme ThingPark à l'aide de l'algorithme de Shannon. Si l'entropie est supérieure ou égale au seuil d'entropie accepté par la plateforme ThingPark, la clé d'authentification d'interface de tunnel est acceptée. Sinon, la clé d'authentification d'interface de tunnel est rejetée.

Notes importantes

Le serveur d'application doit satisfaire aux exigences suivantes concernant la session HTTPS des rapports LRC :

• Le serveur d'application ne doit pas utiliser un certificat TLS auto-signé.
• Le serveur d'application configuré dans l'application ThingPark DOIT avoir des entrées DNS valides, des adresses IP accessibles et des serveurs HTTP opérationnels. Les routes associées à une seule URL de destination doivent être configurées en mode Ordre (également connu sous le nom de Séquentiel).
• HTTP 1.1 est conçu pour permettre le pipelining de plusieurs requêtes sur une seule connexion TCP. Cette fonctionnalité permet d'éviter la latence de l'échange TCP SYN/SYN ACK lors de l'établissement de la session TCP et de réduire ainsi le temps de demande perçu, tout en minimisant la surcharge TLS, car la négociation de clé intensive en CPU a lieu uniquement pendant l'établissement TCP. Malheureusement, les serveurs HTTP récents ont des configurations par défaut qui tendent à optimiser la réponse à un grand nombre de clients, et forcent la déconnexion TCP après 5 à 15 secondes. Ce paramètre par défaut est bien trop court pour un serveur d'application IoT car il nécessite une négociation TLS complète pour chaque paquet reçu, si l'intervalle de paquets uplink vers le serveur d'application est supérieur à 5 secondes. Tous les serveurs HTTP et proxies utilisés comme serveur d'application pour les réseaux IoT LPWAN DOIVENT être configurés avec une valeur d'au moins 30 minutes.
• Le serveur d'application DOIT envoyer la réponse HTTP dès que la demande HTTP est traitée à la couche HTTP (typiquement en moins de 100ms). Le serveur d'application NE DOIT PAS bloquer la transmission de la réponse HTTP pour traiter le message backend aux niveaux supérieurs. Le traitement asynchrone des requêtes HTTP DOIT être mis en œuvre pour garantir ce délai maximum. Le cluster LRC met en œuvre une procédure de liste noire basée sur le nombre de requêtes HTTP en attente par serveur d'application. En cas de nombre trop élevé de requêtes HTTP en attente, le serveur d'application est mis en liste noire pendant 30 secondes.

Format des paramètres

Horodatages ISO 8601

Description des horodatages

Tous les paramètres d'horodatage ISO 8601 décrits dans cette section sont obligatoires et utilisent la convention suivante :

YYYY-MM-DDThh:mm:ss.s+\|-hh:mm

Exemples :

2016-08-01T09:06:06.0+02:00

2016-11-28T09:06:06.0-04:00

Où :

• YYYY : année à quatre chiffres
• MM : mois à deux chiffres
• DD : jour à deux chiffres
• hh : heures à deux chiffres (00 à 23)
• mm : minutes à deux chiffres (00 à 59)
• ss : secondes à deux chiffres (00 à 59)
• s : millisecondes à un à trois chiffres (0 à 999)
• +|-hh:mm : désignateur de fuseau horaire (+hh:mm ou -hh:mm)

Encodage des horodatages

Le paramètre d'horodatage doit être encodé différemment dans le SHA256 effectué pendant l'Authentification et dans l'URL de la requête HTTP :

Caractères spéciaux	Dans le SHA256, utiliser...	Dans l'URL, utiliser...
+	+	%2B
-	-	-
:	:	%3A
.	.	.
Exemples	2016-08-01T09:06:06.0+02:00 2016-11-28T09:06:06.0-04:00	2016-08-01T09%3A06%3A06.0%2B02%3A00 2016-11-28T09%3A06%3A06.0-04%3A00

Authentification

Interface de tunnel LRC vers serveur d'application

Cette section décrit l'authentification des rapports LRC.

Principes de sécurisation du cadre LRC vers AS

La sécurisation du cadre LRC vers AS est mise en œuvre en quatre étapes :

• Le LRC ajoute l'ID AS et l'horodatage de génération dans le message.

• Ensuite, le LRC ajoute un jeton de sécurité pour signer le message basé sur une clé d'authentification d'interface de tunnel pré-partagée.

• Lorsque l'AS reçoit un message, l'AS recalcule le jeton de sécurité.

• Si le jeton de sécurité recalculé correspond au jeton de sécurité fourni par le LRC, et si la déviation temporelle (entre la génération par le LRC et la réception par l'AS) est acceptable (par exemple, inférieure à 10 secondes), alors l'AS peut faire confiance au message et le traiter en conséquence.

L'ID AS et la clé d'authentification d'interface de tunnel font partie de la configuration de la connexion associée au capteur.

Pour plus d'informations sur la clé d'authentification d'interface de tunnel, voir Types de connexion.

Détails de la vérification des jetons

Le jeton doit être vérifié par le serveur d'application comme suit :

1. Le serveur d'application récupère les paramètres de requête décodés fournis par le LRC dans l'URL de la requête HTTP SANS le Token, mais incluant tous les autres paramètres dans le même ordre que dans l'URL :

   • Pour une trame uplink

     Un exemple de <query-parameters> est : LrnDevEui=FADE8F83D9663F5B&LrnFPort=2&LrnInfos=HTTP_RP_2ea666f7-1-1170211&AS_ID=MYASSEC&Time=2022-01-04T10:43:49.185+01:00

   • Pour un rapport de trame downlink envoyée

     Un exemple de <query-parameters> est : LrnDevEui=FADE55B9F72E2243&LrnFPort=8&LrnInfos=HTTP_RP_0dac70c1-1-1170317&AS_ID=AS&Time=2022-01-04T10:45:04.793+01:00

   • Pour un rapport récapitulatif multicast

     Un exemple de <query-parameters> est : LrnDevEui=faded697a91154b7&LrnFPort=1&LrnInfos=HTTP_RP_c837e2b2-1-1170440&AS_ID=AS&Time=2022-01-04T10:46:47.790+01:00

   • Pour un rapport de localisation

     Un exemple de <query-parameters> est : LrnDevEui=fadec8b7fce3e6fb&LrnFPort=0&LrnInfos=HTTP_RP_91cb736f-1-1170828&AS_ID=AS&Time=2022-01-04T10:54:32.380+01:00

   • Pour un rapport de notification

     Un exemple de <query-parameters> est : LrnDevEui=faded5d619611575&LrnInfos=HTTP_RP_839dcea2-1-1170548&AS_ID=AS&Time=2022-01-04T10:48:35.630+01:00

2. Le serveur d'application construit les <body-elements> comme la concaténation, sans séparateur, des valeurs suivantes :

   • Pour une trame uplink (extrait du corps DevEUI_uplink) : CustomerID, DevEUI, FPort, FCntUp, payload_hex

     Un exemple de <body-elements> est 199906997FADE8F83D9663F5B23a0b2 (concaténation de 199906997, FADE8F83D9663F5B, 2, 3, a0b2)

     Prudence

     Une valeur de FPort 0 est utilisée si aucun FPort n'est défini dans le corps de DevEUI_uplink. Une valeur de payload_hex vide est utilisée s'il n'y a pas de payload_hex défini dans le corps DevEUI_uplink.

   • Pour un rapport de trame downlink envoyée (extrait du corps DevEUI_downlink_sent) : CustomerID, DevEUI, FPort, FCntDn

     Un exemple de <body-elements> est : 199906997FADE55B9F72E224381 (concaténation de 199906997, FADE55B9F72E2243, 8, 1)

   • Pour un rapport récapitulatif multicast (extrait du corps de DevEUI_multicast_summary) : CustomerID, DevEUI, FPort, FCntDn

     Un exemple de <body-elements> est : 199906997FADED697A91154B714 (concaténation de 199906997, FADED697A91154B7, 1, 4)

   • Pour un rapport de localisation (extrait du corps DevEUI_location) : CustomerID, DevEUI

     Un exemple de <body-elements> est : 199906997fadec8b7fce3e6fb (concaténation de 199906997, fadec8b7fce3e6fb)

   • Pour un rapport de notification (extrait du corps DevEUI_notification) : CustomerID, DevEUI

     Un exemple de <body-elements> est : 199906997FADED5D619611575 (concaténation de 199906997, FADED5D619611575)

3. Le serveur d'application calcule le <token> comme suit : SHA-256(<body-elements><query-parameters><TunnelInterfaceAuthenticationKey>)

   • Pour une trame uplink

     Un exemple de <token> est : SHA‑256(199906997FADE8F83D9663F5B23a0b2LrnDevEui=FADE8F83D9663F5B&LrnFPort=2&LrnInfos=HTTP_RP_2ea666f7-1-1170211&AS_ID=MYASSEC&Time=2022-01-04T10:43:49.185+01:000eeb1d3dafc5def386223787062b6b91)

   • Pour un rapport de trame downlink envoyée

     Un exemple de <token> est : SHA‑256(199906997FADE55B9F72E224381LrnDevEui=FADE55B9F72E2243&LrnFPort=8&LrnInfos=HTTP_RP_0dac70c1-1-1170317&AS_ID=AS&Time=2022-01-04T10:45:04.793+01:000eeb1d3dafc5def386223787062b6b91)

   • Pour un rapport récapitulatif multicast

     Un exemple de <token> est : SHA‑256(199906997FADED697A91154B714LrnDevEui=faded697a91154b7&LrnFPort=1&LrnInfos=HTTP_RP_c837e2b2-1-1170440&AS_ID=AS&Time=2022-01-04T10:46:47.790+01:000eeb1d3dafc5def386223787062b6b91)

   • Pour un rapport de localisation

     Un exemple de <token> est : SHA‑256(199906997fadec8b7fce3e6fbLrnDevEui=fadec8b7fce3e6fb&LrnFPort=0&LrnInfos=HTTP_RP_91cb736f-1-1170828&AS_ID=AS&Time=2022-01-04T10:54:32.380+01:000eeb1d3dafc5def386223787062b6b91)

   • Pour un rapport de notification

     Un exemple de <token> est : SHA‑256(199906997FADED5D619611575LrnDevEui=faded5d619611575&LrnInfos=HTTP_RP_839dcea2-1-1170548&AS_ID=AS&Time=2022-01-04T10:48:35.630+01:000eeb1d3dafc5def386223787062b6b91)

     Où : 0eeb1d3dafc5def386223787062b6b91 est la clé d'authentification d'interface de tunnel pré-partagée de 128 bits (représentation sous forme de chaîne hexadécimale en minuscules) entre le serveur d'application et le LRC telle que définie dans la configuration du serveur d'application.

4. Le <token> est encodé sous forme de chaîne hexadécimale ET peut être comparé au paramètre de requête Token fourni par le LRC dans l'URL de la requête HTTP.

   • Pour une trame uplink

     Un exemple de <token> est : e2f2ed5bfa7033391ef908f2a040ede65659a6e14c156443214beb465055c5f5

   • Pour un rapport de trame downlink envoyée

     Un exemple de <token> est : 968e7e4815d4ad4bb168d087c56b0c1cd88df43685fd7f65496de51945067a37

   • Pour un rapport récapitulatif multicast

     Un exemple de <token> est : ed7906635edb764eb8e570315772e24fed3853d0f878474394d405d77b085a1a

   • Pour un rapport de localisation

     Un exemple de <token> est : 1a0bf3f1a7a0538918a87e8120170d8a238156a05ef9bae8b03c42ccc52345f2

   • Pour un rapport de notification

     Un exemple de <token> est : d159eca541c2a8d5d4bcfd1e17a5870ded99ee511cc8b164cb53df8a0deda063

5. Enfin, si le token est valide, le serveur d'application peut vérifier la déviation entre l'émission (comme indiqué dans le paramètre de requête Time) et la réception par le serveur d'application.

Interface de tunnel serveur d'application vers LRC

Principes de sécurisation du downlink frame

Le downlink frame est sécurisé avec les exigences suivantes.

Le AS ne peut pas envoyer de POST en downlink si :

• Le AS n'est pas en possession de la clé d'authentification d'interface de tunnel.

• Le AS n'a pas été autorisé à envoyer un paquet en downlink au capteur.

• Le temps entre la génération de la requête par le AS et la réception de la requête par le LRC est trop élevé.

L'ID AS, la clé d'authentification d'interface de tunnel et la déviation de temps maximale font partie de la configuration de la connexion associée au capteur.

Pour plus d'informations sur la clé d'authentification d'interface de tunnel, voir Types de connexion.

Détails de calcul du token

Le token doit être calculé par le serveur d'application comme suit :

1. Les paramètres de requête décodés du downlink message (y compris les paramètres AS_ID et Time) sont construits SANS le Token :

   Un exemple de <query-parameters> est : DevEUI=000000000F1D8693&FPort=1&Payload=00&AS_ID=app1.sample.com&Time=2016-01-11T14:28:00.333+02:00

   où : 2016-01-11T14:28:00.333+02:00 contient le caractère + dans le désignateur de fuseau horaire du paramètre Time.

2. Le <token> est calculé comme SHA-256(<query-parameters><LrcAskey>)

   Un exemple de <token> est : SHA‑256(DevEUI=000000000F1D8693&FPort=1&Payload=00&AS_ID=app1.sample.com&Time=2016-01-11T14:28:00.333+02:0046ab678cd45df4a4e4b375eacd096acc)

   où : 46ab678cd45df4a4e4b375eacd096acc est la clé d'authentification d'interface de tunnel pré-partagée de 128 bits (représentation sous forme de chaîne hexadécimale en minuscules) entre le serveur d'application et le LRC telle que définie dans la configuration du serveur d'application.> où : 2016-01-11T14:28:00.333+02:00 contient le caractère + dans le désignateur de fuseau horaire du paramètre Time.

3. Le <token> est encodé en tant que chaîne hexadécimale (Un exemple de <token> encodé est : 63a4ec6532937c9bcba109a75f731d6dc192c9df662dee56757634a8a6dc3f4c) ET ajouté à la fin des paramètres de requête de l'URL de requête HTTP utilisant le paramètre Token.

   Un exemple d'URL de requête HTTP encodée est : https://api.thingpark.com/thingpark/lrc/rest/downlink?DevEUI=000000000F1D8693&FPort=1&Payload=00&AS_ID=app1.sample.com&Time=2016-01-11T14%3A28%3A00.333%2B02%3A00&Token=63a4ec6532937c9bcba109a75f731d6dc192c9df662dee56757634a8a6dc3f4c

   où : 2016-01-11T14%3A28%3A00.333%2B02%3A00 contient le code ASCII %2B pour le caractère + et le code ASCII %3A pour le caractère :.

Encodage XML ou JSON

Définir le format JSON

Par défaut, le message des rapports LRC est encodé au format JSON par le LRC. Il peut être réglé en JSON non typé ou XML dans la configuration de la connexion.