1 /* 2 * wpa_supplicant - Exported functions for wpa_supplicant modules 3 * Copyright (c) 2003-2005, Jouni Malinen <j (at) w1.fi> 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License version 2 as 7 * published by the Free Software Foundation. 8 * 9 * Alternatively, this software may be distributed under the terms of BSD 10 * license. 11 * 12 * See README and COPYING for more details. 13 */ 14 15 #ifndef WPA_SUPPLICANT_H 16 #define WPA_SUPPLICANT_H 17 18 /* Driver wrappers are not supposed to directly touch the internal data 19 * structure used in wpa_supplicant, so that definition is not provided here. 20 */ 21 struct wpa_supplicant; 22 23 /** 24 * enum wpa_event_type - Event type for wpa_supplicant_event() calls 25 */ 26 typedef enum wpa_event_type { 27 /** 28 * EVENT_ASSOC - Association completed 29 * 30 * This event needs to be delivered when the driver completes IEEE 31 * 802.11 association or reassociation successfully. 32 * wpa_driver_ops::get_bssid() is expected to provide the current BSSID 33 * after this even has been generated. In addition, optional 34 * EVENT_ASSOCINFO may be generated just before EVENT_ASSOC to provide 35 * more information about the association. If the driver interface gets 36 * both of these events at the same time, it can also include the 37 * assoc_info data in EVENT_ASSOC call. 38 */ 39 EVENT_ASSOC, 40 41 /** 42 * EVENT_DISASSOC - Association lost 43 * 44 * This event should be called when association is lost either due to 45 * receiving deauthenticate or disassociate frame from the AP or when 46 * sending either of these frames to the current AP. 47 */ 48 EVENT_DISASSOC, 49 50 /** 51 * EVENT_MICHAEL_MIC_FAILURE - Michael MIC (TKIP) detected 52 * 53 * This event must be delivered when a Michael MIC error is detected by 54 * the local driver. Additional data is for event processing is 55 * provided with union wpa_event_data::michael_mic_failure. This 56 * information is used to request new encyption key and to initiate 57 * TKIP countermeasures if needed. 58 */ 59 EVENT_MICHAEL_MIC_FAILURE, 60 61 /** 62 * EVENT_SCAN_RESULTS - Scan results available 63 * 64 * This event must be called whenever scan results are available to be 65 * fetched with struct wpa_driver_ops::get_scan_results(). This event 66 * is expected to be used some time after struct wpa_driver_ops::scan() 67 * is called. If the driver provides an unsolicited event when the scan 68 * has been completed, this event can be used to trigger 69 * EVENT_SCAN_RESULTS call. If such event is not available from the 70 * driver, the driver wrapper code is expected to use a registered 71 * timeout to generate EVENT_SCAN_RESULTS call after the time that the 72 * scan is expected to be completed. 73 */ 74 EVENT_SCAN_RESULTS, 75 76 /** 77 * EVENT_ASSOCINFO - Report optional extra information for association 78 * 79 * This event can be used to report extra association information for 80 * EVENT_ASSOC processing. This extra information includes IEs from 81 * association frames and Beacon/Probe Response frames in union 82 * wpa_event_data::assoc_info. EVENT_ASSOCINFO must be send just before 83 * EVENT_ASSOC. Alternatively, the driver interface can include 84 * assoc_info data in the EVENT_ASSOC call if it has all the 85 * information available at the same point. 86 */ 87 EVENT_ASSOCINFO, 88 89 /** 90 * EVENT_INTERFACE_STATUS - Report interface status changes 91 * 92 * This optional event can be used to report changes in interface 93 * status (interface added/removed) using union 94 * wpa_event_data::interface_status. This can be used to trigger 95 * wpa_supplicant to stop and re-start processing for the interface, 96 * e.g., when a cardbus card is ejected/inserted. 97 */ 98 EVENT_INTERFACE_STATUS, 99 100 /** 101 * EVENT_PMKID_CANDIDATE - Report a candidate AP for pre-authentication 102 * 103 * This event can be used to inform wpa_supplicant about candidates for 104 * RSN (WPA2) pre-authentication. If wpa_supplicant is not responsible 105 * for scan request (ap_scan=2 mode), this event is required for 106 * pre-authentication. If wpa_supplicant is performing scan request 107 * (ap_scan=1), this event is optional since scan results can be used 108 * to add pre-authentication candidates. union 109 * wpa_event_data::pmkid_candidate is used to report the BSSID of the 110 * candidate and priority of the candidate, e.g., based on the signal 111 * strength, in order to try to pre-authenticate first with candidates 112 * that are most likely targets for re-association. 113 * 114 * EVENT_PMKID_CANDIDATE can be called whenever the driver has updates 115 * on the candidate list. In addition, it can be called for the current 116 * AP and APs that have existing PMKSA cache entries. wpa_supplicant 117 * will automatically skip pre-authentication in cases where a valid 118 * PMKSA exists. When more than one candidate exists, this event should 119 * be generated once for each candidate. 120 * 121 * Driver will be notified about successful pre-authentication with 122 * struct wpa_driver_ops::add_pmkid() calls. 123 */ 124 EVENT_PMKID_CANDIDATE, 125 126 /** 127 * EVENT_STKSTART - Request STK handshake (MLME-STKSTART.request) 128 * 129 * This event can be used to inform wpa_supplicant about desire to set 130 * up secure direct link connection between two stations as defined in 131 * IEEE 802.11e with a new PeerKey mechanism that replaced the original 132 * STAKey negotiation. The caller will need to set peer address for the 133 * event. 134 */ 135 EVENT_STKSTART 136 } wpa_event_type; 137 138 139 /** 140 * union wpa_event_data - Additional data for wpa_supplicant_event() calls 141 */ 142 union wpa_event_data { 143 /** 144 * struct assoc_info - Data for EVENT_ASSOC and EVENT_ASSOCINFO events 145 * 146 * This structure is optional for EVENT_ASSOC calls and required for 147 * EVENT_ASSOCINFO calls. By using EVENT_ASSOC with this data, the 148 * driver interface does not need to generate separate EVENT_ASSOCINFO 149 * calls. 150 */ 151 struct assoc_info { 152 /** 153 * req_ies - (Re)Association Request IEs 154 * 155 * If the driver generates WPA/RSN IE, this event data must be 156 * returned for WPA handshake to have needed information. If 157 * wpa_supplicant-generated WPA/RSN IE is used, this 158 * information event is optional. 159 * 160 * This should start with the first IE (fixed fields before IEs 161 * are not included). 162 */ 163 u8 *req_ies; 164 165 /** 166 * req_ies_len - Length of req_ies in bytes 167 */ 168 size_t req_ies_len; 169 170 /** 171 * resp_ies - (Re)Association Response IEs 172 * 173 * Optional association data from the driver. This data is not 174 * required WPA, but may be useful for some protocols and as 175 * such, should be reported if this is available to the driver 176 * interface. 177 * 178 * This should start with the first IE (fixed fields before IEs 179 * are not included). 180 */ 181 u8 *resp_ies; 182 183 /** 184 * resp_ies_len - Length of resp_ies in bytes 185 */ 186 size_t resp_ies_len; 187 188 /** 189 * beacon_ies - Beacon or Probe Response IEs 190 * 191 * Optional Beacon/ProbeResp data: IEs included in Beacon or 192 * Probe Response frames from the current AP (i.e., the one 193 * that the client just associated with). This information is 194 * used to update WPA/RSN IE for the AP. If this field is not 195 * set, the results from previous scan will be used. If no 196 * data for the new AP is found, scan results will be requested 197 * again (without scan request). At this point, the driver is 198 * expected to provide WPA/RSN IE for the AP (if WPA/WPA2 is 199 * used). 200 * 201 * This should start with the first IE (fixed fields before IEs 202 * are not included). 203 */ 204 u8 *beacon_ies; 205 206 /** 207 * beacon_ies_len - Length of beacon_ies */ 208 size_t beacon_ies_len; 209 } assoc_info; 210 211 /** 212 * struct michael_mic_failure - Data for EVENT_MICHAEL_MIC_FAILURE 213 */ 214 struct michael_mic_failure { 215 int unicast; 216 } michael_mic_failure; 217 218 /** 219 * struct interface_status - Data for EVENT_INTERFACE_STATUS 220 */ 221 struct interface_status { 222 char ifname[100]; 223 enum { 224 EVENT_INTERFACE_ADDED, EVENT_INTERFACE_REMOVED 225 } ievent; 226 } interface_status; 227 228 /** 229 * struct pmkid_candidate - Data for EVENT_PMKID_CANDIDATE 230 */ 231 struct pmkid_candidate { 232 /** BSSID of the PMKID candidate */ 233 u8 bssid[ETH_ALEN]; 234 /** Smaller the index, higher the priority */ 235 int index; 236 /** Whether RSN IE includes pre-authenticate flag */ 237 int preauth; 238 } pmkid_candidate; 239 240 /** 241 * struct stkstart - Data for EVENT_STKSTART 242 */ 243 struct stkstart { 244 u8 peer[ETH_ALEN]; 245 } stkstart; 246 }; 247 248 /** 249 * wpa_supplicant_event - Report a driver event for wpa_supplicant 250 * @wpa_s: pointer to wpa_supplicant data; this is the ctx variable registered 251 * with struct wpa_driver_ops::init() 252 * @event: event type (defined above) 253 * @data: possible extra data for the event 254 * 255 * Driver wrapper code should call this function whenever an event is received 256 * from the driver. 257 */ 258 void wpa_supplicant_event(struct wpa_supplicant *wpa_s, wpa_event_type event, 259 union wpa_event_data *data); 260 261 /** 262 * wpa_supplicant_rx_eapol - Deliver a received EAPOL frame to wpa_supplicant 263 * @ctx: Context pointer (wpa_s) 264 * @src_addr: Source address of the EAPOL frame 265 * @buf: EAPOL data starting from the EAPOL header (i.e., no Ethernet header) 266 * @len: Length of the EAPOL data 267 * 268 * This function is called for each received EAPOL frame. 269 */ 270 void wpa_supplicant_rx_eapol(void *ctx, const u8 *src_addr, 271 const u8 *buf, size_t len); 272 273 #endif /* WPA_SUPPLICANT_H */ 274
