Skip to main content

Security & Keys

Overview​

A LoRaWAN® network relies on secret keys: device keys protect the radio traffic, and credentials and tokens protect access to TEKTELIC KONA Core Network Server. This article explains what each key protects, where KONA Core uses it, and who can see it. Use it to decide who gets access to what, and how to handle keys in your own processes.

How it works​

The three device keys​

Every LoRaWAN device uses three keys. The AppKey is a long-term root key. The two session keys are valid for one session, until the device joins again.

KeyKONA Core labelWhat it protectsHow the device gets it
AppKeyApplication KeyThe join procedure. The device and the network use it to authenticate the join and derive the session keys.Stored on the device at production and entered in KONA Core. Used only with OTAA.
NwkSKeyNetwork session keyNetwork traffic. The network server uses it to check the MIC of each frame, so it knows the frame is genuine and unchanged. It also encrypts MAC commands.Derived at each join with OTAA. Set in advance with ABP.
AppSKeyApplication session keyApplication payloads. It encrypts the payload of each uplink and downlink end to end.Derived at each join with OTAA. Set in advance with ABP.

Each key is 16 bytes, entered in KONA Core as 32 hexadecimal characters. In LoRaWAN, the frame counters work with the session keys. The network rejects a frame whose counter it has already seen, so a recorded frame can't be replayed.

In KONA Core, the Enable relax frame-counter option on a device's Advanced network settings tab weakens this check. The UI warns that it enables replay attacks. Leave it cleared unless a device can't work without it.

With OTAA, a device gets new session keys every time it joins. With ABP, the session keys stay the same for the life of the device. We recommend OTAA for this reason. For how the two activation methods work, see Device Activation & Classes.

How KONA Core handles device keys​

OTAA devices. You enter the AppKey in Application Key on the device, together with the DevEUI in Device EUI and the JoinEUI in Application EUI. During the join, the device and the Join Server component of KONA Core derive the session keys. The Network session key and Application session key fields on Activation are inactive for OTAA devices. You can't enter or change their values.

Application Key requirement. For standard OTAA onboarding, enter the device's Application Key. A TEKTELIC device already registered in the Join Server can be added without manually entering its AppKey.

ABP devices. You enter Network session key and Application session key on the device's Activation tab. KONA Core uses them for the life of the device.

Multicast groups. A multicast group has its own Network session key and Application session key. All devices in the group share them.

Payload decryption. The application option Send app payload encrypted is cleared by default. It decides who decrypts the payload. When cleared, KONA Core decrypts the payload with the AppSKey before sending it to MQTT subscriptions. When selected, KONA Core sends the payload still encrypted with the AppSKey.

The same option decides whether KONA Core expects downlink payloads encrypted or not. Select it only if your application server holds the AppSKey and decrypts the payload itself. See Manage Applications.

Who can see the keys. The device form shows Application Key, Network session key and Application session key as plain text fields, without masking. Any role that can open a device's details can read them. User roles see them read-only.

A Sub-Customer sees the keys of devices in its own applications and applications assigned by its Customer. For which roles open the Devices page, see Users, Roles & Permissions.

Gateway credentials​

KONA gateways connect to KONA Core over MQTT, with TLS on port 8883 by default. Gateways added since release 2.6.13 need TLS by default; port 1883 without TLS works only when Allow non TLS MQTT connection is selected. The gateway signs in to the MQTT broker with credentials that you also save in KONA Core, in the gateway's Manage credentials dialog. The Credentials type can be:

  • Basic: a Username and Password.
  • X.509 Certificate.
  • Tektelic Certificate: the gateway uses a Gateway certificate, and must be configured to use the KONA Core root certificate.

Choose X.509 Certificate or Tektelic Certificate when you want certificate-based authentication instead of a username and password. Certificate authentication isn't restricted to particular gateway models. Configure the gateway with the certificate material required by the selected method.

The Credentials dialog warns: Please note that access to gateway passwords will eventually be removed from UI and API. Keep your own record of each gateway's credentials, for example its test report sheet. Don't rely on reading the password back from KONA Core.

The Add Gateway dialog has the option Allow non TLS MQTT connection. Leave it cleared, so the gateway can connect only over TLS. For the steps, see Onboard a KONA Gateway via MQTT.

User access and API tokens​

Web UI. Users sign in with their email address and password. KONA Core adds a 10-second timeout after each regular sign-in attempt to slow down brute-force attacks. The timeout doesn't apply to Trial Login or Google sign-in. When a session ends, KONA Core shows Session has expired and asks you to sign in again.

Each user's role and modules decide what they can see and change: see Users, Roles & Permissions.

REST API. A request to the API carries an access token in the X-Authorization header, in the form Bearer <access-token>. You get the token by signing in with the email address and password of a KONA Core user. The token has the same role, and so the same access, as that user.

The access token is valid for 2 hours and the refresh token for 24 hours. Use the access token for requests. Refresh it with the refresh token when needed. If the refresh token has expired, sign in again.

To end a token before it expires, use Revoke. For how to sign in and send requests, see the API Reference.

Integration secrets. Integrations that push data to your servers can hold their own secrets, for example an authorization token. Treat them like passwords. For HTTP integrations, we recommend HTTPS.

Audit. The User Activity Log records sign-ins, failed sign-ins, password changes and resets, and changes to entities. Check it when you suspect misuse of an account.

Best practices​

  • Use OTAA. Each join gives the device new session keys. Use ABP only for devices that don't support OTAA.
  • Give each person their own user. Don't share one account between people or systems. With a shared account, the User Activity Log can't show who made a change.
  • Use the lowest role that does the job. Use the user role for monitoring, and the administrator role only for people who change the setup. Every role that opens a device sees its keys.
  • Create a dedicated user for API access. Give it the lowest role your integration needs. If its credentials leak, you can remove that one user without affecting people.
  • Remove access when people leave. Delete or Permanently disable their user. See Manage Users.
  • Keep keys out of email and chat. Device keys usually come with the device from its manufacturer. Move them in files only as long as you need them, for example for bulk device commissioning, then delete the files.
  • Keep gateway connections on TLS. Leave Allow non TLS MQTT connection cleared.
  • Keep the frame-counter check. Leave Enable relax frame-counter cleared, so KONA Core keeps rejecting replayed frames.
  • Rotate an exposed key. For an OTAA device, change its AppKey on the device and in KONA Core. Then make the device join again. In Devices, open the device, enter edit mode, update Application Key and save the change.