contrib/wpa_supplicant-0.4.9/driver.h

   1 /*
   2  * WPA Supplicant - driver interface definition
   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 DRIVER_H
  16 #define DRIVER_H
  17
  18 #define WPA_SUPPLICANT_DRIVER_VERSION 2
  19
  20 #include "defs.h"
  21
  22 #define AUTH_ALG_OPEN_SYSTEM    0x01
  23 #define AUTH_ALG_SHARED_KEY     0x02
  24 #define AUTH_ALG_LEAP           0x04
  25
  26 #define IEEE80211_MODE_INFRA    0
  27 #define IEEE80211_MODE_IBSS     1
  28
  29 #define IEEE80211_CAP_ESS       0x0001
  30 #define IEEE80211_CAP_IBSS      0x0002
  31 #define IEEE80211_CAP_PRIVACY   0x0010
  32
  33 #define SSID_MAX_WPA_IE_LEN 40
  34 /**
  35  * struct wpa_scan_result - Scan results
  36  * @bssid: BSSID
  37  * @ssid: SSID
  38  * @ssid_len: length of the ssid
  39  * @wpa_ie: WPA IE
  40  * @wpa_ie_len: length of the wpa_ie
  41  * @rsn_ie: RSN IE
  42  * @rsn_ie_len: length of the RSN IE
  43  * @freq: frequency of the channel in MHz (e.g., 2412 = channel 1)
  44  * @caps: capability information field in host byte order
  45  * @qual: signal quality
  46  * @noise: noise level
  47  * @level: signal level
  48  * @maxrate: maximum supported rate
  49  *
  50  * This structure is used as a generic format for scan results from the
  51  * driver. Each driver interface implementation is responsible for converting
  52  * the driver or OS specific scan results into this format.
  53  */
  54 struct wpa_scan_result {
  55         u8 bssid[ETH_ALEN];
  56         u8 ssid[32];
  57         size_t ssid_len;
  58         u8 wpa_ie[SSID_MAX_WPA_IE_LEN];
  59         size_t wpa_ie_len;
  60         u8 rsn_ie[SSID_MAX_WPA_IE_LEN];
  61         size_t rsn_ie_len;
  62         int freq;
  63         u16 caps;
  64         int qual;
  65         int noise;
  66         int level;
  67         int maxrate;
  68 };
  69
  70 /**
  71  * struct wpa_driver_associate_params - Association parameters
  72  * Data for struct wpa_driver_ops::associate().
  73  */
  74 struct wpa_driver_associate_params {
  75         /**
  76          * bssid - BSSID of the selected AP
  77          * This can be %NULL, if ap_scan=2 mode is used and the driver is
  78          * responsible for selecting with which BSS to associate. */
  79         const u8 *bssid;
  80
  81         /**
  82          * ssid - The selected SSID
  83          */
  84         const u8 *ssid;
  85         size_t ssid_len;
  86
  87         /**
  88          * freq - Frequency of the channel the selected AP is using
  89          * Frequency that the selected AP is using (in MHz as
  90          * reported in the scan results)
  91          */
  92         int freq;
  93
  94         /**
  95          * wpa_ie - WPA information element for (Re)Association Request
  96          * WPA information element to be included in (Re)Association
  97          * Request (including information element id and length). Use
  98          * of this WPA IE is optional. If the driver generates the WPA
  99          * IE, it can use pairwise_suite, group_suite, and
 100          * key_mgmt_suite to select proper algorithms. In this case,
 101          * the driver has to notify wpa_supplicant about the used WPA
 102          * IE by generating an event that the interface code will
 103          * convert into EVENT_ASSOCINFO data (see wpa_supplicant.h).
 104          * When using WPA2/IEEE 802.11i, wpa_ie is used for RSN IE
 105          * instead. The driver can determine which version is used by
 106          * looking at the first byte of the IE (0xdd for WPA, 0x30 for
 107          * WPA2/RSN).
 108          */
 109         const u8 *wpa_ie;
 110         /**
 111          * wpa_ie_len - length of the wpa_ie
 112          */
 113         size_t wpa_ie_len;
 114
 115         /* The selected pairwise/group cipher and key management
 116          * suites. These are usually ignored if @wpa_ie is used. */
 117         wpa_cipher pairwise_suite;
 118         wpa_cipher group_suite;
 119         wpa_key_mgmt key_mgmt_suite;
 120
 121         /**
 122          * auth_alg - Allowed authentication algorithms
 123          * Bit field of AUTH_ALG_*
 124          */
 125         int auth_alg;
 126
 127         /**
 128          * mode - Operation mode (infra/ibss) IEEE80211_MODE_*
 129          */
 130         int mode;
 131 };
 132
 133 /**
 134  * struct wpa_driver_capa - Driver capability information
 135  */
 136 struct wpa_driver_capa {
 137 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA            0x00000001
 138 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA2           0x00000002
 139 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA_PSK        0x00000004
 140 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA2_PSK       0x00000008
 141 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA_NONE       0x00000010
 142         unsigned int key_mgmt;
 143
 144 #define WPA_DRIVER_CAPA_ENC_WEP40       0x00000001
 145 #define WPA_DRIVER_CAPA_ENC_WEP104      0x00000002
 146 #define WPA_DRIVER_CAPA_ENC_TKIP        0x00000004
 147 #define WPA_DRIVER_CAPA_ENC_CCMP        0x00000008
 148         unsigned int enc;
 149
 150 #define WPA_DRIVER_AUTH_OPEN            0x00000001
 151 #define WPA_DRIVER_AUTH_SHARED          0x00000002
 152 #define WPA_DRIVER_AUTH_LEAP            0x00000004
 153         unsigned int auth;
 154
 155 /* Driver generated WPA/RSN IE */
 156 #define WPA_DRIVER_FLAGS_DRIVER_IE      0x00000001
 157 #define WPA_DRIVER_FLAGS_SET_KEYS_AFTER_ASSOC 0x00000002
 158         unsigned int flags;
 159 };
 160
 161
 162 /**
 163  * struct wpa_driver_ops - Driver interface API definition
 164  *
 165  * This structure defines the API that each driver interface needs to implement
 166  * for core wpa_supplicant code. All driver specific functionality is captured
 167  * in this wrapper.
 168  */
 169 struct wpa_driver_ops {
 170         /** Name of the driver interface */
 171         const char *name;
 172         /** One line description of the driver interface */
 173         const char *desc;
 174
 175         /**
 176          * get_bssid - Get the current BSSID
 177          * @priv: private driver interface data
 178          * @bssid: buffer for BSSID (ETH_ALEN = 6 bytes)
 179          *
 180          * Returns: 0 on success, -1 on failure
 181          *
 182          * Query kernel driver for the current BSSID and copy it to bssid.
 183          * Setting bssid to 00:00:00:00:00:00 is recommended if the STA is not
 184          * associated.
 185          */
 186         int (*get_bssid)(void *priv, u8 *bssid);
 187
 188         /**
 189          * get_ssid - Get the current SSID
 190          * @priv: private driver interface data
 191          * @ssid: buffer for SSID (at least 32 bytes)
 192          *
 193          * Returns: Length of the SSID on success, -1 on failure
 194          *
 195          * Query kernel driver for the current SSID and copy it to ssid.
 196          * Returning zero is recommended if the STA is not associated.
 197          *
 198          * Note: SSID is an array of octets, i.e., it is not nul terminated and
 199          * can, at least in theory, contain control characters (including nul)
 200          * and as such, should be processed as binary data, not a printable
 201          * string.
 202          */
 203         int (*get_ssid)(void *priv, u8 *ssid);
 204
 205         /**
 206          * set_wpa - Enable/disable WPA support (OBSOLETE)
 207          * @priv: private driver interface data
 208          * @enabled: 1 = enable, 0 = disable
 209          *
 210          * Returns: 0 on success, -1 on failure
 211          *
 212          * Note: This function is included for backwards compatibility. This is
 213          * called only just after init and just before deinit, so these
 214          * functions can be used to implement same functionality and the driver
 215          * interface need not define this function.
 216          *
 217          * Configure the kernel driver to enable/disable WPA support. This may
 218          * be empty function, if WPA support is always enabled. Common
 219          * configuration items are WPA IE (clearing it when WPA support is
 220          * disabled), Privacy flag configuration for capability field (note:
 221          * this the value need to set in associate handler to allow plaintext
 222          * mode to be used) when trying to associate with, roaming mode (can
 223          * allow wpa_supplicant to control roaming if ap_scan=1 is used;
 224          * however, drivers can also implement roaming if desired, especially
 225          * ap_scan=2 mode is used for this).
 226          */
 227         int (*set_wpa)(void *priv, int enabled);
 228
 229         /**
 230          * set_key - Configure encryption key
 231          * @priv: private driver interface data
 232          * @alg: encryption algorithm (%WPA_ALG_NONE, %WPA_ALG_WEP,
 233          *      %WPA_ALG_TKIP, %WPA_ALG_CCMP); %WPA_ALG_NONE clears the key.
 234          * @addr: address of the peer STA or ff:ff:ff:ff:ff:ff for
 235          *      broadcast/default keys
 236          * @key_idx: key index (0..3), usually 0 for unicast keys
 237          * @set_tx: configure this key as the default Tx key (only used when
 238          *      driver does not support separate unicast/individual key
 239          * @seq: sequence number/packet number, seq_len octets, the next
 240          *      packet number to be used for in replay protection; configured
 241          *      for Rx keys (in most cases, this is only used with broadcast
 242          *      keys and set to zero for unicast keys)
 243          * @seq_len: length of the seq, depends on the algorithm:
 244          *      TKIP: 6 octets, CCMP: 6 octets
 245          * @key: key buffer; TKIP: 16-byte temporal key, 8-byte Tx Mic key,
 246          *      8-byte Rx Mic Key
 247          * @key_len: length of the key buffer in octets (WEP: 5 or 13,
 248          *      TKIP: 32, CCMP: 16)
 249          *
 250          * Returns: 0 on success, -1 on failure
 251          *
 252          * Configure the given key for the kernel driver. If the driver
 253          * supports separate individual keys (4 default keys + 1 individual),
 254          * addr can be used to determine whether the key is default or
 255          * individual. If only 4 keys are supported, the default key with key
 256          * index 0 is used as the individual key. STA must be configured to use
 257          * it as the default Tx key (set_tx is set) and accept Rx for all the
 258          * key indexes. In most cases, WPA uses only key indexes 1 and 2 for
 259          * broadcast keys, so key index 0 is available for this kind of
 260          * configuration.
 261          *
 262          * Please note that TKIP keys include separate TX and RX MIC keys and
 263          * some drivers may expect them in different order than wpa_supplicant
 264          * is using. If the TX/RX keys are swapped, all TKIP encrypted packets
 265          * will tricker Michael MIC errors. This can be fixed by changing the
 266          * order of MIC keys by swapping te bytes 16..23 and 24..31 of the key
 267          * in driver_*.c set_key() implementation, see driver_ndis.c for an
 268          * example on how this can be done.
 269          */
 270         int (*set_key)(void *priv, wpa_alg alg, const u8 *addr,
 271                        int key_idx, int set_tx, const u8 *seq, size_t seq_len,
 272                        const u8 *key, size_t key_len);
 273
 274         /**
 275          * init - Initialize driver interface
 276          * @ctx: context to be used when calling wpa_supplicant functions,
 277          * e.g., wpa_supplicant_event()
 278          * @ifname: interface name, e.g., wlan0
 279          *
 280          * Returns: Pointer to private data, %NULL on failure
 281          *
 282          * Initialize driver interface, including event processing for kernel
 283          * driver events (e.g., associated, scan results, Michael MIC failure).
 284          * This function can allocate a private configuration data area for
 285          * @ctx, file descriptor, interface name, etc. information that may be
 286          * needed in future driver operations. If this is not used, non-NULL
 287          * value will need to be returned because %NULL is used to indicate
 288          * failure. The returned value will be used as 'void *priv' data for
 289          * all other driver_ops functions.
 290          *
 291          * The main event loop (eloop.c) of wpa_supplicant can be used to
 292          * register callback for read sockets (eloop_register_read_sock()).
 293          *
 294          * See wpa_supplicant.h for more information about events and
 295          * wpa_supplicant_event() function.
 296          */
 297         void * (*init)(void *ctx, const char *ifname);
 298
 299         /**
 300          * deinit - Deinitialize driver interface
 301          * @priv: private driver interface data from init()
 302          *
 303          * Shut down driver interface and processing of driver events. Free
 304          * private data buffer if one was allocated in init() handler.
 305          */
 306         void (*deinit)(void *priv);
 307
 308         /**
 309          * set_param - Set driver configuration parameters
 310          * @priv: private driver interface data from init()
 311          * @param: driver specific configuration parameters
 312          *
 313          * Returns: 0 on success, -1 on failure
 314          *
 315          * Optional handler for notifying driver interface about configuration
 316          * parameters (driver_param).
 317          */
 318         int (*set_param)(void *priv, const char *param);
 319
 320         /**
 321          * set_countermeasures - Enable/disable TKIP countermeasures
 322          * @priv: private driver interface data
 323          * @enabled: 1 = countermeasures enabled, 0 = disabled
 324          *
 325          * Returns: 0 on success, -1 on failure
 326          *
 327          * Configure TKIP countermeasures. When these are enabled, the driver
 328          * should drop all received and queued frames that are using TKIP.
 329          */
 330         int (*set_countermeasures)(void *priv, int enabled);
 331
 332         /**
 333          * set_drop_unencrypted - Enable/disable unencrypted frame filtering
 334          * @priv: private driver interface data
 335          * @enabled: 1 = unencrypted Tx/Rx frames will be dropped, 0 = disabled
 336          *
 337          * Returns: 0 on success, -1 on failure
 338          *
 339          * Configure the driver to drop all non-EAPOL frames (both receive and
 340          * transmit paths). Unencrypted EAPOL frames (ethertype 0x888e) must
 341          * still be allowed for key negotiation.
 342          */
 343         int (*set_drop_unencrypted)(void *priv, int enabled);
 344
 345         /**
 346          * scan - Request the driver to initiate scan
 347          * @priv: private driver interface data
 348          * @ssid: specific SSID to scan for (ProbeReq) or %NULL to scan for
 349          *      all SSIDs (either active scan with broadcast SSID or passive
 350          *      scan
 351          * @ssid_len: length of the SSID
 352          *
 353          * Returns: 0 on success, -1 on failure
 354          *
 355          * Once the scan results are ready, the driver should report scan
 356          * results event for wpa_supplicant which will eventually request the
 357          * results with wpa_driver_get_scan_results().
 358          */
 359         int (*scan)(void *priv, const u8 *ssid, size_t ssid_len);
 360
 361         /**
 362          * get_scan_results - Fetch the latest scan results
 363          * @priv: private driver interface data
 364          * @results: pointer to buffer for scan results
 365          * @max_size: maximum number of entries (buffer size)
 366          *
 367          * Returns: Number of scan result entries used on success, -1 on
 368          * failure
 369          *
 370          * If scan results include more than max_size BSSes, max_size will be
 371          * returned and the remaining entries will not be included in the
 372          * buffer.
 373          */
 374         int (*get_scan_results)(void *priv,
 375                                 struct wpa_scan_result *results,
 376                                 size_t max_size);
 377
 378         /**
 379          * deauthenticate - Request driver to deauthenticate
 380          * @priv: private driver interface data
 381          * @addr: peer address (BSSID of the AP)
 382          * @reason_code: 16-bit reason code to be sent in the deauthentication
 383          *      frame
 384          *
 385          * Returns: 0 on success, -1 on failure
 386          */
 387         int (*deauthenticate)(void *priv, const u8 *addr, int reason_code);
 388
 389         /**
 390          * disassociate - Request driver to disassociate
 391          * @priv: private driver interface data
 392          * @addr: peer address (BSSID of the AP)
 393          * @reason_code: 16-bit reason code to be sent in the disassociation
 394          *      frame
 395          *
 396          * Returns: 0 on success, -1 on failure
 397          */
 398         int (*disassociate)(void *priv, const u8 *addr, int reason_code);
 399
 400         /**
 401          * associate - Request driver to associate
 402          * @priv: private driver interface data
 403          * @params: association parameters
 404          *
 405          * Returns: 0 on success, -1 on failure
 406          */
 407         int (*associate)(void *priv,
 408                          struct wpa_driver_associate_params *params);
 409
 410         /**
 411          * set_auth_alg - Set IEEE 802.11 authentication algorithm
 412          * @priv: private driver interface data
 413          * @auth_alg: bit field of AUTH_ALG_*
 414          *
 415          * If the driver supports more than one authentication algorithm at the
 416          * same time, it should configure all supported algorithms. If not, one
 417          * algorithm needs to be selected arbitrarily. Open System
 418          * authentication should be ok for most cases and it is recommended to
 419          * be used if other options are not supported. Static WEP configuration
 420          * may also use Shared Key authentication and LEAP requires its own
 421          * algorithm number. For LEAP, user can make sure that only one
 422          * algorithm is used at a time by configuring LEAP as the only
 423          * supported EAP method. This information is also available in
 424          * associate() params, so set_auth_alg may not be needed in case of
 425          * most drivers.
 426          *
 427          * Returns: 0 on success, -1 on failure
 428          */
 429         int (*set_auth_alg)(void *priv, int auth_alg);
 430
 431         /**
 432          * add_pmkid - Add PMKSA cache entry to the driver
 433          * @priv: private driver interface data
 434          * @bssid: BSSID for the PMKSA cache entry
 435          * @pmkid: PMKID for the PMKSA cache entry
 436          *
 437          * Returns: 0 on success, -1 on failure
 438          *
 439          * This function is called when a new PMK is received, as a result of
 440          * either normal authentication or RSN pre-authentication.
 441          *
 442          * If the driver generates RSN IE, i.e., it does not use wpa_ie in
 443          * associate(), add_pmkid() can be used to add new PMKSA cache entries
 444          * in the driver. If the driver uses wpa_ie from wpa_supplicant, this
 445          * driver_ops function does not need to be implemented. Likewise, if
 446          * the driver does not support WPA, this function is not needed.
 447          */
 448         int (*add_pmkid)(void *priv, const u8 *bssid, const u8 *pmkid);
 449
 450         /**
 451          * remove_pmkid - Remove PMKSA cache entry to the driver
 452          * @priv: private driver interface data
 453          * @bssid: BSSID for the PMKSA cache entry
 454          * @pmkid: PMKID for the PMKSA cache entry
 455          *
 456          * Returns: 0 on success, -1 on failure
 457          *
 458          * This function is called when the supplicant drops a PMKSA cache
 459          * entry for any reason.
 460          *
 461          * If the driver generates RSN IE, i.e., it does not use wpa_ie in
 462          * associate(), remove_pmkid() can be used to synchronize PMKSA caches
 463          * between the driver and wpa_supplicant. If the driver uses wpa_ie
 464          * from wpa_supplicant, this driver_ops function does not need to be
 465          * implemented. Likewise, if the driver does not support WPA, this
 466          * function is not needed.
 467          */
 468         int (*remove_pmkid)(void *priv, const u8 *bssid, const u8 *pmkid);
 469
 470         /**
 471          * flush_pmkid - Flush PMKSA cache
 472          * @priv: private driver interface data
 473          *
 474          * Returns: 0 on success, -1 on failure
 475          *
 476          * This function is called when the supplicant drops all PMKSA cache
 477          * entries for any reason.
 478          *
 479          * If the driver generates RSN IE, i.e., it does not use wpa_ie in
 480          * associate(), remove_pmkid() can be used to synchronize PMKSA caches
 481          * between the driver and wpa_supplicant. If the driver uses wpa_ie
 482          * from wpa_supplicant, this driver_ops function does not need to be
 483          * implemented. Likewise, if the driver does not support WPA, this
 484          * function is not needed.
 485          */
 486         int (*flush_pmkid)(void *priv);
 487
 488         /**
 489          * flush_pmkid - Flush PMKSA cache
 490          * @priv: private driver interface data
 491          *
 492          * Returns: 0 on success, -1 on failure
 493          *
 494          * Get driver/firmware/hardware capabilities.
 495          */
 496         int (*get_capa)(void *priv, struct wpa_driver_capa *capa);
 497
 498         /**
 499          * poll - Poll driver for association information
 500          * @priv: private driver interface data
 501          *
 502          * This is an option callback that can be used when the driver does not
 503          * provide event mechanism for association events. This is called when
 504          * receiving WPA EAPOL-Key messages that require association
 505          * information. The driver interface is supposed to generate associnfo
 506          * event before returning from this callback function. In addition, the
 507          * driver interface should generate an association event after having
 508          * sent out associnfo.
 509          */
 510         void (*poll)(void *priv);
 511
 512         /**
 513          * get_ifname - Get interface name
 514          * @priv: private driver interface data
 515          *
 516          * Returns: Pointer to the interface name. This can differ from the
 517          * interface name used in init() call.
 518          *
 519          * This optional function can be used to allow the driver interface to
 520          * replace the interface name with something else, e.g., based on an
 521          * interface mapping from a more descriptive name.
 522          */
 523         const char * (*get_ifname)(void *priv);
 524
 525         /**
 526          * get_mac_addr - Get own MAC address
 527          * @priv: private driver interface data
 528          *
 529          * Returns: Pointer to own MAC address or %NULL on failure
 530          *
 531          * This optional function can be used to get the own MAC address of the
 532          * device from the driver interface code. This is only needed if the
 533          * l2_packet implementation for the OS does not provide easy access to
 534          * a MAC address. */
 535         const u8 * (*get_mac_addr)(void *priv);
 536
 537         /**
 538          * send_eapol - Optional function for sending EAPOL packets
 539          * @priv: private driver interface data
 540          * @dest: Destination MAC address
 541          * @proto: Ethertype
 542          * @data: EAPOL packet starting with IEEE 802.1X header
 543          * @data_len: Size of the EAPOL packet
 544          *
 545          * Returns: 0 on success, -1 on failure
 546          *
 547          * This optional function can be used to override l2_packet operations
 548          * with driver specific functionality. If this function pointer is set,
 549          * l2_packet module is not used at all and the driver interface code is
 550          * responsible for receiving and sending all EAPOL packets. The
 551          * received EAPOL packets are sent to core code by calling
 552          * wpa_supplicant_rx_eapol(). The driver interface is required to
 553          * implement get_mac_addr() handler if send_eapol() is used.
 554          */
 555         int (*send_eapol)(void *priv, const u8 *dest, u16 proto,
 556                           const u8 *data, size_t data_len);
 557 };
 558
 559 #endif /* DRIVER_H */