diff --git a/hostapd/accounting.c b/hostapd/accounting.c index d49c76523..c4c683d1e 100644 --- a/hostapd/accounting.c +++ b/hostapd/accounting.c @@ -225,6 +225,11 @@ static void accounting_interim_update(void *eloop_ctx, void *timeout_ctx) } +/** + * accounting_sta_start - Start STA accounting + * @hapd: hostapd BSS data + * @sta: The station + */ void accounting_sta_start(struct hostapd_data *hapd, struct sta_info *sta) { struct radius_msg *msg; @@ -363,6 +368,11 @@ static void accounting_sta_report(struct hostapd_data *hapd, } +/** + * accounting_sta_interim - Send a interim STA accounting report + * @hapd: hostapd BSS data + * @sta: The station + */ void accounting_sta_interim(struct hostapd_data *hapd, struct sta_info *sta) { if (sta->acct_session_started) @@ -370,6 +380,11 @@ void accounting_sta_interim(struct hostapd_data *hapd, struct sta_info *sta) } +/** + * accounting_sta_stop - Stop STA accounting + * @hapd: hostapd BSS data + * @sta: The station + */ void accounting_sta_stop(struct hostapd_data *hapd, struct sta_info *sta) { if (sta->acct_session_started) { @@ -396,7 +411,15 @@ static void accounting_sta_get_id(struct hostapd_data *hapd, } -/* Process the RADIUS frames from Accounting Server */ +/** + * accounting_receive - Process the RADIUS frames from Accounting Server + * @msg: RADIUS response message + * @req: RADIUS request message + * @shared_secret: RADIUS shared secret + * @shared_secret_len: Length of shared_secret in octets + * @data: Context data (struct hostapd_data *) + * Returns: Processing status + */ static RadiusRxResult accounting_receive(struct radius_msg *msg, struct radius_msg *req, u8 *shared_secret, size_t shared_secret_len, void *data) @@ -444,6 +467,11 @@ static void accounting_report_state(struct hostapd_data *hapd, int on) } +/** + * accounting_init: Initialize accounting + * @hapd: hostapd BSS data + * Returns: 0 on success, -1 on failure + */ int accounting_init(struct hostapd_data *hapd) { /* Acct-Session-Id should be unique over reboots. If reliable clock is @@ -460,6 +488,10 @@ int accounting_init(struct hostapd_data *hapd) } +/** + * accounting_deinit: Deinitilize accounting + * @hapd: hostapd BSS data + */ void accounting_deinit(struct hostapd_data *hapd) { accounting_report_state(hapd, 0); diff --git a/hostapd/config.c b/hostapd/config.c index f333d1d22..c760ee605 100644 --- a/hostapd/config.c +++ b/hostapd/config.c @@ -1377,6 +1377,11 @@ static int hostapd_config_ht_capab(struct hostapd_config *conf, #endif /* CONFIG_IEEE80211N */ +/** + * hostapd_config_read - Read and parse a configuration file + * @fname: Configuration file name (including path, if needed) + * Returns: Allocated configuration data structure + */ struct hostapd_config * hostapd_config_read(const char *fname) { struct hostapd_config *conf; @@ -2366,6 +2371,10 @@ static void hostapd_config_free_bss(struct hostapd_bss_config *conf) } +/** + * hostapd_config_free - Free hostapd configuration + * @conf: Configuration data from hostapd_config_read(). + */ void hostapd_config_free(struct hostapd_config *conf) { size_t i; @@ -2381,8 +2390,16 @@ void hostapd_config_free(struct hostapd_config *conf) } -/* Perform a binary search for given MAC address from a pre-sorted list. - * Returns 1 if address is in the list or 0 if not. */ +/** + * hostapd_maclist_found - Find a MAC address from a list + * @list: MAC address list + * @num_entries: Number of addresses in the list + * @addr: Address to search for + * @vlan_id: Buffer for returning VLAN ID or %NULL if not needed + * Returns: 1 if address is in the list or 0 if not. + * + * Perform a binary search for given MAC address from a pre-sorted list. + */ int hostapd_maclist_found(struct mac_acl_entry *list, int num_entries, const u8 *addr, int *vlan_id) { diff --git a/hostapd/developer.txt b/hostapd/developer.txt deleted file mode 100644 index e1d316341..000000000 --- a/hostapd/developer.txt +++ /dev/null @@ -1,219 +0,0 @@ -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] diff --git a/hostapd/eapol_sm.c b/hostapd/eapol_sm.c index 49a557a35..8e9d56c79 100644 --- a/hostapd/eapol_sm.c +++ b/hostapd/eapol_sm.c @@ -140,9 +140,14 @@ static void eapol_auth_tx_req(struct eapol_state_machine *sm) } -/* Port Timers state machine - implemented as a function that will be called - * once a second as a registered event loop timeout */ - +/** + * eapol_port_timers_tick - Port Timers state machine + * @eloop_ctx: struct eapol_state_machine * + * @timeout_ctx: Not used + * + * This statemachine is implemented as a function that will be called + * once a second as a registered event loop timeout. + */ static void eapol_port_timers_tick(void *eloop_ctx, void *timeout_ctx) { struct eapol_state_machine *state = timeout_ctx; @@ -941,6 +946,13 @@ static void eapol_sm_step_cb(void *eloop_ctx, void *timeout_ctx) } +/** + * eapol_auth_step - Advance EAPOL state machines + * @sm: EAPOL state machine + * + * This function is called to advance EAPOL state machines after any change + * that could affect their state. + */ void eapol_auth_step(struct eapol_state_machine *sm) { /* diff --git a/hostapd/hostapd.c b/hostapd/hostapd.c index 8f2ec4cb6..c94dbd7f5 100644 --- a/hostapd/hostapd.c +++ b/hostapd/hostapd.c @@ -281,6 +281,9 @@ static void hostapd_sim_db_cb(void *ctx, void *session_ctx) #endif /* EAP_SERVER */ +/** + * handle_term - SIGINT and SIGTERM handler to terminate hostapd process + */ static void handle_term(int sig, void *eloop_ctx, void *signal_ctx) { printf("Signal %d received - terminating\n", sig); @@ -384,6 +387,9 @@ int hostapd_reload_config(struct hostapd_iface *iface) #ifndef CONFIG_NATIVE_WINDOWS +/** + * handle_reload - SIGHUP handler to reload configuration + */ static void handle_reload(int sig, void *eloop_ctx, void *signal_ctx) { struct hapd_interfaces *hapds = (struct hapd_interfaces *) eloop_ctx; @@ -402,6 +408,9 @@ static void handle_reload(int sig, void *eloop_ctx, void *signal_ctx) #ifdef HOSTAPD_DUMP_STATE +/** + * hostapd_dump_state - SIGUSR1 handler to dump hostapd state to a text file + */ static void hostapd_dump_state(struct hostapd_data *hapd) { FILE *f; diff --git a/hostapd/iapp.c b/hostapd/iapp.c index 18f3b99e5..6d6dba8f7 100644 --- a/hostapd/iapp.c +++ b/hostapd/iapp.c @@ -13,7 +13,7 @@ * * Note: IEEE 802.11F-2003 was a experimental use specification. It has expired * and IEEE has withdrawn it. In other words, it is likely better to look at - * using some other mechanism for AP-to-AP communication than extenting the + * using some other mechanism for AP-to-AP communication than extending the * implementation here. */ @@ -238,6 +238,11 @@ static void iapp_send_layer2_update(struct iapp_data *iapp, u8 *addr) } +/** + * iapp_new_station - IAPP processing for a new STA + * @iapp: IAPP data + * @sta: The associated station + */ void iapp_new_station(struct iapp_data *iapp, struct sta_info *sta) { struct ieee80211_mgmt *assoc; @@ -306,6 +311,12 @@ static void iapp_process_add_notify(struct iapp_data *iapp, } +/** + * iapp_receive_udp - Process IAPP UDP frames + * @sock: File descriptor for the socket + * @eloop_ctx: IAPP data (struct iapp_data *) + * @sock_ctx: Not used + */ static void iapp_receive_udp(int sock, void *eloop_ctx, void *sock_ctx) { struct iapp_data *iapp = eloop_ctx; diff --git a/hostapd/ieee802_11.c b/hostapd/ieee802_11.c index 2109b23da..9e6485fcc 100644 --- a/hostapd/ieee802_11.c +++ b/hostapd/ieee802_11.c @@ -335,6 +335,12 @@ void ieee802_11_print_ssid(char *buf, const u8 *ssid, u8 len) } +/** + * ieee802_11_send_deauth - Send Deauthentication frame + * @hapd: hostapd BSS data + * @addr: Address of the destination STA + * @reason: Reason code for Deauthentication + */ void ieee802_11_send_deauth(struct hostapd_data *hapd, u8 *addr, u16 reason) { struct ieee80211_mgmt mgmt; @@ -1631,6 +1637,15 @@ static void handle_assoc_cb(struct hostapd_data *hapd, } +/** + * ieee802_11_mgmt_cb - Process management frame TX status callback + * @hapd: hostapd BSS data structure (the BSS from which the management frame + * was sent from) + * @buf: management frame data (starting from IEEE 802.11 header) + * @len: length of frame data in octets + * @stype: management frame subtype from frame control field + * @ok: Whether the frame was ACK'ed + */ void ieee802_11_mgmt_cb(struct hostapd_data *hapd, u8 *buf, size_t len, u16 stype, int ok) { diff --git a/hostapd/ieee802_11_auth.c b/hostapd/ieee802_11_auth.c index 2d63ff17e..bb88dd0e6 100644 --- a/hostapd/ieee802_11_auth.c +++ b/hostapd/ieee802_11_auth.c @@ -10,6 +10,11 @@ * license. * * See README and COPYING for more details. + * + * Access control list for IEEE 802.11 authentication can uses statically + * configured ACL from configuration files or an external RADIUS server. + * Results from external RADIUS queries are cached to allow faster + * authentication frame processing. */ #include "includes.h" @@ -193,6 +198,17 @@ static int hostapd_radius_acl_query(struct hostapd_data *hapd, const u8 *addr, } +/** + * hostapd_allowed_address - Check whether a specified STA can be authenticated + * @hapd: hostapd BSS data + * @addr: MAC address of the STA + * @msg: Authentication message + * @len: Length of msg in octets + * @session_timeout: Buffer for returning session timeout (from RADIUS) + * @acct_interim_interval: Buffer for returning account interval (from RADIUS) + * @vlan_id: Buffer for returning VLAN ID + * Returns: HOSTAPD_ACL_ACCEPT, HOSTAPD_ACL_REJECT, or HOSTAPD_ACL_PENDING + */ int hostapd_allowed_address(struct hostapd_data *hapd, const u8 *addr, const u8 *msg, size_t len, u32 *session_timeout, u32 *acct_interim_interval, int *vlan_id) @@ -337,6 +353,11 @@ static void hostapd_acl_expire_queries(struct hostapd_data *hapd, time_t now) } +/** + * hostapd_acl_expire - ACL cache expiration callback + * @eloop_ctx: struct hostapd_data * + * @timeout_ctx: Not used + */ static void hostapd_acl_expire(void *eloop_ctx, void *timeout_ctx) { struct hostapd_data *hapd = eloop_ctx; @@ -350,8 +371,16 @@ static void hostapd_acl_expire(void *eloop_ctx, void *timeout_ctx) } -/* Return 0 if RADIUS message was a reply to ACL query (and was processed here) - * or -1 if not. */ +/** + * hostapd_acl_recv_radius - Process incoming RADIUS Authentication messages + * @msg: RADIUS response message + * @req: RADIUS request message + * @shared_secret: RADIUS shared secret + * @shared_secret_len: Length of shared_secret in octets + * @data: Context data (struct hostapd_data *) + * Returns: RADIUS_RX_PROCESSED if RADIUS message was a reply to ACL query (and + * was processed here) or RADIUS_RX_UNKNOWN if not. + */ static RadiusRxResult hostapd_acl_recv_radius(struct radius_msg *msg, struct radius_msg *req, u8 *shared_secret, size_t shared_secret_len, @@ -443,6 +472,11 @@ hostapd_acl_recv_radius(struct radius_msg *msg, struct radius_msg *req, } +/** + * hostapd_acl_init: Initialize IEEE 802.11 ACL + * @hapd: hostapd BSS data + * Returns: 0 on success, -1 on failure + */ int hostapd_acl_init(struct hostapd_data *hapd) { if (radius_client_register(hapd->radius, RADIUS_AUTH, @@ -455,6 +489,10 @@ int hostapd_acl_init(struct hostapd_data *hapd) } +/** + * hostapd_acl_deinit - Deinitialize IEEE 802.11 ACL + * @hapd: hostapd BSS data + */ void hostapd_acl_deinit(struct hostapd_data *hapd) { struct hostapd_acl_query_data *query, *prev; diff --git a/hostapd/ieee802_1x.c b/hostapd/ieee802_1x.c index 350c54229..5b5458dfa 100644 --- a/hostapd/ieee802_1x.c +++ b/hostapd/ieee802_1x.c @@ -647,7 +647,15 @@ static void handle_eap(struct hostapd_data *hapd, struct sta_info *sta, } -/* Process the EAPOL frames from the Supplicant */ +/** + * ieee802_1x_receive - Process the EAPOL frames from the Supplicant + * @hapd: hostapd BSS data + * @sa: Source address (sender of the EAPOL frame) + * @buf: EAPOL frame + * @len: Length of buf in octets + * + * This function is called for each incoming EAPOL frame from the interface + */ void ieee802_1x_receive(struct hostapd_data *hapd, const u8 *sa, const u8 *buf, size_t len) { @@ -796,6 +804,14 @@ void ieee802_1x_receive(struct hostapd_data *hapd, const u8 *sa, const u8 *buf, } +/** + * ieee802_1x_new_station - Start IEEE 802.1X authentication + * @hapd: hostapd BSS data + * @sta: The station + * + * This function is called to start IEEE 802.1X authentication when a new + * station completes IEEE 802.11 association. + */ void ieee802_1x_new_station(struct hostapd_data *hapd, struct sta_info *sta) { struct rsn_pmksa_cache_entry *pmksa; @@ -1186,7 +1202,15 @@ ieee802_1x_search_radius_identifier(struct hostapd_data *hapd, u8 identifier) } -/* Process the RADIUS frames from Authentication Server */ +/** + * ieee802_1x_receive_auth - Process RADIUS frames from Authentication Server + * @msg: RADIUS response message + * @req: RADIUS request message + * @shared_secret: RADIUS shared secret + * @shared_secret_len: Length of shared_secret in octets + * @data: Context data (struct hostapd_data *) + * Returns: Processing status + */ static RadiusRxResult ieee802_1x_receive_auth(struct radius_msg *msg, struct radius_msg *req, u8 *shared_secret, size_t shared_secret_len, diff --git a/hostapd/sta_info.c b/hostapd/sta_info.c index 55745e85e..bd873f6e2 100644 --- a/hostapd/sta_info.c +++ b/hostapd/sta_info.c @@ -219,6 +219,14 @@ void hostapd_free_stas(struct hostapd_data *hapd) } +/** + * ap_handle_timer - Per STA timer handler + * @eloop_ctx: struct hostapd_data * + * @timeout_ctx: struct sta_info * + * + * This function is called to check station activity and to remove inactive + * stations. + */ void ap_handle_timer(void *eloop_ctx, void *timeout_ctx) { struct hostapd_data *hapd = eloop_ctx; diff --git a/src/common/ieee802_11_common.c b/src/common/ieee802_11_common.c index c9f47022c..682d61b13 100644 --- a/src/common/ieee802_11_common.c +++ b/src/common/ieee802_11_common.c @@ -116,6 +116,14 @@ static int ieee802_11_parse_vendor_specific(u8 *pos, size_t elen, } +/** + * ieee802_11_parse_elems - Parse information elements in management frames + * @start: Pointer to the start of IEs + * @len: Length of IE buffer in octets + * @elems: Data structure for parsed elements + * @show_errors: Whether to show parsing errors in debug log + * Returns: Parsing result + */ ParseRes ieee802_11_parse_elems(u8 *start, size_t len, struct ieee802_11_elems *elems, int show_errors)