Skip to content

Added support IEEE 802.15.4-2015+ frame control and MHR (#4947) - #5306

Open
nflatrea wants to merge 3 commits into
secdev:masterfrom
nflatrea:master
Open

nflatrea wants to merge 3 commits into
secdev:masterfrom
nflatrea:master

Conversation

@nflatrea

Copy link
Copy Markdown

Description

Added support for IEEE 802.15.4-2015+ to scapy/layers/dot15d4.py.
Until now only 2003/2006 frames where supported

Frame version 0b10 (802.15.4-2015 and later) defines Frame Control bits that used to be reserved, thus changing the rules for which MHR fields are present. Scapy kept applying the old rules to these frames, so captures from Wi-SUN, TSCH and Thread 1.4 were dissected wrongly.

Changes

  • Frame Control:
    • new fields fcf_seqnumsuppress and fcf_ie_present, in the bits that were reserved before
    • the sequence number is only present when it isn't suppressed
  • Frame versions now have names (2003 / 2006 / 2015).
  • New frame types: Multipurpose, Fragment and Extended.
  • PAN ID and address presence for frame version 2 follows the 2015 table: PAN ID Compression combined with both addressing modes. Versions 0b00 and 0b01 behave exactly as before.
  • Header IE and Payload IE are dissected when fcf_ie_present is set.
  • Auxiliary security header: Frame Counter Suppression and ASN-in-Nonce are supported.
  • The MAC command ID enum covers the 2015+ commands.

/!\ header fields are present depending on frame version + PAN ID Compression + addressing modes taken together.
I kept the old code path untouched for versions 0/1 and added a separate one for version 2. This avoids regressions on existing captures, at the cost of a little duplication.

Impact

Nothing should change for 2003/2006 frames: all existing dot15d4 tests passed unchanged. Layers built on top of 802.15.4 (6LoWPAN, ZigBee) still receive the same payload.

Tests

Second commit added unit tests to test/scapy/layers/dot15d4.uts:

  • 2015 frames covering every PAN ID / addressing combination
  • sequence number suppression
  • Header and Payload IEs
  • Frame Counter Suppression
  • build/dissect round-trip
  • non-regression on 2003/2006 frames

Results were not checked against real Wi-SUN or TSCH as we don't have enough samples.

fixes #4947

nflatrea and others added 3 commits October 30, 2026 18:26
…v#4947) (1/2)

modified:   scapy/layers/dot15d4.py

Frame version 0b10 (2) redefines two formerly reserved Frame Control bits
and changes which MHR fields are present. The layer was only correct
for 2003/2006 frames, so 2015+ captures (ex. Wi-SUN, TSCH, Thread 1.4)
were mis-dissected (addresses and PAN IDs were read at the wrong offsets).

	Added fcf_ie_present (bit 9) and fcf_seqnumsuppress (bit 8) in place of
	fcf_reserved_2; the sequence number is now conditional.
	Name frame versions and the Multipurpose/Fragment/Extended frame types.

	destination/source PAN ID and address presence now follows 7.2.2.6 Table 7-2
	for version 2 (PAN ID Compression now also governs the destination PAN ID);
	versions 0b00/0b01 (0/1) are unchanged.

	Added Header IE (7.4.2) and Payload IE (7.4.3) dissection, including
	Header Termination 1/2 and Payload Termination handling, after the
	Aux Security Header; payload IEs are not parsed when encrypted.

	Dot15d4Ack now carries addressing/security/IEs for 0b10;
	Imm-Ack behaviour is unchanged.

	no Superframe/GTS/Pending Address fields for 0b10.

	Added Frame Counter Suppression and ASN in Nonce bits; frame counter becomes conditional.

	Extend the MAC command ID enum to the 2024 table

patch:      Added IEEE 802.15.4-2015+ frame tests (secdev#4947) (2/2)
modified:   test/scapy/layers/dot15d4.uts

	Added tests covering captures from round-trip, PAN ID presence,
	Sequence Number Suppression, Enh-Ack, Enhanced Beacon and Frame Counter Suppression.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Scapy IEEE 802.15.4 processing is based on version 2011?

1 participant