Packet Broker API

Packet Broker is a packet-based traffic exchange for LoRaWAN networks.

This repository contains the API for interacting with the Packet Broker Router and Key Exchanges. The API is based on gRPC for high performance and portability to any environment.

Terminology

Concept

High level concept

On uplink:

• Forwarders publish an uplink message with encrypted fields to the Home Network via Packet Broker Router
• Forwarders generate one or multiple key encryption keys (KEKs) with a KEK label. Forwarders can use any rotation and key sharding strategy (per message, per time unit, per Home Network NetID, a combination of those, etc)
• Forwarders publish the KEKs to Key Exchanges
• Forwarders generate data encryption keys (DEKs) for PHYPayload, signal quality and localization metadata. The DEKs may be the same or may be different
• Forwarders encrypt the uplink message
  • The PHYPayload gets encrypted with the DEK for PHYPayload
  • The signal quality gets encrypted with the DEK for signal quality
  • The localization gets encrypted with the DEK for localization
  • Forwarders choose which KEKs to use to encrypt the DEKs
  • The encrypted DEKs are added to the message, referring to the KEK that encrypted the DEK
  • All encryption uses AES-256-GCM
• Forwarders generate the SHA-256 payload hash in the message
• Forwarders publish the encrypted message to Packet Broker Router. The uplink message contains:
  • Pointers to KEKs used for encrypting DEKs in the message. The pointers consist of the Key Exchange address and the KEK label
  • Teaser of the PHYPayload to drive the decision to decrypt an encrypted DEK, containing:
    • SHA-256 hash of the PHYPayload except MIC (to support retransmissions in LoRaWAN 1.1.x)
    • LoRaWAN public fields
    • Join-request: JoinEUI, DevEUI and DevNonce
    • Data uplink: confirmed uplink yes/no, DevAddr, FOpts yes/no, FCnt, FPort and FRMPayload length
  • Encrypted PHYPayload and the DEK encrypted with one or multiple KEKs
  • Teaser of the gateway metadata to drive the decision to decrypt an encrypted DEK, containing:
    • Whether the gateway is terrestrial or a satellite
    • Indication whether localization data contains a fine timestamp
  • Encrypted signal quality and the DEK encrypted with one or multiple KEKs
  • Encrypted localization and the DEK encrypted with one or multiple KEKs
  • Forwarder and gateway uplink tokens
  • Region of the gateway as defined in LoRaWAN Regional Parameters
• Packet Broker Router routes the encrypted message with the Forwarder (Tenant) to the Home Network (Tenant) according to the Routing Policy and Routing Filter
• Home Network can buy the message (i.e. decrypt a DEK) based the teasers, based on price(s) on Key Exchange(s) and payload hash (to check if the message has been received already via other means)
• If the Key Exchange provides the KEK, the Home Network can decrypt the DEK itself. Otherwise, the Home Network requests the Key Exchange to decrypt the DEK
  • Alternatively, the Home Network may optionally have the PHYPayload decrypted and pass the FNwkSIntKey or NwkSKey to validate the MIC before recording the transaction, if the Key Exchange supports this

On downlink:

• The Home Network publish a downlink message to a Forwarder via Packet Broker Router
• The downlink message contains:
  • PHYPayload
  • RX1 and RX2 frequency and data rate index (in gateway region from the uplink message)
  • RX1 delay
  • Class (A or C)
  • Forwarder and gateway uplink tokens copied from the uplink message

Downlink is similar to Stateless Passive Roaming as defined in LoRaWAN Backend Interfaces. The API is compatible with the XmitDataReq message, except that Packet Broker downlink can be used for join-accept messages.

Components

• Forwarder
  • Configures routing
    • Routing Policies per Home Network
    • A default Routing Policy (default is routing enabled with all uplink and downlink flags set)
  • Generates KEKs and DEKs
  • Publishes KEKs to Key Exchanges
  • Encrypts DEKs with one or multiple KEKs
  • Encrypts PHYPayload, signal quality and localization metadata with DEKs
  • Publishes messages to Packet Broker Router
  • Subscribes for downlink on Packet Broker Router
• Packet Broker Router to route traffic from Forwarders to Home Networks and back. Acts as a switchboard
  • Forwarder interface: rpcs for publishing uplink messages and subscribing to a stream of downlink messages
  • Home Network interface: rpcs for publishing downlink messages and subscribing to a stream of uplink messages
  • Router
    • Uplink
      • Acts on messages published by a Forwarder
      • Depending on the message type:
      • On join-request, determines the Home Networks (and their Tenants) by their configured JoinEUI and DevEUI prefixes of interest
      • On data uplink, determines the Home Networks (and their Tenants) by the NetID from DevAddr. Drops the message if none found
      • Looks up the Uplink Routing Policy of the concerning Forwarder and Home Network. Falls back to the default Routing Uplink Policy. Drops the message if uplink routing is disabled for the concerning Home Network
      • Applies the Uplink Routing Policy
      • Looks up the Home Networks' Routing Filters. If any, drop the message if any Filter does not pass
      • Delivers the message to the Home Network (Tenants)
    • Downlink
      • Acts on messages published by a Home Network (Tenant)
      • Determines the Forwarder (Tenant) by the given NetID and Forwarder ID and optionally Tenant ID. Drops the message if not found
      • Looks up the Downlink Policy of the concerning Forwarder (Tenant) and Home Network (Tenant). Falls back to the Routing Policy of the Home Network, and if not set, falls back to the default Routing Policy. Drops the message if downlink routing is disabled
      • Applies the Downlink Routing Policy
      • Delivers the message to the Forwarder (Tenant)
• Home Network
  • Publishes downlink messages to Packet Broker Router
  • Subscribes to uplink on Packet Broker Router with its ID and a set of Routing Filters. If no Routing Filters specified, a catch-all Routing Filter applies
  • Makes consideration to have PHYPayload or metadata decrypted
  • On a positive decision, has the encrypted DEK decrypted
  • If the Key Exchange provides the KEK, the Home Network decrypts the DEK. Otherwise, the Home Network requests Key Exchange to decrypt the encrypted DEK
• Packet Broker Key Exchange
  • Provides the KEK and records the transaction. This allows Home Networks to decrypt messages offline. Forwarders are free to rotate KEKs and use multiple KEKs at any time
  • Decrypts on request by the Home Network, respecting the KEK usage limit, recording the KEK transaction, and optionally checks MIC if session key NwkSKey or FNwkSIntKey is provided

Types of Key Exchanges

All Key Exchanges keep track of the usage of KEKs to decrypt DEKs on request by a Home Network. Forwarders and Home Networks can be the same Member if they play both roles.

1. Marketplace Members have one billing relationship with the Marketplace for debit and credit invoices

2. Balancer Members can offset the balance with a mutation that they both agree on, typically from an out-of-band monetary transaction

Operations

Packet Broker Router exposes the routing services API. Clients can use gRPC directly, or use the Packet Broker command-line interface (CLI).

Packet Broker Router services are exposed on the following default ports:

Packet Broker Router uses token-based HTTP authentication and TLS mutual authentication. Learn how to obtain a TLS client certificate.

License

The API is distributed under Apache License, Version 2.0. See LICENSE for more information.