freebsd-nq/contrib/hostapd/developer.txt

Developer notes for hostapd
===========================

hostapd daemon setup, operations, and shutdown
----------------------------------------------

Files: hostapd.[ch]

Externally called functions:
  hostapd_new_assoc_sta() is called when a station associates with the AP

Event loop functions:
  handle_term() is called on SIGINT and SIGTERM to terminate hostapd process
  handle_reload() is called on SIGHUP to reload configuration
  handle_dump_state() is called on SIGUSR1 to dump station state data to a
	text file
  hostapd_rotate_wep() is called to periodically change WEP keys


Configuration parsing
---------------------

Configuration file parsing and data structure definition.

Files: config.[ch]

Externally called functions:
  hostapd_config_read() is called to read and parse a configuration file;
	allocates and returns configuration data structure
  hostapd_config_free() is called to free configuration data structure
  hostapd_maclist_found() is called to check whether a given address is found
	in a list of MAC addresses


Kernel driver access
--------------------

Helper functions for configuring the Host AP kernel driver and
accessing data from it.

Files: driver.[ch]


IEEE 802.11 frame handling (netdevice wlan#ap)
----------------------------------------------

Receive all incoming IEEE 802.11 frames from the kernel driver via
wlan#ap interface.

Files: receive.c

Externally called functions:
  hostapd_init_sockets() is called to initialize sockets for receiving and
	sending IEEE 802.11 frames via wlan#ap interface

Event loop functions:
  handle_read() is called for each incoming packet from wlan#ap net device


Station table
-------------

Files: sta_info.[ch], ap.h

Event loop functions:
  ap_handle_timer() is called to check station activity and to remove
	inactive stations


IEEE 802.11 management
----------------------

IEEE 802.11 management frame sending and processing (mainly,
authentication and association). IEEE 802.11 station functionality
(authenticate and associate with another AP as an station).

Files: ieee802_11.[ch]

Externally called functions:
  ieee802_11_mgmt() is called for each received IEEE 802.11 management frame
	(from handle_frame() in hostapd.c)
  ieee802_11_mgmt_cb() is called for each received TX callback of IEEE 802.11
	management frame (from handle_tx_callback() in hostapd.c)
  ieee802_11_send_deauth() is called to send deauthentication frame
  ieee802_11_send_disassoc() is called to send disassociation frame
  ieee802_11_parse_elems() is used to parse information elements in
	IEEE 802.11 management frames

Event loop functions:
  ieee802_11_sta_authenticate() called to retry authentication (with another
	AP)
  ieee802_11_sta_associate() called to retry association (with another AP)


IEEE 802.11 authentication
--------------------------

Access control list for IEEE 802.11 authentication. Uses staticly
configured ACL from configuration files or an external RADIUS
server. Results from external RADIUS queries are cached to allow
faster authentication frame processing.

Files: ieee802_11_auth.[ch]

Externally called functions:
  hostapd_acl_init() called once during hostapd startup
  hostapd_acl_deinit() called once during hostapd shutdown
  hostapd_acl_recv_radius() called by IEEE 802.1X code for incoming RADIUS
	Authentication messages (returns 0 if message was processed)
  hostapd_allowed_address() called to check whether a specified station can be
	authenticated

Event loop functions:
  hostapd_acl_expire() is called to expire ACL cache entries


IEEE 802.1X Authenticator
-------------------------

Files: ieee802_1x.[ch]


Externally called functions:
  ieee802_1x_receive() is called for each incoming EAPOL frame from the
	wireless interface
  ieee802_1x_new_station() is called to start IEEE 802.1X authentication when
	a new station completes IEEE 802.11 association

Event loop functions:
  ieee802_1x_receive_auth() called for each incoming RADIUS Authentication
	message


EAPOL state machine
-------------------

IEEE 802.1X state machine for EAPOL.

Files: eapol_sm.[ch]

Externally called functions:
  eapol_sm_step() is called to advance EAPOL state machines after any change
	that could affect their state

Event loop functions:
  eapol_port_timers_tick() called once per second to advance Port Timers state
	machine


IEEE 802.11f (IAPP)
-------------------

Files: iapp.[ch]

Externally called functions:
  iapp_new_station() is called to start accounting session when a new station
	completes IEEE 802.11 association or IEEE 802.1X authentication

Event loop functions:
  iapp_receive_udp() is called for incoming IAPP frames over UDP


Per station accounting
----------------------

Send RADIUS Accounting start and stop messages to a RADIUS Accounting
server. Process incoming RADIUS Accounting messages.

Files: accounting.[ch]

Externally called functions:
  accounting_init() called once during hostapd startup
  accounting_deinit() called once during hostapd shutdown
  accounting_sta_start() called when a station starts new session
  accounting_sta_stop() called when a station session is terminated

Event loop functions:
  accounting_receive() called for each incoming RADIUS Accounting message
  accounting_list_timer() called to retransmit accounting messages and to
	remove expired entries


RADIUS messages
---------------

RADIUS message generation and parsing functions.

Files: radius.[ch]


Event loop
----------

Event loop for registering timeout calls, signal handlers, and socket
read events.

Files: eloop.[ch]


RC4
---

RC4 encryption

Files: rc4.[ch]


MD5
---

MD5 hash and HMAC-MD5.

Files: md5.[ch]


Miscellaneous helper functions
------------------------------

Files: common.[ch]