contrib/wpa_supplicant-0.4.9/wpa_supplicant.h

   1 /*
   2  * wpa_supplicant - Exported functions for wpa_supplicant modules
   3  * Copyright (c) 2003-2005, Jouni Malinen <jkmaline@cc.hut.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 } wpa_event_type;
 126
 127
 128 /**
 129  * union wpa_event_data - Additional data for wpa_supplicant_event() calls
 130  */
 131 union wpa_event_data {
 132         /**
 133          * struct assoc_info - Data for EVENT_ASSOC and EVENT_ASSOCINFO events
 134          *
 135          * This structure is optional for EVENT_ASSOC calls and required for
 136          * EVENT_ASSOCINFO calls. By using EVENT_ASSOC with this data, the
 137          * driver interface does not need to generate separate EVENT_ASSOCINFO
 138          * calls.
 139          */
 140         struct assoc_info {
 141                 /**
 142                  * req_ies - (Re)Association Request IEs
 143                  *
 144                  * If the driver generates WPA/RSN IE, this event data must be
 145                  * returned for WPA handshake to have needed information. If
 146                  * wpa_supplicant-generated WPA/RSN IE is used, this
 147                  * information event is optional.
 148                  *
 149                  * This should start with the first IE (fixed fields before IEs
 150                  * are not included).
 151                  */
 152                 u8 *req_ies;
 153
 154                 /**
 155                  * req_ies_len - Length of req_ies in bytes
 156                  */
 157                 size_t req_ies_len;
 158
 159                 /**
 160                  * resp_ies - (Re)Association Response IEs
 161                  *
 162                  * Optional association data from the driver. This data is not
 163                  * required WPA, but may be useful for some protocols and as
 164                  * such, should be reported if this is available to the driver
 165                  * interface.
 166                  *
 167                  * This should start with the first IE (fixed fields before IEs
 168                  * are not included).
 169                  */
 170                 u8 *resp_ies;
 171
 172                 /**
 173                  * resp_ies_len - Length of resp_ies in bytes
 174                  */
 175                 size_t resp_ies_len;
 176
 177                 /**
 178                  * beacon_ies - Beacon or Probe Response IEs
 179                  *
 180                  * Optional Beacon/ProbeResp data: IEs included in Beacon or
 181                  * Probe Response frames from the current AP (i.e., the one
 182                  * that the client just associated with). This information is
 183                  * used to update WPA/RSN IE for the AP. If this field is not
 184                  * set, the results from previous scan will be used. If no
 185                  * data for the new AP is found, scan results will be requested
 186                  * again (without scan request). At this point, the driver is
 187                  * expected to provide WPA/RSN IE for the AP (if WPA/WPA2 is
 188                  * used).
 189                  *
 190                  * This should start with the first IE (fixed fields before IEs
 191                  * are not included).
 192                  */
 193                 u8 *beacon_ies;
 194
 195                 /**
 196                  * beacon_ies_len - Length of beacon_ies */
 197                 size_t beacon_ies_len;
 198         } assoc_info;
 199
 200         /**
 201          * struct michael_mic_failure - Data for EVENT_MICHAEL_MIC_FAILURE
 202          */
 203         struct michael_mic_failure {
 204                 int unicast;
 205         } michael_mic_failure;
 206
 207         /**
 208          * struct interface_status - Data for EVENT_INTERFACE_STATUS
 209          */
 210         struct interface_status {
 211                 char ifname[20];
 212                 enum {
 213                         EVENT_INTERFACE_ADDED, EVENT_INTERFACE_REMOVED
 214                 } ievent;
 215         } interface_status;
 216
 217         /**
 218          * struct pmkid_candidate - Data for EVENT_PMKID_CANDIDATE
 219          */
 220         struct pmkid_candidate {
 221                 /** BSSID of the PMKID candidate */
 222                 u8 bssid[ETH_ALEN];
 223                 /** Smaller the index, higher the priority */
 224                 int index;
 225                 /** Whether RSN IE includes pre-authenticate flag */
 226                 int preauth;
 227         } pmkid_candidate;
 228 };
 229
 230 /**
 231  * wpa_supplicant_event - Report a driver event for wpa_supplicant
 232  * @wpa_s: pointer to wpa_supplicant data; this is the ctx variable registered
 233  *      with struct wpa_driver_ops::init()
 234  * @event: event type (defined above)
 235  * @data: possible extra data for the event
 236  *
 237  * Driver wrapper code should call this function whenever an event is received
 238  * from the driver.
 239  */
 240 void wpa_supplicant_event(struct wpa_supplicant *wpa_s, wpa_event_type event,
 241                           union wpa_event_data *data);
 242
 243 /**
 244  * wpa_msg - Conditional printf for default target and ctrl_iface monitors
 245  * @wpa_s: pointer to wpa_supplicant data; this is the ctx variable registered
 246  *      with struct wpa_driver_ops::init()
 247  * @level: priority level (MSG_*) of the message
 248  * @fmt: printf format string, followed by optional arguments
 249  *
 250  * This function is used to print conditional debugging and error messages. The
 251  * output may be directed to stdout, stderr, and/or syslog based on
 252  * configuration. This function is like wpa_printf(), but it also sends the
 253  * same message to all attached ctrl_iface monitors.
 254  *
 255  * Note: New line '\n' is added to the end of the text when printing to stdout.
 256  */
 257 void wpa_msg(struct wpa_supplicant *wpa_s, int level, char *fmt, ...)
 258 __attribute__ ((format (printf, 3, 4)));
 259
 260 const char * wpa_ssid_txt(u8 *ssid, size_t ssid_len);
 261
 262 /**
 263  * wpa_supplicant_rx_eapol - Deliver a received EAPOL frame to wpa_supplicant
 264  * @ctx: Context pointer (wpa_s)
 265  * @src_addr: Source address of the EAPOL frame
 266  * @buf: EAPOL data starting from the EAPOL header (i.e., no Ethernet header)
 267  * @len: Length of the EAPOL data
 268  *
 269  * This function is called for each received EAPOL frame.
 270  */
 271 void wpa_supplicant_rx_eapol(void *ctx, const u8 *src_addr,
 272                              const u8 *buf, size_t len);
 273
 274 #endif /* WPA_SUPPLICANT_H */