contrib/wpa_supplicant/driver.h

   1 #ifndef DRIVER_H
   2 #define DRIVER_H
   3
   4 #define WPA_SUPPLICANT_DRIVER_VERSION 2
   5
   6 typedef enum { WPA_ALG_NONE, WPA_ALG_WEP, WPA_ALG_TKIP, WPA_ALG_CCMP } wpa_alg;
   7 typedef enum { CIPHER_NONE, CIPHER_WEP40, CIPHER_TKIP, CIPHER_CCMP,
   8                CIPHER_WEP104 } wpa_cipher;
   9 typedef enum { KEY_MGMT_802_1X, KEY_MGMT_PSK, KEY_MGMT_NONE,
  10                KEY_MGMT_802_1X_NO_WPA, KEY_MGMT_WPA_NONE } wpa_key_mgmt;
  11
  12 #define AUTH_ALG_OPEN_SYSTEM    0x01
  13 #define AUTH_ALG_SHARED_KEY     0x02
  14 #define AUTH_ALG_LEAP           0x04
  15
  16 #define IEEE80211_MODE_INFRA    0
  17 #define IEEE80211_MODE_IBSS     1
  18
  19 #define SSID_MAX_WPA_IE_LEN 40
  20 struct wpa_scan_result {
  21         u8 bssid[ETH_ALEN];
  22         u8 ssid[32];
  23         size_t ssid_len;
  24         u8 wpa_ie[SSID_MAX_WPA_IE_LEN];
  25         size_t wpa_ie_len;
  26         u8 rsn_ie[SSID_MAX_WPA_IE_LEN];
  27         size_t rsn_ie_len;
  28         int freq; /* MHz */
  29         int caps; /* e.g. privacy */
  30         int qual; /* signal quality */
  31         int noise;
  32         int level;
  33         int maxrate;
  34 };
  35
  36 /* Parameters for associate driver_ops. */
  37 struct wpa_driver_associate_params {
  38         /* BSSID of the selected AP */
  39         const u8 *bssid;
  40
  41         /* The selected SSID and its length in bytes */
  42         const u8 *ssid;
  43         size_t ssid_len;
  44
  45         /* frequency that the selected AP is using (in MHz as
  46          * reported in the scan results) */
  47         int freq;
  48
  49         /* WPA information element to be included in (Re)Association
  50          * Request (including information element id and length). Use
  51          * of this WPA IE is optional. If the driver generates the WPA
  52          * IE, it can use @pairwise_suite, @group_suite, and
  53          * @key_mgmt_suite to select proper algorithms. In this case,
  54          * the driver has to notify wpa_supplicant about the used WPA
  55          * IE by generating an event that the interface code will
  56          * convert into EVENT_ASSOCINFO data (see wpa_supplicant.h).
  57          * When using WPA2/IEEE 802.11i, @wpa_ie is used for RSN IE
  58          * instead. The driver can determine which version is used by
  59          * looking at the first byte of the IE (0xdd for WPA, 0x30 for
  60          * WPA2/RSN). @wpa_ie_len: length of the @wpa_ie */
  61         const u8 *wpa_ie;
  62         size_t wpa_ie_len;
  63
  64         /* The selected pairwise/group cipher and key management
  65          * suites. These are usually ignored if @wpa_ie is used. */
  66         wpa_cipher pairwise_suite;
  67         wpa_cipher group_suite;
  68         wpa_key_mgmt key_mgmt_suite;
  69
  70         int auth_alg; /* bit field of AUTH_ALG_* */
  71         int mode; /* IEEE80211_MODE_* */
  72 };
  73
  74 struct wpa_driver_capa {
  75 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA            0x00000001
  76 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA2           0x00000002
  77 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA_PSK        0x00000004
  78 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA2_PSK       0x00000008
  79 #define WPA_DRIVER_CAPA_KEY_MGMT_WPA_NONE       0x00000010
  80         unsigned int key_mgmt;
  81
  82 #define WPA_DRIVER_CAPA_ENC_WEP40       0x00000001
  83 #define WPA_DRIVER_CAPA_ENC_WEP104      0x00000002
  84 #define WPA_DRIVER_CAPA_ENC_TKIP        0x00000004
  85 #define WPA_DRIVER_CAPA_ENC_CCMP        0x00000008
  86         unsigned int enc;
  87
  88 #define WPA_DRIVER_AUTH_OPEN            0x00000001
  89 #define WPA_DRIVER_AUTH_SHARED          0x00000002
  90 #define WPA_DRIVER_AUTH_LEAP            0x00000004
  91         unsigned int auth;
  92
  93 /* Driver generated WPA/RSN IE */
  94 #define WPA_DRIVER_FLAGS_DRIVER_IE      0x00000001
  95 #define WPA_DRIVER_FLAGS_SET_KEYS_AFTER_ASSOC 0x00000002
  96         unsigned int flags;
  97 };
  98
  99
 100 struct wpa_driver_ops {
 101         /* name of the driver interface */
 102         const char *name;
 103         /* one line description of the driver interface */
 104         const char *desc;
 105
 106         /**
 107          * get_bssid - get the current BSSID
 108          * @priv: private driver interface data
 109          * @bssid: buffer for BSSID (ETH_ALEN = 6 bytes)
 110          *
 111          * Returns: 0 on success, -1 on failure
 112          *
 113          * Query kernel driver for the current BSSID and copy it to @bssid.
 114          * Setting @bssid to 00:00:00:00:00:00 is recommended if the STA is not
 115          * associated.
 116          */
 117         int (*get_bssid)(void *priv, u8 *bssid);
 118
 119         /**
 120          * get_ssid - get the current SSID
 121          * @priv: private driver interface data
 122          * @ssid: buffer for SSID (at least 32 bytes)
 123          *
 124          * Returns: length of the SSID on success, -1 on failure
 125          *
 126          * Query kernel driver for the current SSID and copy it to @ssid.
 127          * Returning zero is recommended if the STA is not associated.
 128          *
 129          * Note: SSID is an array of octets, i.e., it is not nul terminated and
 130          * can, at least in theory, contain control characters (including nul)
 131          * and as such, should be processed as binary data, not a printable
 132          * string.
 133          */
 134         int (*get_ssid)(void *priv, u8 *ssid);
 135
 136         /**
 137          * set_wpa - enable/disable WPA support
 138          * @priv: private driver interface data
 139          * @enabled: 1 = enable, 0 = disable
 140          *
 141          * Returns: 0 on success, -1 on failure
 142          *
 143          * Configure the kernel driver to enable/disable WPA support. This may
 144          * be empty function, if WPA support is always enabled. Common
 145          * configuration items are WPA IE (clearing it when WPA support is
 146          * disabled), Privacy flag for capability field, roaming mode (need to
 147          * allow wpa_supplicant to control roaming).
 148          */
 149         int (*set_wpa)(void *priv, int enabled);
 150
 151         /**
 152          * set_key - configure encryption key
 153          * @priv: private driver interface data
 154          * @alg: encryption algorithm (%WPA_ALG_NONE, %WPA_ALG_WEP,
 155          *      %WPA_ALG_TKIP, %WPA_ALG_CCMP); %WPA_ALG_NONE clears the key.
 156          * @addr: address of the peer STA or ff:ff:ff:ff:ff:ff for
 157          *      broadcast/default keys
 158          * @key_idx: key index (0..3), always 0 for unicast keys
 159          * @set_tx: configure this key as the default Tx key (only used when
 160          *      driver does not support separate unicast/individual key
 161          * @seq: sequence number/packet number, @seq_len octets, the next
 162          *      packet number to be used for in replay protection; configured
 163          *      for Rx keys (in most cases, this is only used with broadcast
 164          *      keys and set to zero for unicast keys)
 165          * @seq_len: length of the @seq, depends on the algorithm:
 166          *      TKIP: 6 octets, CCMP: 6 octets
 167          * @key: key buffer; TKIP: 16-byte temporal key, 8-byte Tx Mic key,
 168          *      8-byte Rx Mic Key
 169          * @key_len: length of the key buffer in octets (WEP: 5 or 13,
 170          *      TKIP: 32, CCMP: 16)
 171          *
 172          * Returns: 0 on success, -1 on failure
 173          *
 174          * Configure the given key for the kernel driver. If the driver
 175          * supports separate individual keys (4 default keys + 1 individual),
 176          * @addr can be used to determine whether the key is default or
 177          * individual. If only 4 keys are supported, the default key with key
 178          * index 0 is used as the individual key. STA must be configured to use
 179          * it as the default Tx key (@set_tx is set) and accept Rx for all the
 180          * key indexes. In most cases, WPA uses only key indexes 1 and 2 for
 181          * broadcast keys, so key index 0 is available for this kind of
 182          * configuration.
 183          */
 184         int (*set_key)(void *priv, wpa_alg alg, const u8 *addr,
 185                        int key_idx, int set_tx, const u8 *seq, size_t seq_len,
 186                        const u8 *key, size_t key_len);
 187
 188         /**
 189          * init - initialize driver interface
 190          * @ctx: context to be used when calling wpa_supplicant functions,
 191          * e.g., wpa_supplicant_event()
 192          * @ifname: interface name, e.g., wlan0
 193          *
 194          * Return: pointer to private data, %NULL on failure
 195          *
 196          * Initialize driver interface, including event processing for kernel
 197          * driver events (e.g., associated, scan results, Michael MIC failure).
 198          * This function can allocate a private configuration data area for
 199          * @ctx, file descriptor, interface name, etc. information that may be
 200          * needed in future driver operations. If this is not used, non-NULL
 201          * value will need to be returned because %NULL is used to indicate
 202          * failure. The returned value will be used as 'void *priv' data for
 203          * all other driver_ops functions.
 204          *
 205          * The main event loop (eloop.c) of wpa_supplicant can be used to
 206          * register callback for read sockets (eloop_register_read_sock()).
 207          *
 208          * See wpa_supplicant.h for more information about events and
 209          * wpa_supplicant_event() function.
 210          */
 211         void * (*init)(void *ctx, const char *ifname);
 212
 213         /**
 214          * deinit - deinitialize driver interface
 215          * @priv: pointer to private data (from matching
 216          *      wpa_driver_events_init())
 217          *
 218          * Shut down driver interface and processing of driver events. Free
 219          * private data buffer if one was allocated in init() handler.
 220          */
 221         void (*deinit)(void *priv);
 222
 223         /**
 224          * set_countermeasures - enable/disable TKIP countermeasures
 225          * @priv: private driver interface data
 226          * @enabled: 1 = countermeasures enabled, 0 = disabled
 227          *
 228          * Return: 0 on success, -1 on failure
 229          *
 230          * Configure TKIP countermeasures. When these are enabled, the driver
 231          * should drop all received and queued frames that are using TKIP.
 232          */
 233         int (*set_countermeasures)(void *priv, int enabled);
 234
 235         /**
 236          * set_drop_unencrypted - enable/disable unencrypted frame filtering
 237          * @priv: private driver interface data
 238          * @enabled: 1 = unencrypted Tx/Rx frames will be dropped, 0 = disabled
 239          *
 240          * Return: 0 on success, -1 on failure
 241          *
 242          * Configure the driver to drop all non-EAPOL frames (both receive and
 243          * transmit paths). Unencrypted EAPOL frames (ethertype 0x888e) must
 244          * still be allowed for key negotiation.
 245          */
 246         int (*set_drop_unencrypted)(void *priv, int enabled);
 247
 248         /**
 249          * scan - request the driver to initiate scan
 250          * @priv: private driver interface data
 251          * @ssid: specific SSID to scan for (ProbeReq) or %NULL to scan for
 252          *      all SSIDs (either active scan with broadcast SSID or passive
 253          *      scan
 254          * @ssid_len: length of the SSID
 255          *
 256          * Return: 0 on success, -1 on failure
 257          *
 258          * Once the scan results are ready, the driver should report scan
 259          * results event for wpa_supplicant which will eventually request the
 260          * results with wpa_driver_get_scan_results().
 261          */
 262         int (*scan)(void *priv, const u8 *ssid, size_t ssid_len);
 263
 264         /**
 265          * get_scan_results - fetch the latest scan results
 266          * @priv: private driver interface data
 267          * @results: pointer to buffer for scan results
 268          * @max_size: maximum number of entries (buffer size)
 269          *
 270          * Return: number of scan result entries used on success, -1 on failure
 271          *
 272          * If scan results include more than @max_size BSSes, @max_size will be
 273          * returned and the remaining entries will not be included in the
 274          * buffer.
 275          */
 276         int (*get_scan_results)(void *priv,
 277                                 struct wpa_scan_result *results,
 278                                 size_t max_size);
 279
 280         /**
 281          * deauthenticate - request driver to deauthenticate
 282          * @priv: private driver interface data
 283          * @addr: peer address (BSSID of the AP)
 284          * @reason_code: 16-bit reason code to be sent in the deauthentication
 285          *      frame
 286          *
 287          * Return: 0 on success, -1 on failure
 288          */
 289         int (*deauthenticate)(void *priv, const u8 *addr, int reason_code);
 290
 291         /**
 292          * disassociate - request driver to disassociate
 293          * @priv: private driver interface data
 294          * @addr: peer address (BSSID of the AP)
 295          * @reason_code: 16-bit reason code to be sent in the disassociation
 296          *      frame
 297          *
 298          * Return: 0 on success, -1 on failure
 299          */
 300         int (*disassociate)(void *priv, const u8 *addr, int reason_code);
 301
 302         /**
 303          * associate - request driver to associate
 304          * @priv: private driver interface data
 305          * @params: association parameters
 306          *
 307          * Return: 0 on success, -1 on failure
 308          */
 309         int (*associate)(void *priv,
 310                          struct wpa_driver_associate_params *params);
 311
 312         /**
 313          * set_auth_alg - set IEEE 802.11 authentication algorithm
 314          * @priv: private driver interface data
 315          * @auth_alg: bit field of AUTH_ALG_*
 316          *
 317          * If the driver supports more than one authentication algorithm at the
 318          * same time, it should configure all supported algorithms. If not, one
 319          * algorithm needs to be selected arbitrarily. Open System
 320          * authentication should be ok for most cases and it is recommended to
 321          * be used if other options are not supported. Static WEP configuration
 322          * may also use Shared Key authentication and LEAP requires its own
 323          * algorithm number. For LEAP, user can make sure that only one
 324          * algorithm is used at a time by configuring LEAP as the only
 325          * supported EAP method. This information is also available in
 326          * associate() params, so set_auth_alg may not be needed in case of
 327          * most drivers.
 328          *
 329          * Return: 0 on success, -1 on failure
 330          */
 331         int (*set_auth_alg)(void *priv, int auth_alg);
 332
 333         /**
 334          * add_pmkid - add PMKSA cache entry to the driver
 335          * @priv: private driver interface data
 336          * @bssid: BSSID for the PMKSA cache entry
 337          * @pmkid: PMKID for the PMKSA cache entry
 338          *
 339          * Return: 0 on success, -1 on failure
 340          *
 341          * This function is called when a new PMK is received, as a result of
 342          * either normal authentication or RSN pre-authentication.
 343          *
 344          * If the driver generates RSN IE, i.e., it does not use @wpa_ie in
 345          * associate(), add_pmkid() can be used to add new PMKSA cache entries
 346          * in the driver. If the driver uses @wpa_ie from wpa_supplicant, this
 347          * driver_ops function does not need to be implemented. Likewise, if
 348          * the driver does not support WPA, this function is not needed.
 349          */
 350         int (*add_pmkid)(void *priv, const u8 *bssid, const u8 *pmkid);
 351
 352         /**
 353          * remove_pmkid - remove PMKSA cache entry to the driver
 354          * @priv: private driver interface data
 355          * @bssid: BSSID for the PMKSA cache entry
 356          * @pmkid: PMKID for the PMKSA cache entry
 357          *
 358          * Return: 0 on success, -1 on failure
 359          *
 360          * This function is called when the supplicant drops a PMKSA cache
 361          * entry for any reason.
 362          *
 363          * If the driver generates RSN IE, i.e., it does not use @wpa_ie in
 364          * associate(), remove_pmkid() can be used to synchronize PMKSA caches
 365          * between the driver and wpa_supplicant. If the driver uses @wpa_ie
 366          * from wpa_supplicant, this driver_ops function does not need to be
 367          * implemented. Likewise, if the driver does not support WPA, this
 368          * function is not needed.
 369          */
 370         int (*remove_pmkid)(void *priv, const u8 *bssid, const u8 *pmkid);
 371
 372         /**
 373          * flush_pmkid - flush PMKSA cache
 374          * @priv: private driver interface data
 375          *
 376          * Return: 0 on success, -1 on failure
 377          *
 378          * This function is called when the supplicant drops all PMKSA cache
 379          * entries for any reason.
 380          *
 381          * If the driver generates RSN IE, i.e., it does not use @wpa_ie in
 382          * associate(), remove_pmkid() can be used to synchronize PMKSA caches
 383          * between the driver and wpa_supplicant. If the driver uses @wpa_ie
 384          * from wpa_supplicant, this driver_ops function does not need to be
 385          * implemented. Likewise, if the driver does not support WPA, this
 386          * function is not needed.
 387          */
 388         int (*flush_pmkid)(void *priv);
 389
 390         /**
 391          * flush_pmkid - flush PMKSA cache
 392          * @priv: private driver interface data
 393          *
 394          * Return: 0 on success, -1 on failure
 395          *
 396          * Get driver/firmware/hardware capabilities.
 397          */
 398         int (*get_capa)(void *priv, struct wpa_driver_capa *capa);
 399
 400         /**
 401          * poll - poll driver for association information
 402          * @priv: private driver interface data
 403          *
 404          * This is an option callback that can be used when the driver does not
 405          * provide event mechanism for association events. This is called when
 406          * receiving WPA EAPOL-Key messages that require association
 407          * information. The driver interface is supposed to generate associnfo
 408          * event before returning from this callback function. In addition, the
 409          * driver interface should generate an association event after having
 410          * sent out associnfo.
 411          */
 412         void (*poll)(void *priv);
 413
 414         /**
 415          * get_ifname - get interface name
 416          *
 417          * This optional function can be used to allow the driver interface to
 418          * replace the interface name with something else, e.g., based on an
 419          * interface mapping from a more descriptive name.
 420          *
 421          * Returns a pointer to the interface name. This can differ from the
 422          * interface name used in init() call.
 423          */
 424         const char * (*get_ifname)(void *priv);
 425
 426         /**
 427          * get_mac_addr - get own MAC address
 428          *
 429          * This optional function can be used to get the own MAC address of the
 430          * device from the driver interface code. This is only needed if the
 431          * l2_packet implementation for the OS does not provide easy access to
 432          * a MAC address. */
 433         const u8 * (*get_mac_addr)(void *priv);
 434 };
 435
 436 #endif /* DRIVER_H */