SAE provides secure password-based authentication for 802.11. This reference implementation is written with an OS-specific component which manages the wireless interface and communicates with the host OS, and an OS-independent component which implements the SAE protocol.
The OS-specific components reside in directories named for their respective OS, for example the freebsd OS-specific component is in freebsd/meshd.c. The OS-independent component is sae.c. The other .c files are helper modules. See PORTING for a description of the interfaces the modules have to each other.
Multiple meshd applications can communicate over a loopback interface to simulate a wireless mesh. Each OS-specific component supports communication over the loopback interface.
A monitor application, mon, can be used to sniff interfaces for SAE traffic and provide pithy output.
Only elliptic curves defined over a prime field are supported-- i.e. no characteristic two curves and no prime modulus groups. Therefore the only groups currently supported are 19, 20, 21, 25 and 26 from the IANA registry of RFC 2409's "Diffie-Hellman groups".
meshd currently only supports Atheros radios.
libcrypto from OpenSSL, version 0.9.8 or later. Basically, all you need is EC support that has the pre-defined groups.
On Linux, the following dependencies are required (relative to a base Ubuntu 18.04.1 LTS image):
sudo apt install gcc make cmake pkg-config libssl-dev libconfig-dev libnl-3-dev libnl-genl-3-dev
make all
The file freebsd_6.4_RC1_diffs contains patches for a few kernel files in freebsd 6.4_RC1 (other versions should be straightforward to patch as the diffs are minor) to allow for the sending of 802.11 authentication frames via a BPF. Rebuild the OS with these patches.
Edit the Makefile to point $(LIBS) to OpenSSL and make.
tests/run_tests.sh
Note that tests/test003.sh requires a kernel patch for certain versions -
see the comment in the file for details.
Configuration of sae and meshd are done with sae.conf and meshd.conf, respectively, in the config directory. These files contain attribute and value pairs in the form: attribute=value
One attribute supports a prioritized list of values in the form of a value list: attribute=value1 value2 value3 ...
Lines beginning with '#' are treated as comments and ignored.
Attributes for sae.conf are:
group: a prioritized list of groups to support. This is
the only attribute that supports a value-list.
There is no default.
password: the password to use for authentication. There is
no default.
retrans: the amount of seconds to wait before retransmitting.
Default is 3.
thresh: the number of open connections allowed before
anti-clogging tokens are demanded. Default is 5.
blacklist: how long to ignore peers which fail authentication.
Default is 30.
debug: a bitmask to selectively enable/disable debugging.
error debugging is bit 0x01, protocol messaging is bit
0x02, state machine transitions are bit 0x04,
crypto debugging is bit 0x08, and very verbose crypto
debugging can be turned on with bit 0x10.
lifetime: how long a negotiated PMK is valid for. At then end
of this period the key will be deleted and the peer
will be authenticated again (if it's still around).
giveup: the number of errors and/or state-machine resyncronizations
allowed before the conversation is abandoned. Default
is 5.
Attributes for meshd.conf are:
interface: the name of the wireless interface to use.
Default is "ath0".
ssid: the ssid to beacon. Default is "meshd".
passive: whether meshd will initiate (0) an SAE connection
or wait (1) until initiated to. Default is 0.
debug: when set to 1 sends more information to stdout.
Default is 0.
mediaopt: the media selection option for the wireless interface.
Values are 0 for STA; 1 for ADHOC; 2 for HOSTAP; and,
3 for MONITOR. Default is ADHOC.
band: which radio band to use, "11a", "11b", or "11g". Default
is 11b.
channel: which channel to use in the defined band. Default
is 6.
mcast-rate: set multicast/broadcast transmission rate. Default is
1Mbps for 2.4GHz or 6Mbps for 5GHz
beacon-interval: set beacon interval in TUs.
path-refresh-time: set mesh parameter mesh_path_refresh_path
min-discovery-timeout: set mesh parameter mesh_min_discovery_timeout
gate-annoucements: set mesh parameter mesh_gate_annoucements
hwmp-active-path-timeout: set mesh parameter mesh_active_path_timeout
hwmp-net-diameter-traversal-time: set mesh parameter mesh_hwmp_diameter_traversal_time
hwmp-rootmode: set mesh parameter mesh_hwmp_rootmode
hwmp-rann-interval: set mesh parameter mesh_hwmp_rann_interval
hwmp-active-path-to-root-timeout: set mesh parameter mesh_hwmp_active_path_to_root_timeout
hwmp-root-interval; set mesh parameter mesh_hwmp_root_interval
meshd MUST be run as root. After it's built just run it. If a beacon advertising the configured ssid is received meshd will attempt SAE authentication to the sender. If the sender is configured in a compatible fashion authentication will happen. When run over the loopback interface meshd will generate a random BSSID and begin sending pseudo-beacons over the loopback interface. When another meshd module connects to the loopback authentication will commense.
Note: a mediaopt of HOSTAP will prevent beacons from being received by meshd. A mediaopt of STA will not result in beacons being sent out the radio. It is possible to configure two mesh points to not see each other or to ignore each other.
This implementation is based version 8.01 of IEEE 802.11s. The specification is pretty stable but it may change before final ratification.
