[josephnef]

M6 (#260, EPIC #254): per-cell keys, and the handover security context pre-staged for the UE in the 802.11r style. This closes the "security context" open item.

Why

Every cell, DU and UE shared one key (CELL_PSK), so whoever held it could forge any cell.

What

• src/cell/Keys.h (new): every key derives from one master that only the CU and provisioning hold. Keys are hex(HMAC-SHA1(master, info)), used as the HMAC keys exactly as CELL_PSK strings are.
  • Cell key K_c: tags everything that controls cell c's UEs (grant map, handover IE, DL body, the UE beacon's own tag, MR, RACH). A compromised DU or UE forges that one cell.
  • Area key K_A: tags what another cell must check: the neighbour list (measurement provenance) and a new area tag on the UE beacon. A neighbour DU now checks that tag before it counts a UE as heard or forwards it for DAPS; before, it took "heard" from any frame with the right address.
  • UE key K_(c,u): belongs to the UE's home identity.
  • wrap_context: raw(K_t) ⊕ HMAC(K_u, 'X' id target) ‖ HMAC(K_u, 'K' id target raw(K_t))[0..4]. The pad is per handover, and the 4-byte key check lets the UE refuse a context that isn't its own.
• Formats:
  • F1 v9: HoCommand::ctx (24 bytes);
  • handover IE v3: carries ctx;
  • UE beacon IE v3 (kCellProtoVersion 3): an area tag (label V) after its tag.
• CU (RAN_MASTER_KEY): wraps the target cell's key for the UE's home key in every command (ran.ho_cmd ctx, home). home_of follows a UE across handovers.
• DU: relays the context in its handover IE without reading it. It airs the NL under the area key and checks other cells' UE beacons by their area tag.
• UE (CELL_AREA_KEY, CELL_UE_KEY):
  • unwraps the context when it accepts a command, and refuses one that isn't its own (cell.ue.ho_no_context);
  • verifies the target's buffered maps with K_t;
  • switches key at the switch and back on a fallback (the serving key is read under a lock by the RX thread);
  • takes the NL under the area key and airs the area tag;
  • its RACH uses the serving key.
• Without CELL_AREA_KEY: one shared key for everything, as before.
• Selftests:
  • cell_m6: the derivation, the hex round trip, the context (wrong UE / id / target / tampered → refused), and the context through F1 and the IE;
  • cell_node: the area tag accepted only with the area key and the cell tag only with the cell key.
• Docs: docs/cell-m6.md gains a section on per-cell keys and the handover context. The open items now cover joined UEs (no provisioned UE key) and the area-key exposure.

Rig (testrig scripts/m6_cellkeys.sh; the scripts derive every role's keys from one master)

case	runs	result
handover under per-cell keys	2	context in every command (home 1:1); switch, target in slot 99.8 %, ran.ho_done; 0 maps refused
UE holding cell 2's key in cell 1 (a cell-2 insider forging cell 1)	2	0 of 879 maps taken, never heard in slot; cell 2 unaffected
UE holding another UE's key	2	every command refused (no context), no switch; DU1 kept it (heard 100 %, in slot 99.8 %)
coordination with "heard" from area tags	1	ran_coord_analyze pass, both cells' UEs heard by the other DU

The M6 suite under per-cell keys passes: inter-frequency handover and fallback, DAPS, measurement gaps, phase planning, the crossing with source failure, clock fit across a DU restart, and the RACH re-join. One shared-key handover also passes, so the old mode is unchanged.

Open:

• a RACH-joined UE has no provisioned UE key, so under per-cell keys it doesn't hand over;
• an area-key holder can fake measurement provenance and heard/DAPS presence, but never control.

🤖 Generated with Claude Code

[qodo-free-for-open-source-projects]

PR Summary by Qodo

Isolate cell keys and pre-stage UE handover security contexts

✨ Enhancement 🧪 Tests 📝 Documentation 🕐 40+ Minutes

AI Description

• Derive separate cell, area, and UE keys to limit the reach of compromised credentials.
• Carry a UE-specific target key through handover, enabling authenticated target maps and key
 switching.
• Authenticate cross-cell presence, retain shared-key mode, and document tests and remaining
 provisioning gaps.

Diagram

sequenceDiagram
    participant Keys as Key derivation
    participant CU as Controller
    participant Target as Target DU
    participant Source as Source DU
    participant UE as UE
    CU->>Keys: Derive target and home keys
    Keys-->>CU: Return keys
    CU->>Target: Stage handover context
    CU->>Source: Send handover context
    Source->>UE: Relay authenticated handover IE
    Target->>UE: Send target grant maps
    UE->>UE: Unwrap, verify, switch key
    UE->>Target: Send area-tagged beacon

Loading

High-Level Assessment

The following are alternative approaches to this PR:

1. Keep one shared cell key

• ➕ Requires no new provisioning or handover context.
• ➖ A holder can forge traffic for every cell, the problem this PR addresses.

2. Establish a direct CU–UE key channel

• ➕ Could deliver target keys without relaying a wrapped context through DU handover messages.
• ➖ Requires a new authenticated transport and UE protocol rather than using the existing F1 and handover IE paths.

Recommendation: Use the PR's wrapped-context approach: it limits cell-control credentials without adding a CU–UE transport and preserves shared-key operation. Treat join-time UE-key provisioning and the forgery scope of the shared area key as follow-up security work.

Files changed (9) +485 / -32

Enhancement (6) +340 / -25

cell.hAdd an area tag to version 3 UE beacons +17/-8

Add an area tag to version 3 UE beacons

• Extends UE beacons with a second tag and lets parsing verify either the serving-cell tag or the area tag for cross-cell presence checks.

examples/cell/cell.h

main.cppApply cell, area, and UE keys across DU and UE operation +100/-12

Apply cell, area, and UE keys across DU and UE operation

• The DU authenticates neighboring UE beacons with the area key, signs neighbor lists with it, and relays opaque handover contexts. The UE unwraps a context before accepting handover, verifies buffered target maps with the target key, switches keys at handover, and restores the source key on fallback.

examples/cell/main.cpp

F1.hCarry handover contexts in F1 version 9 +4/-1

Carry handover contexts in F1 version 9

• Adds the 24-byte context to handover command encoding and decoding and advances the F1 protocol version.

src/cell/F1.h

HoCommand.hCarry contexts through handover commands and version 3 IEs +11/-2

Carry contexts through handover commands and version 3 IEs

• Adds context fields to the command and over-the-air IE, including them in IE encoding, decoding, CRC, and tag coverage.

src/cell/HoCommand.h

Keys.hDefine key derivation and UE-specific context wrapping +175/-0

Define key derivation and UE-specific context wrapping

• Introduces master-derived area, cell, and home-UE keys, hex conversion, and a 24-byte wrapped target key with a key check. Documents credential ownership and the shared-key fallback.

src/cell/Keys.h

main.cppWrap target keys for each UE's home identity +33/-2

Wrap target keys for each UE's home identity

• Uses the configured master key to create handover contexts and tracks a UE's home identity across handovers. Clears provisional home mappings on cancellation or timeout and logs whether commands contain a context.

tools/ran-controller/main.cpp

Tests (2) +77 / -5

cell_m6_selftest.cppTest key derivation and handover context integrity +63/-1

Test key derivation and handover context integrity

• Tests distinct derived keys, hex conversion, context rejection for wrong credentials or tampering, and context preservation through F1 and handover IE serialization.

tests/cell_m6_selftest.cpp

cell_node_selftest.cppTest independent cell and area beacon tags +14/-4

Test independent cell and area beacon tags

• Adjusts beacon-format assertions for version 3 and verifies that each tag accepts its corresponding key but rejects the other.

tests/cell_node_selftest.cpp

Documentation (1) +68 / -2

cell-m6.mdDocument the key model and handover security context +68/-2

Document the key model and handover security context

• Explains key ownership, context delivery, keyed rig results, and shared-key compatibility. Replaces the resolved security-context open item with join-time provisioning and area-key exposure limitations.

docs/cell-m6.md

[qodo-free-for-open-source-projects]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. Reused identities block later handovers ✓ Resolved

Description

home_of retains a mapping for a UE's former serving identity after that UE successfully moves to
another cell. When a different UE later receives the vacated identity, the CU wraps its handover
context using the previous UE's home key, so the new UE refuses the command.

---

2. Area-tag checks silently disappear ✓ Resolved

Description

area_auth() converts a configured CELL_AREA_KEY into an empty authenticator on builds without
OpenSSL, while auth_ok() checks only CELL_PSK for that build. If the area key is set but
CELL_PSK is empty, startup succeeds and the new cross-cell beacon and neighbour-list paths accept
unauthenticated frames.

---

Tip of the day

💡 Did you know, you can hide the parts of a finding you never read, like the evidence or the agent prompt

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[josephnef]

Qodo review addressed in f9f7be6:

1. Reused identities block later handovers: at ran.ho_done the CU now drops home_of for the source identity the UE left, so a UE given that identity later never inherits the previous UE's home key. The target mapping stays while the UE holds it, and the abort paths still drop the provisional one. Rig re-check under per-cell keys: a crossing there and back (1 → 2 → 1) wraps both commands for the UE's own home (home 1:1) and passes.
2. Area-tag checks silently disappear without OpenSSL: CELL_AREA_KEY and CELL_UE_KEY are now refused at start on a build without OpenSSL, as CELL_PSK is, so a set key can never become an empty authenticator. The CU already exits for any HMAC key there; its message now names RAN_MASTER_KEY too.

ctest 95/95.

[josephnef]

CI green; both Qodo bugs resolved. The remaining items are the two high-level alternatives (keep one shared key; a direct CU–UE key channel), for which Qodo recommends this PR's wrapped-context approach. Join-time UE-key provisioning and the area-key scope are listed as open in docs/cell-m6.md. Merging with skip-qodo-gate.