XU XUv0.13.1
中文

#embedded/wifi

import: #embedded/wifi

counts: 13 functions, 4 methods, 6 types, 13 constants, 0 method sets

Protocol building blocks and device responsibility

This package supplies bounded beacon parsing, AP selection, association and a narrow PSK/CCMP pairwise handshake. It prepares protocol messages and validates received bytes; applications supply the controller event loop and manage key installation, replay counters and packet ownership. Verify hardware completion and RX status before parsing DMA data.

Use key_data for wrapped key-data validation, ccmp for authenticated protected frames, and ipv4 for DHCP/ARP/ICMP acquisition probes. Standard WifiDevice operations remain unavailable. Persistent station service, lease renewal, DNS/TCP, WPA3/PMF and BLE/Wi-Fi coexistence require further implementation.

struct Beacon

XuAPI
pub struct Beacon {
    pub valid bool
    pub ssid []int
    pub bssid []int
    pub channel int
    pub interval_tu int
    pub privacy bool
}

Purpose

A bounded parser for one complete, FCS-stripped IEEE 802.11 beacon MPDU. The radio driver must independently verify DMA ownership, RX status, FCS, and the captured length before passing bytes here. This reports an observed beacon, never an association, IP lease, or authentication mode.

Public fields

valid bool
field (bool)
ssid []int
field ([]int)
bssid []int
field ([]int)
channel int
field (int)
interval_tu int
field (int)
privacy bool
field (bool)

beacon_parse_bytes

XuAPI
pub fn beacon_parse_bytes(frame &string) Beacon

Purpose

Byte storage keeps a DMA snapshot small on targets whose int is wider than one byte. A string here is an opaque byte sequence, including embedded NUL.

Parameters

frame &string
frame (read-only borrow; caller keeps the original; type &string)

Returns

Beacon — a value of this type

beacon_parse

XuAPI
pub fn beacon_parse(frame &[]int) Beacon

Purpose

Convenience entry for protocol code using []int as bytes. Reject values outside a byte before converting; silently truncating them hides corruption.

Parameters

frame &[]int
frame (read-only borrow; caller keeps the original; type &[]int)

Returns

Beacon — a value of this type

const STA_IDLE

XuAPI
pub const STA_IDLE = 0

Purpose

Constant STA_IDLE, defining protocol or algorithm parameters.

const STA_READY

XuAPI
pub const STA_READY = 1

Purpose

Constant STA_READY, defining protocol or algorithm parameters.

const STA_AUTH_WAIT

XuAPI
pub const STA_AUTH_WAIT = 2

Purpose

Constant STA_AUTH_WAIT, defining protocol or algorithm parameters.

const STA_AUTHENTICATED

XuAPI
pub const STA_AUTHENTICATED = 3

Purpose

Constant STA_AUTHENTICATED, defining protocol or algorithm parameters.

const STA_ASSOC_WAIT

XuAPI
pub const STA_ASSOC_WAIT = 4

Purpose

Constant STA_ASSOC_WAIT, defining protocol or algorithm parameters.

const STA_ASSOCIATED

XuAPI
pub const STA_ASSOCIATED = 5

Purpose

Constant STA_ASSOCIATED, defining protocol or algorithm parameters.

const STA_REJECTED

XuAPI
pub const STA_REJECTED = 6

Purpose

Constant STA_REJECTED, defining protocol or algorithm parameters.

const STA_SECURITY_OPEN

XuAPI
pub const STA_SECURITY_OPEN = 0

Purpose

Constant STA_SECURITY_OPEN, defining protocol or algorithm parameters.

const STA_SECURITY_WPA2_PSK_CCMP

XuAPI
pub const STA_SECURITY_WPA2_PSK_CCMP = 2

Purpose

Constant STA_SECURITY_WPA2_PSK_CCMP, defining protocol or algorithm parameters.

struct StationAp

XuAPI
pub struct StationAp {
    pub valid bool
    pub ssid string
    pub bssid string
    pub channel int
    pub capability int
    pub rates []int // common legacy rates in units of 500kb/s; bit7 = basic
    pub security int
    pub rsn string // selected association-request RSN IE, including ID/length
}

Purpose

Structure encapsulating valid, ssid, bssid, channel, capability.

Public fields

valid bool
field (bool)
ssid string
field (string)
bssid string
field (string)
channel int
field (int)
capability int
field (int)
rates []int // common legacy rates in units of 500kb/s; bit7 = basic
field ([]int // common legacy rates in units of 500kb/s; bit7 = basic)
security int
field (int)
rsn string // selected association-request RSN IE, including ID/length
field (string // selected association-request RSN IE, including ID/length)

struct Station

XuAPI
pub struct Station {
    pub state int
    pub mac string
    pub ap StationAp
    pub sequence int // our management sequence counter, modulo 4096
    pub status_code int // last matched authentication/association status
    pub aid int // set only after a successful matched association response
}

Purpose

Structure encapsulating state, mac, ap, sequence, status_code.

Public fields

state int
field (int)
mac string
field (string)
ap StationAp
field (StationAp)
sequence int // our management sequence counter, modulo 4096
field (int // our management sequence counter, modulo 4096)
status_code int // last matched authentication/association status
field (int // last matched authentication/association status)
aid int // set only after a successful matched association response
field (int // set only after a successful matched association response)

station_ap_from_beacon

XuAPI
pub fn station_ap_from_beacon(frame &string, rx_channel int) StationAp

Purpose

A missing DS IE is allowed in a beacon, but selecting an AP needs the real receiver channel. A present DS IE must agree with it. Hidden SSIDs need an explicit probe/hidden-network policy and are not silently guessed here.

Parameters

frame &string
frame (read-only borrow; caller keeps the original; type &string)
rx_channel int
rx_channel (int)

Returns

StationAp — a value of this type

station_create

XuAPI
pub fn station_create(mac string, ap StationAp) Station

Purpose

Station create.

Parameters

mac string
mac (string)
ap StationAp
ap (StationAp)

Returns

Station — a value of this type

($&Station) authentication_request

XuAPI
pub fn (sta $&Station) authentication_request() string

Purpose

Operation on $&Station: authentication request.

Parameters

sta $&Station
The Station instance used by this call (exclusive borrow).

Returns

string — result string

($&Station) association_request

XuAPI
pub fn (sta $&Station) association_request() string

Purpose

Operation on $&Station: association request.

Parameters

sta $&Station
The Station instance used by this call (exclusive borrow).

Returns

string — result string

($&Station) receive_management

XuAPI
pub fn (sta $&Station) receive_management(frame &string) bool

Purpose

True means this complete response matched a pending transaction, including explicit AP rejection. False leaves state unchanged. AP sequence-control is its own counter; open authentication transaction sequence must instead be 2.

Parameters

sta $&Station
The Station instance used by this call (exclusive borrow).
frame &string
frame (read-only borrow; caller keeps the original; type &string)

Returns

bool — true or false

($&Station) reset_management

XuAPI
pub fn (sta $&Station) reset_management()

Purpose

Caller owns timeout/retry scheduling and hardware/key teardown.

Parameters

sta $&Station
The Station instance used by this call (exclusive borrow).

Returns

This call does not return a value.

station_ap_from_probe_response

XuAPI
pub fn station_ap_from_probe_response(frame &string, rx_channel int, receiver &string) StationAp

Purpose

Probe Responses carry the same fixed fields and IEs as beacons, but are directed to this station. Validate the original receiver first, then adapt an owned copy for the shared IE parser; the captured MPDU stays unchanged.

Parameters

frame &string
frame (read-only borrow; caller keeps the original; type &string)
rx_channel int
rx_channel (int)
receiver &string
receiver (read-only borrow; caller keeps the original; type &string)

Returns

StationAp — a value of this type

const WPA2_WAIT_M1

XuAPI
pub const WPA2_WAIT_M1 = 1

Purpose

Constant WPA2_WAIT_M1, defining protocol or algorithm parameters.

const WPA2_WAIT_M3

XuAPI
pub const WPA2_WAIT_M3 = 2

Purpose

Constant WPA2_WAIT_M3, defining protocol or algorithm parameters.

const WPA2_KEY_DATA_PENDING

XuAPI
pub const WPA2_KEY_DATA_PENDING = 3

Purpose

Constant WPA2_KEY_DATA_PENDING, defining protocol or algorithm parameters.

const WPA2_M4_READY

XuAPI
pub const WPA2_M4_READY = 4

Purpose

Constant WPA2_M4_READY, defining protocol or algorithm parameters.

wpa2_hmac_sha1

XuAPI
pub fn wpa2_hmac_sha1(key &string, data &string) string

Purpose

Raw 20-byte HMAC-SHA1 for WPA2 keys (at most 64 bytes) and bounded packets. Long HMAC keys are outside this protocol profile and are rejected explicitly.

Parameters

key &string
key (read-only borrow; caller keeps the original; type &string)
data &string
data (read-only borrow; caller keeps the original; type &string)

Returns

string — result string

wpa2_pmk

XuAPI
pub fn wpa2_pmk(passphrase &string, ssid &string) string

Purpose

PBKDF2-HMAC-SHA1(passphrase, SSID, 4096, 32). Input is the WPA passphrase form, not a raw 64-character PSK. Empty return means invalid input.

Parameters

passphrase &string
passphrase (read-only borrow; caller keeps the original; type &string)
ssid &string
ssid (read-only borrow; caller keeps the original; type &string)

Returns

string — result string

wpa2_ptk

XuAPI
pub fn wpa2_ptk(pmk &string, aa &string, spa &string, anonce &string, snonce &string) string

Purpose

PRF-512: KCK = bytes 0..15, KEK = 16..31, CCMP TK = 32..47. Last 16 bytes are not used by the CCMP profile. Peer MACs/nonces sort as unsigned octets; the counter begins at zero after label || NUL || context.

Parameters

pmk &string
pmk (read-only borrow; caller keeps the original; type &string)
aa &string
aa (read-only borrow; caller keeps the original; type &string)
spa &string
spa (read-only borrow; caller keeps the original; type &string)
anonce &string
anonce (read-only borrow; caller keeps the original; type &string)
snonce &string
snonce (read-only borrow; caller keeps the original; type &string)

Returns

string — result string

struct Wpa2Key

XuAPI
pub struct Wpa2Key {
    pub valid bool
    pub version int
    pub info int
    pub key_length int
    pub replay string
    pub nonce string
    pub mic string
    pub key_data string
}

Purpose

Structure encapsulating valid, version, info, key_length, replay.

Public fields

valid bool
field (bool)
version int
field (int)
info int
field (int)
key_length int
field (int)
replay string
field (string)
nonce string
field (string)
mic string
field (string)
key_data string
field (string)

wpa2_key_parse

XuAPI
pub fn wpa2_key_parse(frame &string) Wpa2Key

Purpose

Exact EAPOL length is required; callers strip Ethernet/Wi-Fi padding first. RSN key descriptor type2/version2 only: no WPA1/TKIP, PMF, SHA256 AKM or SAE.

Parameters

frame &string
frame (read-only borrow; caller keeps the original; type &string)

Returns

Wpa2Key — a value of this type

struct Wpa2Handshake

XuAPI
pub struct Wpa2Handshake {
    pub valid bool
    pub phase int
}

Purpose

Structure encapsulating valid, phase.

Public fields

valid bool
field (bool)
phase int
field (int)

struct Wpa2Step

XuAPI
pub struct Wpa2Step {
    pub valid bool
    pub transmit string
    pub validate_key_data bool
    pub key_data string
    pub kek string
    pub tk string
}

Purpose

Structure encapsulating valid, transmit, validate_key_data, key_data, kek.

Public fields

valid bool
field (bool)
transmit string
field (string)
validate_key_data bool
True once per transaction after MIC/nonce/replay verification. The caller must decrypt/validate key_data before installing TK/GTK. A retry does not request installation again (including after was generated).
key_data string
field (string)
kek string
field (string)
tk string
field (string)

wpa2_handshake_empty

XuAPI
pub fn wpa2_handshake_empty() Wpa2Handshake

Purpose

An invalid, allocation-free owner for a device that has not started a handshake. This also provides explicit teardown without parsing a frame.

Parameters

No arguments are required.

Returns

Wpa2Handshake — a value of this type

wpa2_handshake_start

XuAPI
pub fn wpa2_handshake_start(pmk &string, aa &string, spa &string, snonce &string, rsn_ie &string) Wpa2Handshake

Purpose

A fresh cryptographic 32-byte SNonce is supplied by the hardware owner on every new exchange. Reuse across reconnects is forbidden by this contract. rsn_ie must be the complete PSK/CCMP RSN IE sent in association (22 bytes).

Parameters

pmk &string
pmk (read-only borrow; caller keeps the original; type &string)
aa &string
aa (read-only borrow; caller keeps the original; type &string)
spa &string
spa (read-only borrow; caller keeps the original; type &string)
snonce &string
snonce (read-only borrow; caller keeps the original; type &string)
rsn_ie &string
rsn_ie (read-only borrow; caller keeps the original; type &string)

Returns

Wpa2Handshake — a value of this type

wpa2_handshake_receive

XuAPI
pub fn wpa2_handshake_receive(s $&Wpa2Handshake, frame &string) Wpa2Step

Purpose

Invalid/unrelated frames leave the exchange unchanged. A new after requires a caller-controlled reset with a fresh SNonce; it cannot silently replace an in-progress or installed PTK. Replay counters stay as 8 octets, so no 64-bit integer conversion can truncate them on ESP32.

Parameters

s $&Wpa2Handshake
s (exclusive borrow; may modify the original; type $&Wpa2Handshake)
frame &string
frame (read-only borrow; caller keeps the original; type &string)

Returns

Wpa2Step — a value of this type

wpa2_handshake_confirm_keys

XuAPI
pub fn wpa2_handshake_confirm_keys(s $&Wpa2Handshake, verified_m3 &string) string

Purpose

Call only after AES unwrap integrity, AP RSN consistency, GTK KDE bounds and key-install success have all been checked by the owner. This is an explicit integration boundary, not validation performed by this module. It generates once and retries the cached bytes without requesting any key reinstall.

Parameters

s $&Wpa2Handshake
s (exclusive borrow; may modify the original; type $&Wpa2Handshake)
verified_m3 &string
verified_m3 (read-only borrow; caller keeps the original; type &string)

Returns

string — result string