Skip to content

Add WPA2-Enterprise (PEAP/MSCHAPv2) support - #288

Open
dantdmdarealguy wants to merge 1 commit into
OpenIntelWireless:masterfrom
dantdmdarealguy:wpa2-enterprise
Open

dantdmdarealguy wants to merge 1 commit into
OpenIntelWireless:masterfrom
dantdmdarealguy:wpa2-enterprise

Conversation

@dantdmdarealguy

Copy link
Copy Markdown

Closes: #4 · Requires: OpenIntelWireless/itlwm#1075. Older kexts don't have the new ioctls; HeliPort detects that and asks the user to update itlwm.

Summary

Adds a userspace 802.1X supplicant so HeliPort can join WPA2-Enterprise networks
with itlwm. All EAP, TLS and certificate handling happens here; the kext only
relays EAPOL frames and installs the derived PMK (see the itlwm PR, OpenIntelWireless/itlwm#1075).

How it works

  • EAP engine: vendored hostap eap_peer with its internal TLS implementation
    (EAPCore/, BSD license, no OpenSSL), driven by a small RFC 4137 lower layer
    (EAPSupplicantBridge.c). PEAPv0 outer, MSCHAPv2 inner; other methods are NAK'd.
  • Certificate trust (trust on first use): the first connection to an SSID runs a
    probe-only TLS handshake that aborts right after the server certificate, so no
    credentials are sent. HeliPort shows the subject and SHA-256 fingerprint; on
    Trust it pins the certificate per SSID. Later connections verify the pin inside
    hostap (hash://server/sha256/…) before phase 2, so credentials only ever go to
    the pinned certificate. A changed certificate is reported as such and the attempt
    fails. Forgetting the network also removes its pin.
  • Transport: EAPOL frames move between HeliPort and itlwm through new
    user-client ioctls (RX_EAPOL / TX_EAPOL).
    • itlwm queues incoming frames, so HeliPort polls: every 10 ms during an
      exchange, every 250 ms otherwise (enough to catch an AP-initiated reauth).
    • No privileged helper and no extra entitlements; unsigned CI builds work.
    • Unsigned builds still work, but Keychain "Always Allow" doesn't stick for a
      completely unsigned app, so the release zip is ad-hoc signed.
  • Credentials are stored in the Keychain via the existing CredentialsManager;
    "Remember this network" and auto-join work as for personal networks. The PMK
    buffer handed to itlwm is wiped with memset_s afterwards.
  • Reauthentication: after connecting, HeliPort keeps answering EAP requests on
    the same association (periodic reauth, session timeouts), including after a
    HeliPort relaunch while still connected (credentials restored from the Keychain).

Other fixes

  • ClientKit: get_platform_info() built driver_version + " " + fw_version with
    strcpy/strcat into a 32-byte field and could overflow the caller's stack.
  • WiFiConfigWindow: the Join button checked the username box's own visibility
    instead of its grid row, the username box had no delegate, and enterprise
    passwords were truncated to 64 / required ≥ 8 characters (WPA passphrase rules).

UI

  • Enterprise security types show the username field; the trust prompt appears on
    first connect.

Prebuilt binaries

Until this is merged, an unofficial prebuilt itlwm.kext + HeliPort.app built from these PRs is on my fork's releases page: https://github.com/dantdmdarealguy/itlwm/releases. The two only work together, and only with itlwm (not AirportItlwm).

Testing

  • macOS 15.7.7, Intel Wireless-AC 9560, itlwm from Add 802.1X (WPA2-Enterprise) support for a userspace supplicant itlwm#1075.
  • Texas A&M TAMU_WiFi (PEAP/MSCHAPv2): first connect with certificate prompt,
    repeat connect with pinned certificate, Remember + auto-join at login,
    reauthentication (notifyutil -p org.openintelwireless.HeliPort.debug.reauth
    triggers one for testing).
  • SwiftLint: no new violations; it reports the same 8 warnings as master, from
    a rule newer SwiftLint versions add. The CI build commands (Debug and Release,
    unsigned) succeed.

Limitations / follow-ups

  • PEAP/MSCHAPv2 only (no EAP-TLS/TTLS, no WPA3-Enterprise). No UI to view or reset
    a pinned certificate yet (forgetting the network clears it).
  • Brief outage on reauthentication. After a reauth, one AP ran a second EAP
    exchange about 3 s later, and connectivity dropped for about 1.4 s (see the itlwm
    PR).
  • Tested on one network so far. Reports from other enterprise networks are welcome.
  • EAPVerboseLogging (defaults) enables hostap debug logging; it includes
    credential-derived hexdumps, so it is off by default.

Adds a userspace 802.1X supplicant so HeliPort can join WPA2-Enterprise
networks with itlwm. All EAP, TLS and certificate handling is here; itlwm
only relays EAPOL frames and installs the derived PMK.

- EAP engine: vendored hostap eap_peer with its internal TLS client
  (EAPCore/, BSD, no OpenSSL), driven by a small RFC 4137 lower layer
  (EAPSupplicantBridge.c). PEAPv0 outer, MSCHAPv2 inner.
- Server certificate trust on first use: the first connection to an SSID
  runs a probe-only TLS handshake that stops after the server certificate,
  so no credentials are sent. The user checks the subject and SHA-256
  fingerprint and pins it; later connections verify the pin in hostap
  before phase 2 and report a changed certificate. Forgetting the network
  removes its pin.
- EAPOL frames move through itlwm's RX_EAPOL / TX_EAPOL user-client calls,
  so no privileged helper or extra entitlements are needed and unsigned
  builds work. Older itlwm builds are detected and the user is told to
  update.
- Credentials in the Keychain; Remember / auto-join work as for personal
  networks. Reauthentication is answered on the established association,
  also after a HeliPort relaunch.
- Fix a stack overflow in get_platform_info() (strcat into a 32-byte
  field), and Join-button and credential validation in WiFiConfigWindow
  for enterprise networks.

For testing reauthentication:
notifyutil -p org.openintelwireless.HeliPort.debug.reauth

Closes OpenIntelWireless#4.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Development

Successfully merging this pull request may close these issues.

1 participant