Import of WPA supplicant 0.4.8

1 files changed, 214 insertions, 21 deletions

diff --git a/contrib/wpa_supplicant/wpa_supplicant.h b/contrib/wpa_supplicant/wpa_supplicant.h
index e5ad182..e7e6f0d 100644
--- a/contrib/wpa_supplicant/wpa_supplicant.h
+++ b/contrib/wpa_supplicant/wpa_supplicant.h
@@ -1,3 +1,17 @@
+/*
+ * wpa_supplicant - Exported functions for wpa_supplicant modules
+ * Copyright (c) 2003-2005, Jouni Malinen <jkmaline@cc.hut.fi>
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation.
+ *
+ * Alternatively, this software may be distributed under the terms of BSD
+ * license.
+ *
+ * See README and COPYING for more details.
+ */
+
 #ifndef WPA_SUPPLICANT_H
 #define WPA_SUPPLICANT_H
 
@@ -6,21 +20,164 @@
  */
 struct wpa_supplicant;
 
-typedef enum {
-	EVENT_ASSOC, EVENT_DISASSOC, EVENT_MICHAEL_MIC_FAILURE,
-	EVENT_SCAN_RESULTS, EVENT_ASSOCINFO, EVENT_INTERFACE_STATUS,
+/**
+ * enum wpa_event_type - Event type for wpa_supplicant_event() calls
+ */
+typedef enum wpa_event_type {
+	/**
+	 * EVENT_ASSOC - Association completed
+	 *
+	 * This event needs to be delivered when the driver completes IEEE
+	 * 802.11 association or reassociation successfully.
+	 * wpa_driver_ops::get_bssid() is expected to provide the current BSSID
+	 * after this even has been generated. In addition, optional
+	 * EVENT_ASSOCINFO may be generated just before EVENT_ASSOC to provide
+	 * more information about the association. If the driver interface gets
+	 * both of these events at the same time, it can also include the
+	 * assoc_info data in EVENT_ASSOC call.
+	 */
+	EVENT_ASSOC,
+
+	/**
+	 * EVENT_DISASSOC - Association lost
+	 *
+	 * This event should be called when association is lost either due to
+	 * receiving deauthenticate or disassociate frame from the AP or when
+	 * sending either of these frames to the current AP.
+	 */
+	EVENT_DISASSOC,
+
+	/**
+	 * EVENT_MICHAEL_MIC_FAILURE - Michael MIC (TKIP) detected
+	 *
+	 * This event must be delivered when a Michael MIC error is detected by
+	 * the local driver. Additional data is for event processing is
+	 * provided with union wpa_event_data::michael_mic_failure. This
+	 * information is used to request new encyption key and to initiate
+	 * TKIP countermeasures if needed.
+	 */
+	EVENT_MICHAEL_MIC_FAILURE,
+
+	/**
+	 * EVENT_SCAN_RESULTS - Scan results available
+	 *
+	 * This event must be called whenever scan results are available to be
+	 * fetched with struct wpa_driver_ops::get_scan_results(). This event
+	 * is expected to be used some time after struct wpa_driver_ops::scan()
+	 * is called. If the driver provides an unsolicited event when the scan
+	 * has been completed, this event can be used to trigger
+	 * EVENT_SCAN_RESULTS call. If such event is not available from the
+	 * driver, the driver wrapper code is expected to use a registered
+	 * timeout to generate EVENT_SCAN_RESULTS call after the time that the
+	 * scan is expected to be completed.
+	 */
+	EVENT_SCAN_RESULTS,
+
+	/**
+	 * EVENT_ASSOCINFO - Report optional extra information for association
+	 *
+	 * This event can be used to report extra association information for
+	 * EVENT_ASSOC processing. This extra information includes IEs from
+	 * association frames and Beacon/Probe Response frames in union
+	 * wpa_event_data::assoc_info. EVENT_ASSOCINFO must be send just before
+	 * EVENT_ASSOC. Alternatively, the driver interface can include
+	 * assoc_info data in the EVENT_ASSOC call if it has all the
+	 * information available at the same point.
+	 */
+	EVENT_ASSOCINFO,
+
+	/**
+	 * EVENT_INTERFACE_STATUS - Report interface status changes
+	 *
+	 * This optional event can be used to report changes in interface
+	 * status (interface added/removed) using union
+	 * wpa_event_data::interface_status. This can be used to trigger
+	 * wpa_supplicant to stop and re-start processing for the interface,
+	 * e.g., when a cardbus card is ejected/inserted.
+	 */
+	EVENT_INTERFACE_STATUS,
+
+	/**
+	 * EVENT_PMKID_CANDIDATE - Report a candidate AP for pre-authentication
+	 *
+	 * This event can be used to inform wpa_supplicant about candidates for
+	 * RSN (WPA2) pre-authentication. If wpa_supplicant is not responsible
+	 * for scan request (ap_scan=2 mode), this event is required for
+	 * pre-authentication. If wpa_supplicant is performing scan request
+	 * (ap_scan=1), this event is optional since scan results can be used
+	 * to add pre-authentication candidates. union
+	 * wpa_event_data::pmkid_candidate is used to report the BSSID of the
+	 * candidate and priority of the candidate, e.g., based on the signal
+	 * strength, in order to try to pre-authenticate first with candidates
+	 * that are most likely targets for re-association.
+	 *
+	 * EVENT_PMKID_CANDIDATE can be called whenever the driver has updates
+	 * on the candidate list. In addition, it can be called for the current
+	 * AP and APs that have existing PMKSA cache entries. wpa_supplicant
+	 * will automatically skip pre-authentication in cases where a valid
+	 * PMKSA exists. When more than one candidate exists, this event should
+	 * be generated once for each candidate.
+	 *
+	 * Driver will be notified about successful pre-authentication with
+	 * struct wpa_driver_ops::add_pmkid() calls.
+	 */
 	EVENT_PMKID_CANDIDATE
 } wpa_event_type;
 
+
+/**
+ * union wpa_event_data - Additional data for wpa_supplicant_event() calls
+ */
 union wpa_event_data {
-	struct {
-		/* Optional request information data: IEs included in AssocReq
-		 * and AssocResp. If these are not returned by the driver,
-		 * WPA Supplicant will generate the WPA/RSN IE. */
-		u8 *req_ies, *resp_ies;
-		size_t req_ies_len, resp_ies_len;
-
-		/* Optional Beacon/ProbeResp data: IEs included in Beacon or
+	/**
+	 * struct assoc_info - Data for EVENT_ASSOC and EVENT_ASSOCINFO events
+	 *
+	 * This structure is optional for EVENT_ASSOC calls and required for
+	 * EVENT_ASSOCINFO calls. By using EVENT_ASSOC with this data, the
+	 * driver interface does not need to generate separate EVENT_ASSOCINFO
+	 * calls.
+	 */
+	struct assoc_info {
+		/**
+		 * req_ies - (Re)Association Request IEs
+		 *
+		 * If the driver generates WPA/RSN IE, this event data must be
+		 * returned for WPA handshake to have needed information. If
+		 * wpa_supplicant-generated WPA/RSN IE is used, this
+		 * information event is optional.
+		 *
+		 * This should start with the first IE (fixed fields before IEs
+		 * are not included).
+		 */
+		u8 *req_ies;
+
+		/**
+		 * req_ies_len - Length of req_ies in bytes
+		 */
+		size_t req_ies_len;
+
+		/**
+		 * resp_ies - (Re)Association Response IEs
+		 *
+		 * Optional association data from the driver. This data is not
+		 * required WPA, but may be useful for some protocols and as
+		 * such, should be reported if this is available to the driver
+		 * interface.
+		 *
+		 * This should start with the first IE (fixed fields before IEs
+		 * are not included).
+		 */
+		u8 *resp_ies;
+
+		/**
+		 * resp_ies_len - Length of resp_ies in bytes
+		 */
+		size_t resp_ies_len;
+
+		/**
+		 * beacon_ies - Beacon or Probe Response IEs
+		 *
+		 * Optional Beacon/ProbeResp data: IEs included in Beacon or
 		 * Probe Response frames from the current AP (i.e., the one
 		 * that the client just associated with). This information is
 		 * used to update WPA/RSN IE for the AP. If this field is not
@@ -28,30 +185,52 @@ union wpa_event_data {
 		 * data for the new AP is found, scan results will be requested
 		 * again (without scan request). At this point, the driver is
 		 * expected to provide WPA/RSN IE for the AP (if WPA/WPA2 is
-		 * used). */
-		u8 *beacon_ies; /* beacon or probe resp IEs */
+		 * used).
+		 *
+		 * This should start with the first IE (fixed fields before IEs
+		 * are not included).
+		 */
+		u8 *beacon_ies;
+
+		/**
+		 * beacon_ies_len - Length of beacon_ies */
 		size_t beacon_ies_len;
 	} assoc_info;
-	struct {
+
+	/**
+	 * struct michael_mic_failure - Data for EVENT_MICHAEL_MIC_FAILURE
+	 */
+	struct michael_mic_failure {
 		int unicast;
 	} michael_mic_failure;
-	struct {
+
+	/**
+	 * struct interface_status - Data for EVENT_INTERFACE_STATUS
+	 */
+	struct interface_status {
 		char ifname[20];
 		enum {
 			EVENT_INTERFACE_ADDED, EVENT_INTERFACE_REMOVED
 		} ievent;
 	} interface_status;
-	struct {
+
+	/**
+	 * struct pmkid_candidate - Data for EVENT_PMKID_CANDIDATE
+	 */
+	struct pmkid_candidate {
+		/** BSSID of the PMKID candidate */
 		u8 bssid[ETH_ALEN];
-		int index; /* smaller the index, higher the priority */
+		/** Smaller the index, higher the priority */
+		int index;
+		/** Whether RSN IE includes pre-authenticate flag */
 		int preauth;
 	} pmkid_candidate;
 };
 
 /**
- * wpa_supplicant_event - report a driver event for wpa_supplicant
- * @wpa_s: pointer to wpa_supplicant data; this is the @ctx variable registered
- *	with wpa_driver_events_init()
+ * wpa_supplicant_event - Report a driver event for wpa_supplicant
+ * @wpa_s: pointer to wpa_supplicant data; this is the ctx variable registered
+ *	with struct wpa_driver_ops::init()
  * @event: event type (defined above)
  * @data: possible extra data for the event
  *
@@ -62,7 +241,9 @@ void wpa_supplicant_event(struct wpa_supplicant *wpa_s, wpa_event_type event,
 			  union wpa_event_data *data);
 
 /**
- * wpa_msg - conditional printf for default target and ctrl_iface monitors
+ * wpa_msg - Conditional printf for default target and ctrl_iface monitors
+ * @wpa_s: pointer to wpa_supplicant data; this is the ctx variable registered
+ *	with struct wpa_driver_ops::init()
  * @level: priority level (MSG_*) of the message
  * @fmt: printf format string, followed by optional arguments
  *
@@ -78,4 +259,16 @@ __attribute__ ((format (printf, 3, 4)));
 
 const char * wpa_ssid_txt(u8 *ssid, size_t ssid_len);
 
+/**
+ * wpa_supplicant_rx_eapol - Deliver a received EAPOL frame to wpa_supplicant
+ * @ctx: Context pointer (wpa_s)
+ * @src_addr: Source address of the EAPOL frame
+ * @buf: EAPOL data starting from the EAPOL header (i.e., no Ethernet header)
+ * @len: Length of the EAPOL data
+ *
+ * This function is called for each received EAPOL frame.
+ */
+void wpa_supplicant_rx_eapol(void *ctx, const u8 *src_addr,
+			     const u8 *buf, size_t len);
+
 #endif /* WPA_SUPPLICANT_H */