#embedded/wifi
Xu 0.13.1 API
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
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
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
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
Purpose
Constant STA_IDLE, defining protocol or algorithm parameters.
const STA_READY
Purpose
Constant STA_READY, defining protocol or algorithm parameters.
const STA_AUTH_WAIT
pub const STA_AUTH_WAIT = 2
Purpose
Constant STA_AUTH_WAIT, defining protocol or algorithm parameters.
const STA_AUTHENTICATED
pub const STA_AUTHENTICATED = 3
Purpose
Constant STA_AUTHENTICATED, defining protocol or algorithm parameters.
const STA_ASSOC_WAIT
pub const STA_ASSOC_WAIT = 4
Purpose
Constant STA_ASSOC_WAIT, defining protocol or algorithm parameters.
const STA_ASSOCIATED
pub const STA_ASSOCIATED = 5
Purpose
Constant STA_ASSOCIATED, defining protocol or algorithm parameters.
const STA_REJECTED
pub const STA_REJECTED = 6
Purpose
Constant STA_REJECTED, defining protocol or algorithm parameters.
const STA_SECURITY_OPEN
pub const STA_SECURITY_OPEN = 0
Purpose
Constant STA_SECURITY_OPEN, defining protocol or algorithm parameters.
const STA_SECURITY_WPA2_PSK_CCMP
pub const STA_SECURITY_WPA2_PSK_CCMP = 2
Purpose
Constant STA_SECURITY_WPA2_PSK_CCMP, defining protocol or algorithm parameters.
struct StationAp
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
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
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
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
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
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
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
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
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
pub const WPA2_WAIT_M1 = 1
Purpose
Constant WPA2_WAIT_M1, defining protocol or algorithm parameters.
const WPA2_WAIT_M3
pub const WPA2_WAIT_M3 = 2
Purpose
Constant WPA2_WAIT_M3, defining protocol or algorithm parameters.
const WPA2_KEY_DATA_PENDING
pub const WPA2_KEY_DATA_PENDING = 3
Purpose
Constant WPA2_KEY_DATA_PENDING, defining protocol or algorithm parameters.
const WPA2_M4_READY
pub const WPA2_M4_READY = 4
Purpose
Constant WPA2_M4_READY, defining protocol or algorithm parameters.
wpa2_hmac_sha1
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
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
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
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
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
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
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
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
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
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
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