Skip to main content

LoRaWAN® tunnel interface

LRC to Application Server Tunnel Interface​

This section describes the reports that are generated from the LRC to an Application Server.

Overview​

The purpose of this report is to tunnel an uplink packet received from a device.

An uplink packet is reported to the Application Server if it satisfies at least one of the following conditions:

  • The uplink packet contains an applicative payload (FPort > 0) larger than the DummyPayloadMaxSize value configured in the Device Profile

  • If the device implements LoRaWAN® 1.0: the ACK bit is set in the uplink packet

  • If the device implements LoRaWAN® 1.1: the ACK bit is set in the uplink packet and acknowledges an AFCntDn

  • The Class B state of the device has been successfully toggled by the uplink packet (the Class B bit of the FCtrl field included in the uplink packet has switched on or switched off the Class B state of the device)

If none of the above conditions are satisfied, the uplink packet is not reported to the Application Server.

The XML or JSON document sent to the Application Server includes the RF metadata corresponding to a maximum of 10 best receiving base stations.

Payload Encryption​

The payload can be provided to the application server either encrypted or decrypted.

The following rules apply for each kind of device.

Device activationPayload encryption
ABP device
Radio encrypted payloads		The AppSKey has been provisioned in ThingPark. Therefore the payload is provided decrypted to the AS.
ABP device
End-to-end encrypted payloads		The AppSKey has not been provisioned in ThingPark. Therefore the payload is provided encrypted to the AS. The AS must be provisioned with the AppSKey to decrypt the payload.
OTAA device
Radio encrypted payloads		The AppKey has been provisioned in ThingPark local Join Server or the external Join Server has provided the AppSKey during the join procedure. Therefore the payload is provided decrypted to the AS.
OTAA device
End-to-end encrypted payloads		The AppKey has not been provisioned in ThingPark local Join Server or the external Join Server has not provided the AppSKey during the join procedure. Therefore the payload and AppSKey are provided encrypted to the AS. For more details, please refer to End-to-end payload encryption for OTAA devices with the Hardware Security Module (HSM).

Overview​

The main purpose of this report is to give the effective RF transmission status of a downlink frame transmission initiated by an application server. The RF transmission status of downlink frames initiated by the LRC itself are not reported to the application server.

Effective RF transmission only ensures that the downlink frame has effectively been transmitted by a LRR base station. It does not guarantee that the device has received it. Reports that need end-to-end delivery reports should be sent in Confirmed mode, or use an application layer mechanism.

Note that no downlink frame sent report is generated for downlink frame targeting a multicast group. In that case, Multicast Summary Report is sent.

Multicast Summary Report​

Overview​

The purpose of Multicast Summary Report is the same as Downlink Frame Sent Report, but for multicast groups.

The main purpose of this report is to give the effective RF transmission status of a downlink frame transmission initiated by an application server. The RF transmission status of downlink frames initiated by the LRC itself are not reported to the application server.

Effective RF transmission only ensures that the downlink frame has effectively been transmitted by a LRR Base Station. It does not guarantee that the device has received it.

One report is sent after each transmission attempts of the frame. The total number of attempts depend on the service profile associated with the multicast group.

Location Report​

Overview​

The purpose of the location report is to inform, asynchronously, about the geolocation data associated to the current uplink frame (current FCntUp), as soon as available from the location server.

The location message is only reported if the network geolocation is enabled for the device, and if a new geolocation has been resolved.

Notification Report​

Overview​

The purpose of the notification report is to notify the following events:

  • Device reset: A device reset has been detected by the LRC. A device reset is detected in the following cases:

    • Reset of a device context in the ThingPark user interface

      • LoRaWAN® 1.0: The notification report is triggered by the reset and contains an LRC timestamp. The FCntDn is reset to 0 in this report.

      • LoRaWAN® 1.1: The notification report is triggered by the reset and contains an LRC timestamp. The AFCntDn is reset to 0 in this report.

    • Detection of an ABP device reset in an uplink frame

      • LoRaWAN® 1.0 when ABP automatic reset is allowed: The notification report is triggered by the uplink frame for which the FCntUp reset has been detected and contains the LRR timestamp of this uplink frame. The FCntDn is reset to 0 in this report.

      • LoRaWAN® 1.1: The notification report is triggered by the uplink frame containing the ResetInd MAC command and contains the LRR timestamp of this uplink frame. The AFCntDn is NOT reset to 0 in this report.

  • Successful Join procedure: After sending the Join-accept message, the new AppSKey is reported to the Application Server. A successful join procedure is detected in the following cases:

    • Successful Join procedure on first Join-request

      • LoRaWAN® 1.0: The notification report is triggered by the Join-request and contains the LRR timestamp of this Join-request. The FCntDn is reset to 0 in this report.

      • LoRaWAN® 1.1: The notification report is triggered by the uplink frame containing the ReKeyInd MAC command and contains the LRR timestamp of this uplink frame. The AFCntDn is reset to 0 in this report.

    • Successful Join procedure on subsequent Join-request

      • LoRaWAN® 1.0 with DevNonce counter-based: The notification report is triggered by the Join-request and contains the LRR timestamp of this Join-request. The FCntDn is reset to 0 in this report.

      • LoRaWAN® 1.0 without DevNonce counter-based: The notification report is triggered by the next uplink frame validating the join procedure and contains the LRR timestamp of this uplink frame. The FCntDn is reset to 0 in this report.

      • LoRaWAN® 1.1: The notification report is triggered by the uplink frame containing the ReKeyInd MAC command and contains the LRR timestamp of this uplink frame. The AFCntDn is reset to 0 in this report.

  • Battery and Margin: The LRC received a DevStatusAns MAC command including Battery and Margin information. The notification report is only triggered when the uplink frame containing the DevStatusAns MAC command does not contain an applicative payload. When the uplink frame contains an applicative payload, the Battery and Margin information is included in the uplink frame report.

Custom Headers (Kafka only)​

The following custom kafka headers are provided to the application server when transmitting a notification report.

Application Server to LRC Tunnel Interface​

This section describes how the downlinks are sent from the AS to a device.

Important notes

  • For Class A devices, the LRC queues up to five downlink frames for each device. The AS may decide to flush the downlink queue, using the field FlushDownlinkQueue in the downlink frame query parameters. Additionally, when the downlink queue contains payloads encrypted by AS, it is automatically flushed when an OTAA device rejoins or an ABP device reset (automatic or administrative) is detected. This is required as encrypted payloads are no more valid at this stage: AppSKey is renewed for OTAA devices and FCntDn sequence is reset.

  • For Class B devices, the LRC forwards the downlink frames to the downlink best-LRR together with the available pingslots for that device in the current and the next beacon period, so that the best-LRR can have sufficient scheduling occasions to re-attempt retransmission of the downlink frame based on its local context (LBT, busy modem ...etc). To ensure in-sequence delivery1 of the downlink frames, the AS should implement a flow control mechanism to send downlink frames one-by-one as follows:

    • Send a downlink frame (FCntDn X)

    • Wait for Downlink Frame Sent Report

      • If SUCCESS: send the next downlink frame (FCntDn X+1)

      • If failed: it is up to AS to decide if a retransmission is required.

  • For Class C devices, like Class B, the LRC immediately forwards the downlink frames to the downlink best-LRR without any queuing. In case of transmission issues (resource congestion due to modem business), the best-LRR can autonomously re-attempt packet transmission up to 60s. To ensure in-sequence delivery of downlink frames for Class C devices, the AS should implement a flow control mechanism to send downlink frames one-by-one as follows:

    • Send a downlink frame (FCntDn X)

    • Wait for Downlink Frame Sent Report

      • If SUCCESS: send the next downlink frame (FCntDn X+1)

      • If failed: it is up to AS to decide if a retransmission is required.

Payload Encryption​

Depending on the device provisioning, encryption and decryption can be performed by the LRC.

note

When the payload is encrypted, Wireless Logger cannot decrypt it as this application does not embed the associated decryption key.

The following rules apply for each kind of device.

Device activationPayload encryption
ABP device
Radio encrypted payloads		The AppSKey has been provisioned in ThingPark. Therefore the payload must be provided decrypted by the AS.
ABP device
End-to-end encrypted payloads		The AppSKey has not been provisioned in ThingPark. Therefore the payload must be provided encrypted by the AS along with the FCntDn. The AS must be provisioned with the AppSKey to encrypt the payload.
OTAA device
Radio encrypted payloads		The AppKey has been provisioned in ThingPark local Join Server or the external Join Server has provided the AppSKey during the join procedure. Therefore the payload must be provided decrypted by the AS.
OTAA device
End-to-end encrypted payloads		The AppKey has not been provisioned in ThingPark local Join Server or the external Join Server has not provided the AppSKey during the join procedure. Therefore the payload must be provided encrypted by the AS along with the FCntDn. For more details, please refer to End-to-end payload encryption for OTAA devices with the Hardware Security Module (HSM).

The following HTTP/POST message format is used to tunnel the radio frame payload and associated metadata from the target application server to the LRC. The application server acts as an HTTP client and the reverse HTTP proxy (PROXY_HTTP server) acts as an HTTP server. Rerouting of the HTTP request to the primary LRC or the backup LRC is handled by the reverse HTTP proxy.

The LoRaWAN® MAC message integrity code (MIC) is always computed by the LRC, as part of the MAC frame formatting. The MAC payload may either be encrypted by the application or by the LRC (see the table above).

This POST command can be generated easily by tools such as curl or POSTman:

curl -H "Content-type:application/x-www-form-urlencoded" -X POST "https://api.thingpark.com/thingpark/lrc/rest/downlink?DevEUI=000000000F1D8693&FPort=1&Payload=0102030405060708090A&FCntDn=1234"

Unconfirmed downlink messages are not acknowledged at LoRaWAN® level. Therefore, the network and the tunnel mode Application server does not know whether the messages have been received or not.

Confirmed downlink messages are acknowledged by the target device, but the LoRaWAN® Specification section 4.3.1.2 Message acknowledge bit and acknowledgement procedure (ACK in FCtrl) lets the device free to send delayed ACKs. Therefore, it is not possible to let the network manage retransmissions.

When the LRC receives a possibly empty uplink message (with no payload) with ACK set in the FCtrl field, the LRC will add an ACKbit flag in the XML metadata of the uplink frame sent to the Application server. The retransmit policy relies on the application server.

At PHY level, multicast support in LoRaWAN® class B and class C amount to the same thing as having multiple end devices listen to the same network address. This is already supported as part of class B and class C support in ThingPark Wireless. An Application server just needs to send an unconfirmed downlink message to the target group address (configured as a dummy device).

However, the LoRaWAN® roadmap includes future work on multicast, including group membership and key management procedures, as well as large payload fragmentation transmission such as firmware updates. Actility will implement it in ThingPark Wireless once the LoRaWAN® multicast specification is published.

End-to-end payload encryption for OTAA devices with the Hardware Security Module (HSM)​

This section describes the necessary implementation details on Application Server side to support end-to-end payload encryption for OTAA devices. It provides recommendations and examples for Application developers to design code on Application Server side.

To enforce end-to-end data privacy between end-device and AS, the end-to-end payload encryption mode allows the exchange of the uplink/downlink applicative payload between LRC and AS in encrypted format. In this mode, the application payload is encrypted via AppSKey; this key is only known to the AS (not the LRC) and hence the payload cannot be deciphered by the Service Provider.

note

In end-to-end payload encryption mode, the AppSKey is securely shared with AS (via the network server). In other words, the AppSKey itself is encrypted by the AS transport key, hence the AS must store this AS transport key and manage the decryption of AppSKey sent by NS to be able to successfully decrypt (respectively encrypt) uplink (respectively downlink) application payload.

To work properly with the end-to-end payload encryption mode, the Application Server must implement the following requirements:

  1. AS transport key provisioning/storage in the Subscriber account of the Application Server

  2. Support reception of encrypted AppSKey and decrypt it using AS Transport Key

  3. Secure storage of the decrypted AppSKey for each subscriber

  4. Decryption of uplink data using AppSKey

  5. Encryption downlink data using AppSKey before sending to the Core Network

The AppSKey present in metadata corresponds to the key of the current LoRaWAN® session of the device, therefore it is always synchronized with the AppSKey used by the device to encrypt/decrypt the data payload. When the device goes through a new Join procedure, the new AppSKey (corresponding to the new session) shall be forwarded by the LRC to AS once the new session keys are validated by a valid uplink frame (as specified by section 6.2.4 of the LoRaWAN® 1.0.2 specification).

note

In radio payload encryption mode, the application payload is exchanged in clear format between LRC and AS, nevertheless, it is protection by TLS security over the tunnel interface. In this mode, the AppSKey is NOT sent from LRC to AS over the tunnel interface (AppSKey field is empty in the Uplink Frame Report).

AS transport key provisioning​

The AS transport key cannot be accessible to ThingPark as it secures the transfer of AppSKey between HSM and AS. To enable secure AS transport key exchange between HSM and AS, asymmetric cryptography is used.

ThingPark allows the AS administrator to provision his RSA public key. The AS transport key generation button enables AS administrators to request a new AS transport key to HSM, as illustrated in the following figure.

AS transport key provisioning

This key will be returned to the AS administrator encrypted by the previously configured public key, so only the AS administrator can decode it. Additionally, the AS transport key is returned to the LRC, encrypted by HSM, in a way that only HSM can decrypt. This is required because the HSM is stateless, and therefore the JS function needs to pass the encrypted AS transport key to the HSM whenever needed.

In order to securely generate and retrieve AS transport key from HSM, the subscriber uses an asymmetric RSA key pair.

RSA key pair generation​

In a shell session, the subscriber generates an asymmetric RSA key pair using the two following commands:

  • To generate the RSA private key (private.key):
openssl genrsa -des3 -out private.key 2048
  • To generate the RSA public key (public.pem):
openssl rsa -in private.key -outform PEM -pubout -out public.pem

AS Transport Key retrieval​

The ThingPark user interface allows the subscriber to generate the AS transport key.

The subscriber provides the RSA public key in PEM format. The HSM generates a random AS transport key and returns it encrypted with the RSA public key. the encrypted AS transport key is encoded in base64.

This encrypted AS transport key is ready to be copied, decrypted, and provisioned in the Application Server. The generated label will be used to identify which AS transport key must be used when receiving an uplink frame.

This encrypted AS transport key is not saved in ThingPark. If lost by the subscriber, a new AS transport key will have to be generated.

The encrypted AS transport key can be stored in ASCII format in a text file (for instance encryptedASTransportKey.txt), and decrypted as follows:

cat encryptedASTransportKey.txt | base64 -d | openssl rsautl -decrypt -inkey private.key | xxd -p

Encrypted AS transport key decryption example​

ParameterValue
Encrypted AS Transport Key (base64 encoded)k13rCYqFTIui/JfEh7sTR6ejA0p3cj8GzBIm3nQM8VZ42EsCZT/9w9a8yrjllqsr
Y7WHzNGBvPAXccqAyMaqyFmI3MczU1/PfiOKZ0FL487Z/cPucGTiS2ThsG7t0UEz
zSuLfqzy3ieI0nz+YEgGLwB2DdRJS2fNgZYQmvyaIbFcdDfv6g3iY1OLP2ffOKCh
MaBWJEQWyZ1cgQd95GNhBBv6XXNVISRibjyx/szFEFP1kcZkYJJ22goOTvvbDt8Q
fG1Md/7dOc9g1StpfW5dIFP+jL8W4PCOyR6JFREGTJjUI7SHKiliq73FT+QTb4Ih
ZUjqQA2x7WfhjLXfBlOxKQ==
Deciphered AS Transport Key (hexadecimal encoded)65e040875cb38ad99681379df656306b
Public RSA Key-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA0/L/n52Fvlf2A9IFvRG1
kT9VNN5XSDyMlWkwrZMiQthHgues09YFo9yyNz3n+WI7laJz3LZfbZAX3ljNq1Dm
CLnW64e+4nSc6Qw/aLgvFKZPZ4R3SezHkV5bSsD87Bpx8eDti8w77ovfx/Or27Jw
WY1YLixbAJ8pP7MT9W70tEMYhfcLYzCX0kFi3eDbsvzz5H+tA0b/DXrtAfjw7Smy
IfeNi/GYrFKQEkrj9co67BWaT9RH9mLIVnuyDpsUMpdriGbc8UJ2/2ZSAL11lI8D
54UZUPJugIOc51BLDVQRVN6h8Mu1rCUo2QD95kd6mgCdZCuZVo3vpmzBTQDrSnr2
mQIDAQAB
-----END PUBLIC KEY-----
Private RSA Key-----BEGIN RSA PRIVATE KEY-----
MIIEpAIBAAKCAQEA0/L/n52Fvlf2A9IFvRG1kT9VNN5XSDyMlWkwrZMiQthHgues
09YFo9yyNz3n+WI7laJz3LZfbZAX3ljNq1DmCLnW64e+4nSc6Qw/aLgvFKZPZ4R3
SezHkV5bSsD87Bpx8eDti8w77ovfx/Or27JwWY1YLixbAJ8pP7MT9W70tEMYhfcL
YzCX0kFi3eDbsvzz5H+tA0b/DXrtAfjw7SmyIfeNi/GYrFKQEkrj9co67BWaT9RH
9mLIVnuyDpsUMpdriGbc8UJ2/2ZSAL11lI8D54UZUPJugIOc51BLDVQRVN6h8Mu1
rCUo2QD95kd6mgCdZCuZVo3vpmzBTQDrSnr2mQIDAQABAoIBABzJQyill1Wb0sEA
FGFyd0uL44GztP0NpDZivAbHFf8oKsY/uvxmdAumXNod4VTAn8EZ+EyAxIM379X2
D7D14thKjUMeA7H0Dp+kVzRc16AhWmV/20fCDfTTcOi9P1y91r34Q6saCQXEH5ej
o7LKEHJJPTHAOnfiJhMNumc6M6gLuU88J8UkDrWAM8ji6soMY67VmzAjanpxaSjA
2NBBNJ1Yjh6X/8Pp53qxwrTZRThSrjJAO/vANMy5VsnHqPAXM5Jg7BGJGp24IgPF
4L/2MnWRApCSNNK+MM88AaDOeYBwMvL9rRFGU87gwCP2Tqhy5jryw/Z0QtSbQ2ij
meePpQECgYEA/wjkC9qO3libaTjgVlQyJXGO7qNzgBhI5nwvVStsGgl/k/rZ+4zf
19d5LHRAhh6llQpYvKwIT/QPk6Jdyh/8tIBCurTuYAlwFmbYFC7HhjtXRPgjgNzE
voujfkkqe9sW88NjBeJY9Sn2KgdFuAUkB8CY+HuKn+8GXD6RXAQ+PLkCgYEA1MBc
dAGpheQYO9IULId0cgi36WELpedsE4SM9t499ReZ13sdle9l96FQ21psgxY0jps0
ySfHBsgAZRWva51txYK0nX3Ievebwkpu15STGvjmPXNyiYZSp454zeSwHjxiX6en
NgQzE7Ih5Kz6nAyMUoP+VxPlOCpEmbEFNx4oWOECgYEAjo5QspOLkpui21EwjPDp
SubMB3aUBEEO1s8JwijQd0lh57yrhiG7qbHHCOM+gfm1grbS3TuoNdDtuA9lL6tr
nRWotyaVrFb6MXtxQu7XFqAq6uFtLwW4b+4sCFYriinwDXfk7RAVu4ymDd4cyX0O
I8szdonP9hAs1PkgVXgFtfkCgYAY7nHnJkq3ZgNw/y1eCoGa22qx7q1uw6/mmaHr
TB/2mM1ucv8Ekwlf+4d+LRqKQg/mpkmJSSAJq2ZgciocclZqzuZbjmHwBxQ5sH9M
xBx5DLHugZjqhNMqz4dYmXQKFwlwLDVsHxHdPQK7yYmUv+Oxx8YGbk5uRoXDfPsf
emlAAQKBgQCW4AALAsBfhd1ZGkK4S3P4vq67bNDyC8b/Yq/Q8dNIIhc3CmU7xP7Y
AQsN/VMX6h/zPnP/tuqefDqKl2m03x58ghzC4PFTNJyrDJeJaeEPazzHch7v/tgY
CwlM8IFwEeQVkcA+Q7xRuxgUsZrPZWZTvL7hsaoYAKsdhSBB/FThUA==
-----END RSA PRIVATE KEY-----

AppSKey deciphering​

Encrypted AppSKey decryption​

AppSKey can be decrypted using openssl as follow:

echo $AppSKey | xxd -r -p | openssl enc -d -aes-128-cbc -nosalt -iv 0 -K $ASTransportKey -nopad | xxd -p

Encrypted AppSKey decryption example​

ParameterValue
Encrypted AppSKeyDFE758AFD5FD4DD8A64BE063373AF6C8
Deciphered AS Transport Key98CC5DDD614FF2DF44FD09CA9F52CDBA
Deciphered AppSKeyb0ad83c614043c76c434d460b48b90b4

Details

echo "DFE758AFD5FD4DD8A64BE063373AF6C8" | xxd -r -p

Converts the AppSkeyEnc in binary

openssl enc -d -aes-128-cbc -nosalt -iv 0 -K 98CC5DDD614FF2DF44FD09CA9F52CDBA -nopad

Deciphers the AppSkey with the deciphered AS transport key

| xxd -p

Displays the AppSKey in hexadecimal format

Payload deciphering​

Encrypted payload decryption​

Decryption process according to LoRaWAN®:

  • Determine number of 16 byte blocks - k

  • Create encryption block(s) A1 ... Ak

Size (bytes)1414411
Ai0x014 x 0x00DirDevAddrFCntUp or FCntDown0x00i

  • Create encryption string S1 = aes128_encrypt (AppSKey, Ai)

  • S = S1 | S2 | .. | Sk

  • Pad payload to 16B

  • XOR payload and S

  • Truncate XOR to the size of original payload

Encrypted payload decryption example​

ParameterValue
Deciphered AppSKey2B7E151628AED2A6ABF7158809CF4F3C
Encrypted payload90ada2ccf937393e229e
DevAddr00790D93 (930D7900 in little endian)
FCntUp11 (0B000000 in little endian)
Deciphered payload48656c6c6f576f726c64
  • Determine number of 16 byte blocks - in this case we have one 16 byte block
# export enc_payload=90ada2ccf937393e229e
# echo $((($\{#enc_payload} + 31) / 32))
1
  • Create encryption block(s) A1 ... Ak
# export A1=010000000000930D79000B0000000001
  • Create encryption string
# export AppSKey=2B7E151628AED2A6ABF7158809CF4F3C
# export S=`echo $A1 | xxd -r -p | openssl enc -e -aes-128-cbc -nosalt -iv 0 -K $AppSKey -nopad | xxd -p`
# echo $S
d8c8cea09660564c4efaeaa752df7e47
  • Pad payload to 16 Bytes
# export pad=`echo $enc_payload | sed -e :a -e 's/^.\{1,31\}$/&0/;ta'`
# echo $pad
90ada2ccf937393e229e000000000000
  • XOR payload and S
# export xor=`printf '%x%x\n' "$((0x${pad:0:16} ^ 0x${S:0:16}))" "$((0x${pad:16:16} ^ 0x${S:16:16}))"`
# echo $xor
48656c6c6f576f726c64eaa752df7e47
  • Get decrypted payload by cutting the result of XOR operation to the size of original payload
# echo ${xor:0:$\{#enc_payload}}
48656c6c6f576f726c64

Footnotes​

  1. The MAC layer of the end-device shall drop downlink frames that are received out of sequence. ↩

Last updated on
Copyright © 2024 Actility
On this page