Module multicast 

Remote multicast setup, TS005-2.0.0.

Sending the same firmware image to a thousand devices one at a time would take the band for days. Instead the server gives them all one multicast address and one key, then opens a window in which they listen together. This package is how that group is set up: the server creates it with McCommand::McGroupSetupReq, carrying the group’s key wrapped under a key only the device holds, and later opens a Class C or Class B session on it.

The keys come down a chain no session key ever leaves:

• mc_root_key from the device’s own root key, then mc_ke_key from that: the key the group keys travel under, which lives as long as the device does.
• mc_key unwraps the group key the setup carried.
• mc_app_s_key and mc_nwk_s_key derive the pair that reads the group’s frames, from the group key and the group’s address.

Examples

A server wraps a group key, and the device unwraps it and derives the session:

use pamoja_lorawan::packages::multicast::{
    mc_app_s_key, mc_ke_key, mc_key, mc_nwk_s_key, mc_root_key, wrap_mc_key,
};

let app_key = [0x2B; 16];
let group_key = [0x77; 16];
let ke_key = mc_ke_key(&mc_root_key(&app_key));

let wrapped = wrap_mc_key(&ke_key, &group_key);
assert_eq!(mc_key(&ke_key, &wrapped), group_key, "the device gets it back");

let addr = 0x2601_1BDA;
assert_ne!(mc_app_s_key(&group_key, addr), mc_nwk_s_key(&group_key, addr));

Structs

SessionStatus

What a device makes of a session a server asked it to open, table 20.

Enums

McCommand

One command of the remote multicast setup package.

Constants

GROUPS

How many multicast groups a device may hold at once, section 4.3.

MAX_COMMAND

The longest command of this package, in bytes.

PACKAGE

The identifier of this package, section 4.

PORT

The port the remote multicast setup package is spoken on, section 4.

VERSION

The version of this package implemented here, section 4.

Functions

mc_app_s_key

Derives the key that reads a group’s payloads, section 4.3.

mc_ke_key

Derives the key a group’s key travels under, section 4.3.

mc_key

Unwraps the group key a setup command carried, section 4.3.

mc_nwk_s_key

Derives the key that verifies a group’s frames, section 4.3.

mc_root_key

Derives a device’s multicast root key on the LoRaWAN 1.0.x scheme, section 4.3.

mc_root_key_for

Derives a device’s multicast root key, section 4.3.

wrap_mc_key

Wraps a group key for a device, which is what a server does before sending it.