Home /Modules/docs/wifi-common.md

wifi-common.md

docs/modules/explanations/wifi-common.md · 89 line(s) · markdown

<img align="right" src="../../../images/sleela/sleela-medium-profile-permanent-icon-002.jpg" width="45" height="45" alt="SLeeLa">

wifi-common: Explanation

Natureprotocol (bin/sleelactl help wifi-common: verbs negotiate grade simulate validate info)
Registry summaryShared Wi-Fi contracts
Lives inwifi-common/ (include/sleela_wifi/, src/, tests/, Makefile, README.md, SECURITY.md)
Writeup typeExplanation, because its real purpose (scan, connect, disconnect through the OS Wi-Fi stack) cannot be operated in this sandbox: there is no nmcli, so only the policy core and its contract tests run.
Verified2026-11-13 against master e048707fd: make test passes; all five source variants compile; a scratch program driving the policy core with a fake backend gave the results below; the real backend fails with sh: nmcli: command not found.

What it is

A client-side Wi-Fi control layer shared by the Wi-Fi 4, 5 and 6 modules. It offers a C ABI and a C++17 wrapper to scan, pick a result, apply a fail-closed security policy, request a connection and disconnect. The README says it is "not an 802.11 PHY/MAC implementation or monitor-mode packet sniffer" (wifi-common/README.md). It does not model any IEEE amendment. The design (policy struct, rank scale, "latest scan must match" rule, provider contract) is this project's own. The actual radio work is delegated to the OS: NetworkManager's nmcli on Linux, the Native Wi-Fi API on Windows, CoreWLAN on macOS.

How it works

The core is src/wifi_manager.c (226 lines) around a wifi_manager_t that holds a backend (wifi_backend_t: name, scan, connect, disconnect function pointers), a policy and the last scan (up to WIFI_MAX_SCAN_RESULTS = 128 entries).

  1. Init (wifi_manager_init): rejects NULL backend or missing callbacks; copies the given policy or the default; rejects a policy whose flags are not 0/1 or whose rank is outside 0..5.
  2. Scan (wifi_manager_scan): clears the cache, calls the backend, drops entries that fail valid_network (empty or control-character SSID, malformed 17-character BSSID, signal over 100, unknown security), and stores the rest. Returns BUFFER_TOO_SMALL when the caller's array is smaller than the number kept.
  3. Select (wifi_manager_select): copies entry index out of the cache.
  4. Connect (wifi_manager_connect): the network passed in must match a cached scan entry on SSID, case-insensitive BSSID and security, else NETWORK_NOT_FOUND (this blocks forged or stale selections). Then policy checks, then per-auth-mode argument checks, then the backend call.
  5. Disconnect: forwards to the backend.

Security ranks (wifi_security_rank): Open 0, WEP 1, WPA 3, WPA2 and OWE 4, WPA3 5, unknown -1. Default policy: minimum rank 4, no open networks, no WEP, enterprise TLS validation required, protected management frames (PMF) not required.

Observed with a fake backend (scratch program, not kept; the core compiled from src/wifi_manager.c):

CaseResult
WPA2-Personal, OS-managed auth, default policyok
WPA-Personal / WEP / Open, default policyblocked by Wi-Fi security policy
OWE, default policyok
WPA2-Personal with 5-byte passphraseinvalid argument
WPA2-Personal with 14-byte passphraseok
WPA2-Enterprise, user+password but no CA file / server nameblocked by Wi-Fi security policy
WPA2-Enterprise with CA file and server nameok
PMF required, scan reports PMF unknown (-1)blocked by Wi-Fi security policy
PMF required, scan reports PMF yesok

Passphrase rules in code: 8..63 bytes, or exactly 64 hex digits as a raw PSK (rejected for WPA3-Personal).

Providers

ProviderHow it works (from the source)
wifi_backend_nmcli.c (Linux)Scan runs the constant command nmcli --terse --escape yes --fields SSID,BSSID,CHAN,SIGNAL,SECURITY,IN-USE device wifi list --rescan yes through popen. Connect uses fork/execvp with an argument vector (no shell). Passphrase and enterprise-password modes return AUTH_REQUIRED: secrets never go on a command line. It sets protected_management_frames = -1 always, so a policy requiring PMF can never connect on Linux. It never sets frequency_mhz.
wifi_backend_windows.c (327 lines)Native Wi-Fi API. Not compiled or run here (no Windows SDK).
wifi_backend_macos.mm (98 lines)CoreWLAN. Not compiled or run here. It sets frequency_mhz = 0.
wifi_backend_unavailable.cEvery call returns BACKEND_UNAVAILABLE. Compiled here without error.

Only one provider file is linked into a build; each defines wifi_backend_default().

Where it lives

FileRole
include/sleela_wifi/wifi_manager.hC ABI: types, status codes, policy defaults, function list
include/sleela_wifi/wifi_manager_cpp.hpp, src/wifi_manager_cpp.cppC++17 sleela::wifi::Manager, Network, Credentials (best-effort zeroing of strings on destruction)
src/wifi_manager.cPolicy, validation, selection
src/wifi_backend_*.c / .mmOS providers listed above
tests/test_wifi_manager.cContract tests with a fake backend
Makefileall (archive), test, clean
SECURITY.mdDefaults, authorized red/blue team guidance

Status and limits

Evidence from commands run:

Sources

Read: wifi-common/README.md, SECURITY.md, Makefile, include/sleela_wifi/wifi_manager.h, wifi_manager_cpp.hpp, src/wifi_manager.c, src/wifi_backend_nmcli.c, src/wifi_backend_unavailable.c, src/wifi_manager_cpp.cpp, tests/test_wifi_manager.c; line counts only for the Windows and macOS providers; bin/sleelactl.d/registry.conf (line 58). Run: make test, make, nm libsleela_wifi.a, manual compiles of the nmcli/unavailable/C++ sources, a scratch policy program in /tmp, bin/sleelactl info|validate|negotiate|grade|simulate wifi-common, the example programs of wi-fi-4/5/6.