Entities / Vocabulary
a set of LORIOT services performing the function matching and surpassing the function of a LoRaWAN Network Server.
A set of services enabling access to LORIOT web services (calls to HTTP-based API, typically on port 443).
A system / software component that is bridging the LoRa physical layer to an IP-based, TLSv1.2 encapsulated layer.
Hardware Security Module
Private Key Infrastructure
Transport Layer Security, an evolution from SSL
Certificate Signing Request
(despite to the name, this is used outside of mail services for key formatting)
For increased security, a gateway certificate and key is required when connecting a new gateway to the server.
With this feature enabled, gateways are registered in a separate component within the same environment as the front-end, and when a gateway requests to join the network, it's certificate and key are checked against the certificate authority.
The diagram below visualizes the processes to register, generate and authenticate the gateway, certificate and key:
Key provisioning step-by-step
The following are the steps a user needs to perform to generate a per-gateway client certificate and private key:
- User registers a gateway by its MAC address in the LORIOT dashboard (https, TLSv1.2+).
- User requests a new certificate for the gateway in the LORIOT dashboard (https, TLSv1.2+).
- The back-end generates a private key and a CSR on behalf of the gateway (internal)
- The Root Certificate Authority signs the certificate request (internal / can be done by HSM or PKI)
- The back-end returns both the key and the signed client certificate for the gateway to the user (https, TLSv1.2+)
- The back-end saves the client certificate and forgets the private key (internal)
- The private key is displayed one-time only in the dashboard, and the certificate can be retrieved at any time
- The user transfers the gateway private key and certificate to the gateway via a secure channel (e.g. SSH in a known network environment, direct console connection, as part of a secure file-system image, ...)
- Gateway software connects to the Web Server / Network Server and goes thru the Gateway Authentication process outlined below. If the authentication succeeds, a secure communication session is established between the Gateway and the Network Server.
Gateway Authentication Process
For every communication session between the gateway and the Network Server:
- The gateway connects to the Web Server, checks that the server presents a valid certificate according to the gateway's root certificate store or default certificate embedded in the gateway software.
- Web Server checks that the client certificate provided by the gateway is valid.
- Network Server check that the client certificate is not revoked.
- Network Server verifies that the MAC address of the gateway matches the MAC address the gateway was provisioned with.
- Once all the above checks are done, the communication session is established
Security protocols and Cipher-suites
We use RSA keys of at least 2048 bit private keys on both the server side and the gateway side.
We are using an industry standard TLSv1.2 mutual authentication, with Diffie-Hellman key exchange, AES256 encryption and SHA256 hashing.
CSR and Gateway Certificate Generation
Certificates are generated based on a Root CA, which can be configured by the customer when the server is first provisioned, or a LORIOT Root CA can be used.
Depending on the contract type, we can use HSMs and/or 3rd party PKI for certificate signing.
Key delivery to the Gateway
The system provides both the private key and the certificate in a PEM format.
It is expected that the customer has the means to securely deliver the key material (PEM files) to the gateway, as part of the gateway provisioning process.
We encourage the use of TPMs (Trusted Platform Module) on the gateways for key storage (at the moment of writing this text, we are unaware of any gateways with suitable secure hardware key storage), and an automated process of key delivery without human involvement.
Certificate linking to Gateway
Every certificate carries the specific MAC address / EUI of the gateway. Only a gateway with matching MAC address / EUI will be able to authenticate to the Network Server.
However, as MAC addresses can be changed, this is only a secondary measure of security. It does not replace the need for protecting the key material.
Anyone with access to the gateway-specific private key can act as the gateway, so the protection of the private key is a must for a secure deployment (The private key is an equivalent of a very, very long password).
Any gateway client certificate can be revoked at any time, with immediate effect.
Once a new certificate is generated for a specific gateway, the old certificate is automatically revoked.
1. Login into your user account as usual and select Networks from the menu.
Dashboard → Networks
2. Create a new Network or select your existing Network.
Dashboard → Applications → +New Network
Now select the newly created Network either by clicking on the tab on the left or the name (highlighted in blue).
3. Now add a new gateway to the network.
Dashboard → Networks → Select Network → + Add Gateway to Network
4. A list of gateways will appear, click on the relevant gateway.
5. Select the radio front end and input the MAC address of the gateway and its location.
6. The Gateway is now successfully added to the network.
Gateway binary installation
1. Selecting the gateway will direct to the gateway information page.
Dashboard → Networks → Select Network → Select gateway
2. Select the Software menu to be directed to the binary download page
3. Download the LORIOT binary installer and then via SSH install the binary file.
Generate Certificate and Key
1. Generate a unique Certificate and Key.
Dashboard → Networks → Select Network → Select gateway → Certificate
2. Download the Certificate and Private key from LORIOT via a secure channel
Add Certificate and Key
Copy the downloaded Certificate and Private key from LORIOT to the gateway via a secure channel (e.g. SSH in a known network environment, direct console connection, as part of a secure file-system image, ...)
The recommended directory is the same as the loriot binary (usually /opt/lrt)
Edit OPTION file
1. Edit the options file next to the binary (usually /opt/lrt/options) and add the following line:
2. If your certificate file is gateway.crt and private key file is gateway.key then the line must look like this: