Understanding the Gateway Join Server
To support massive gateway deployment scenarios in an automated and secure way, LoRa®-based gateways must follow a join process, similar to that used for end devices on a LoRaWAN® network. The gateway join process decouples the two major phases in a gateway’s lifetime: manufacturing and deployment.
In this article, we start by looking at the journey of a gateway from manufacturing until deployment. Next, we discuss who owns a gateway, followed by an overview of the gateway join server, before diving into the details of the relevant APIs.
This article assumes that the reader is familiar with LoRaWAN networks, LoRa Basics™ Station, and “gateway join process” described in the article 5 Things You Need to Know about LoRaWAN-based Gateways.
A LoRa-based Gateway’s Journey
Figure 1 illustrates the two phases of a gateway’s journey. Typically, the life of a LoRa-based gateway starts with a design that is then realized in a manufacturing phase. This manufacturing phase may include some form of personalization, whereby secrets are embedded into the gateway’s persistent storage.
Figure 1: Gateway Manufacturing and Deployment Phases
After a gateway is sold, the purchaser deploys it in a LoRaWAN network, where it connects to a LoRaWAN Network Server (LNS). The deployment phase may be repeated several times over the life of a gateway and may require that the gateway renews its LNS credentials, for instance, during migration to a new LNS. This allows solution providers flexibility in their choice of network provider.
The Manufacturing Phase
During the manufacturing phase, gateways are produced with either generic or custom LNS firmware.
Generic LNS Firmware
Generic LNS firmware typically does not include specific LNS endpoint configuration or corresponding LNS credentials for the gateway. In this case, during manufacturing, the LNS endpoint to which the gateway will connect in a deployment is unknown. Instead, in order to connect a gateway to the appropriate LNS, this information must be configured on each gateway prior to deployment. However, generic LNS firmware may also contain additional embedded secrets.
Custom LNS Firmware
By and large, custom LNS firmware does include gateway-specific credentials and LNS-endpoint configuration details. However, customer firmware usually requires a minimum purchase quantity and special agreements with the manufacturer. These types of arrangements are only possible for large LoRaWAN operators. Furthermore, the gateway-specific credentials for the LNS endpoints must be shared with between the gateway manufacturer and the gateway owner. This being the case, the LNS endpoints to which the gateways will connect in a deployment is known at manufacturing.
The Deployment Phase
During deployment, gateways must be configured for an LNS endpoint, and must be configured with the appropriate LNS authorization credentials. The Configuration Update Protocol (CUPS) can be used to configure gateways and distribute the corresponding authentication credentials.
Defining gateway ownership is not a straightforward task. In this article, we consider that the person, organization, or other entity legally tasked to manage a gateway’s LNS endpoints and corresponding set of credentials as the gateway owner. In addition, gateway owners may also control the execution of signed code. Given this definition, an owner can be one or more of the following entities:
- Manufacturer – With appropriate support agreements, the gateway manufacturer may provide gateway management services
- Network Operator – Cable operators fully manage modems installed in people’s homes; similarly, utility companies manage the meters installed in homes
- Solution or Service Provider – Part of a complete solution includes gateway management
- End User – End users can manage their gateways much as they manage personal Wi-Fi gateways
Proof of Ownership
To connect a gateway to a LoRaWAN network, you must be able to prove ownership. How do you do this?
Gateways should be able to derive a secret from a gateway-specific master key, typically embedded during manufacturing. To prove ownership, an entity must provide the appropriate secret, which can only be known by a secure physical interaction with the gateway, or with an authentic record of purchase. We will refer to this secret as a claim PIN.
The Gateway Join Server
The gateway join server decouples the configuration of LNS credentials from manufacturing and enables gateway migration of a gateway among LNS providers. The manufacturing and deployment phases when using a gateway join server are depicted in Figure 2. In this scenario, gateway owners have full control in configuring an LNS endpoint and no LNS credentials are shared with gateway manufacturers.
Figure 2: Manufacturing and Deployment Phases with a Gateway Join Server
It is crucial that the gateway join server is able to verify both claims from owners and authentication tokens from gateways. To this end, the gateway join server must be able to verify the validity of claim PINs and authentication tokens using a twin hardware secure module (HSM), one that has the same batch root key information as the HSM used during gateway manufacturing. The batch root key is the only secret that is shared between the two HSMs (the one used in manufacturing and the one associated with the gateway join server). A gateway batch encompasses a range of gateway MAC addresses which share a key derivation scheme using a common batch root key. The batch root key never leaves the security domain of the twin HSMs.
The HSM for the manufacturing phase personalizes the gateways with a gateway master key, which is derived from the batch root key. The gateway is then able to autonomously derive authentication tokens and claim PINs from this gateway master key, as illustrated in Figure 3. Note that the second HSM is connected to the gateway join server and holds the same batch root key.
Figure 3: Gateway Keys, Tokens and Claim PINs
To assist the gateway owner, the claim PIN should be either printed on the gateway label together with the corresponding MAC address, or it should be possible to use an API to read the claim PIN from the gateway itself. Alternatively, to prove ownership of a large number of gateways, the claim PINs could be made available via a secure process for customers placing large orders with a particular manufacturer. Here, the claim PIN is the secret that proves ownership of a gateway.
At its core, the gateway join server provides two important APIs, the Gateway API and the Owner API. The Gateway API implements the server-side authentication for the CUPS protocol, defined by LoRa Basics Station. The Owner API allows gateway owners to configure LNS endpoints and the corresponding credentials, as well as schedule generic signed updates.
In the following sections we will focus on the basic functions of the Owner API:
- Claim a gateway using the embedded claim secret
- Setup credentials and URIs for LNS and CUPS
- Delete a gateway (to allow other owners to claim it, for example)
- Add a gateway (this is a generic case covering gateways which do not have an embedded authorization token nor a claim secret)
The Gateway API is described at length in the LoRa Basics Station CUPS Protocol documentation. Advanced functions of the Owner API will be the subject of a future article.
Owner API: Claim
Use to claim a single gateway or set of gateways for the specified owner. The claim string is gateway-dependent. Before any operation can be performed on a gateway (e.g. setup, info, delete, etc.) it must be claimed by an owner.
JSON Request Single:
JSON Request Bulk:
Owner API: Setup
Allows an owner to configure the endpoint URI and corresponding credentials. The endpoint URIs and credentials are configurable for both LNS and CUPS instances.
JSON Request Single:
JSON Request Bulk:
JSON Request Mixed:
To simplify setting up a large number of gateways, parameters common to all gateways can be specified at the top level of a mixed request. The following code example shows a mixed request where the URI and trust base for the LNS are specified at the top level, and the gateway-specific client certificate and key are specified individually.
The API call allows an owner to configure corresponding URIs for CUPS and LNS servers implementing LoRa Basics Station protocols. The URIs are encoded as ASCII. All credential parameters (trust, certificate and key) are encoded as Base64.
Note: If a parameter is not specified, its value will be merged with the existing value in the gateway join server DB.
When using HTTP (for CUPS) or Web Socket (for LNS) as URIs, all credential parameters can be omitted. Their values will be set to null, that is, no server authentication and no client authentication will be enabled. In other words, the communication channel will not be secure.
When using HTTPS (for CUPS) or Web Socket Secure (for LNS), trust must be specified for server authentication. Furthermore, if the certificate is not empty, certificate-based client authentication requires that the key be a Base64 string encoding of the DER format of the private key for the gateway. If the certificate parameter is not present or an empty byte string, the key parameters must be a Base64-encoded string containing the Authorization HTTP header, which will be used for token-based client authentication.
Owner API: Delete
Deletes a single gateway or set of gateways for the current owner. Deleting a gateway effectively releases (“un-claims”) it from the gateway join server. This allows the ownership of the gateway to be changed.
JSON Request Single:
JSON Request Bulk:
Owner API: Add
Adds a gateway for the specified owner. This operation is for gateways which have been manufactured without an embedded claim secret. The gateway is implicitly claimed by the owner for whom it is added. The same token should be used in the corresponding cups*.key files for the LoRa Basics Station configuration. Adding a gateway will fail if the gateway already exists or conflicts with an existing batch.
The number of calls for the Add operation is strictly limited per owner. The default limit is 64.
The token is a string. The same string should be placed as a proper HTTP header (i.e. with \r\n as end-of-line delimiters in the corresponding cups*.key files in the LoRa Basics Station home folder.
Note: The cups*crt should be empty or removed.