wpa_driver_ops Struct Reference

Driver interface API definition. More...

#include <driver.h>


Data Fields

const char * name
const char * desc
int(* get_bssid )(void *priv, u8 *bssid)
 Get the current BSSID.
int(* get_ssid )(void *priv, u8 *ssid)
 Get the current SSID.
int(* set_wpa )(void *priv, int enabled)
 Enable/disable WPA support (OBSOLETE).
int(* set_key )(void *priv, wpa_alg alg, const u8 *addr, int key_idx, int set_tx, const u8 *seq, size_t seq_len, const u8 *key, size_t key_len)
 Configure encryption key.
void *(* init )(void *ctx, const char *ifname)
 Initialize driver interface.
void(* deinit )(void *priv)
 Deinitialize driver interface.
int(* set_param )(void *priv, const char *param)
 Set driver configuration parameters.
int(* set_countermeasures )(void *priv, int enabled)
 Enable/disable TKIP countermeasures.
int(* set_drop_unencrypted )(void *priv, int enabled)
 Enable/disable unencrypted frame filtering.
int(* scan )(void *priv, const u8 *ssid, size_t ssid_len)
 Request the driver to initiate scan.
int(* get_scan_results )(void *priv, struct wpa_scan_result *results, size_t max_size)
 Fetch the latest scan results.
int(* deauthenticate )(void *priv, const u8 *addr, int reason_code)
 Request driver to deauthenticate.
int(* disassociate )(void *priv, const u8 *addr, int reason_code)
 Request driver to disassociate.
int(* associate )(void *priv, struct wpa_driver_associate_params *params)
 Request driver to associate.
int(* set_auth_alg )(void *priv, int auth_alg)
 Set IEEE 802.11 authentication algorithm.
int(* add_pmkid )(void *priv, const u8 *bssid, const u8 *pmkid)
 Add PMKSA cache entry to the driver.
int(* remove_pmkid )(void *priv, const u8 *bssid, const u8 *pmkid)
 Remove PMKSA cache entry to the driver.
int(* flush_pmkid )(void *priv)
 Flush PMKSA cache.
int(* get_capa )(void *priv, struct wpa_driver_capa *capa)
 Flush PMKSA cache.
void(* poll )(void *priv)
 Poll driver for association information.
const char *(* get_ifname )(void *priv)
 Get interface name.
const u8 *(* get_mac_addr )(void *priv)
 Get own MAC address.
int(* send_eapol )(void *priv, const u8 *dest, u16 proto, const u8 *data, size_t data_len)
 Optional function for sending EAPOL packets.


Detailed Description

Driver interface API definition.

This structure defines the API that each driver interface needs to implement for core wpa_supplicant code. All driver specific functionality is captured in this wrapper.

Definition at line 181 of file driver.h.


Field Documentation

int(* wpa_driver_ops::add_pmkid)(void *priv, const u8 *bssid, const u8 *pmkid)
 

Add PMKSA cache entry to the driver.

Parameters:
priv private driver interface data
bssid BSSID for the PMKSA cache entry
pmkid PMKID for the PMKSA cache entry
Returns:
0 on success, -1 on failure
This function is called when a new PMK is received, as a result of either normal authentication or RSN pre-authentication.

If the driver generates RSN IE, i.e., it does not use wpa_ie in associate(), add_pmkid() can be used to add new PMKSA cache entries in the driver. If the driver uses wpa_ie from wpa_supplicant, this driver_ops function does not need to be implemented. Likewise, if the driver does not support WPA, this function is not needed.

int(* wpa_driver_ops::associate)(void *priv, struct wpa_driver_associate_params *params)
 

Request driver to associate.

Parameters:
priv private driver interface data
params association parameters
Returns:
0 on success, -1 on failure

int(* wpa_driver_ops::deauthenticate)(void *priv, const u8 *addr, int reason_code)
 

Request driver to deauthenticate.

Parameters:
priv private driver interface data
addr peer address (BSSID of the AP)
reason_code 16-bit reason code to be sent in the deauthentication frame
Returns:
0 on success, -1 on failure

void(* wpa_driver_ops::deinit)(void *priv)
 

Deinitialize driver interface.

Parameters:
priv private driver interface data from init()
Shut down driver interface and processing of driver events. Free private data buffer if one was allocated in init() handler.

const char* wpa_driver_ops::desc
 

One line description of the driver interface

Definition at line 185 of file driver.h.

int(* wpa_driver_ops::disassociate)(void *priv, const u8 *addr, int reason_code)
 

Request driver to disassociate.

Parameters:
priv private driver interface data
addr peer address (BSSID of the AP)
reason_code 16-bit reason code to be sent in the disassociation frame
Returns:
0 on success, -1 on failure

int(* wpa_driver_ops::flush_pmkid)(void *priv)
 

Flush PMKSA cache.

Parameters:
priv private driver interface data
Returns:
0 on success, -1 on failure
This function is called when the supplicant drops all PMKSA cache entries for any reason.

If the driver generates RSN IE, i.e., it does not use wpa_ie in associate(), remove_pmkid() can be used to synchronize PMKSA caches between the driver and wpa_supplicant. If the driver uses wpa_ie from wpa_supplicant, this driver_ops function does not need to be implemented. Likewise, if the driver does not support WPA, this function is not needed.

int(* wpa_driver_ops::get_bssid)(void *priv, u8 *bssid)
 

Get the current BSSID.

Parameters:
priv private driver interface data
bssid buffer for BSSID (ETH_ALEN = 6 bytes)
Returns:
0 on success, -1 on failure
Query kernel driver for the current BSSID and copy it to bssid. Setting bssid to 00:00:00:00:00:00 is recommended if the STA is not associated.

int(* wpa_driver_ops::get_capa)(void *priv, struct wpa_driver_capa *capa)
 

Flush PMKSA cache.

Parameters:
priv private driver interface data
Returns:
0 on success, -1 on failure
Get driver/firmware/hardware capabilities.

const char*(* wpa_driver_ops::get_ifname)(void *priv)
 

Get interface name.

Parameters:
priv private driver interface data
Returns:
Pointer to the interface name. This can differ from the interface name used in init() call.
This optional function can be used to allow the driver interface to replace the interface name with something else, e.g., based on an interface mapping from a more descriptive name.

const u8*(* wpa_driver_ops::get_mac_addr)(void *priv)
 

Get own MAC address.

Parameters:
priv private driver interface data
Returns:
Pointer to own MAC address or NULL on failure
This optional function can be used to get the own MAC address of the device from the driver interface code. This is only needed if the l2_packet implementation for the OS does not provide easy access to a MAC address.

int(* wpa_driver_ops::get_scan_results)(void *priv, struct wpa_scan_result *results, size_t max_size)
 

Fetch the latest scan results.

Parameters:
priv private driver interface data
results pointer to buffer for scan results
max_size maximum number of entries (buffer size)
Returns:
Number of scan result entries used on success, -1 on failure
If scan results include more than max_size BSSes, max_size will be returned and the remaining entries will not be included in the buffer.

int(* wpa_driver_ops::get_ssid)(void *priv, u8 *ssid)
 

Get the current SSID.

Parameters:
priv private driver interface data
ssid buffer for SSID (at least 32 bytes)
Returns:
Length of the SSID on success, -1 on failure
Query kernel driver for the current SSID and copy it to ssid. Returning zero is recommended if the STA is not associated.

Note: SSID is an array of octets, i.e., it is not nul terminated and can, at least in theory, contain control characters (including nul) and as such, should be processed as binary data, not a printable string.

void*(* wpa_driver_ops::init)(void *ctx, const char *ifname)
 

Initialize driver interface.

Parameters:
ctx context to be used when calling wpa_supplicant functions, e.g., wpa_supplicant_event()
ifname interface name, e.g., wlan0
Returns:
Pointer to private data, NULL on failure
Initialize driver interface, including event processing for kernel driver events (e.g., associated, scan results, Michael MIC failure). This function can allocate a private configuration data area for
Parameters:
ctx file descriptor, interface name, etc. information that may be needed in future driver operations. If this is not used, non-NULL value will need to be returned because NULL is used to indicate failure. The returned value will be used as 'void *priv' data for all other driver_ops functions.
The main event loop (eloop.c) of wpa_supplicant can be used to register callback for read sockets (eloop_register_read_sock()).

See wpa_supplicant.h for more information about events and wpa_supplicant_event() function.

const char* wpa_driver_ops::name
 

Name of the driver interface

Definition at line 183 of file driver.h.

void(* wpa_driver_ops::poll)(void *priv)
 

Poll driver for association information.

Parameters:
priv private driver interface data
This is an option callback that can be used when the driver does not provide event mechanism for association events. This is called when receiving WPA EAPOL-Key messages that require association information. The driver interface is supposed to generate associnfo event before returning from this callback function. In addition, the driver interface should generate an association event after having sent out associnfo.

int(* wpa_driver_ops::remove_pmkid)(void *priv, const u8 *bssid, const u8 *pmkid)
 

Remove PMKSA cache entry to the driver.

Parameters:
priv private driver interface data
bssid BSSID for the PMKSA cache entry
pmkid PMKID for the PMKSA cache entry
Returns:
0 on success, -1 on failure
This function is called when the supplicant drops a PMKSA cache entry for any reason.

If the driver generates RSN IE, i.e., it does not use wpa_ie in associate(), remove_pmkid() can be used to synchronize PMKSA caches between the driver and wpa_supplicant. If the driver uses wpa_ie from wpa_supplicant, this driver_ops function does not need to be implemented. Likewise, if the driver does not support WPA, this function is not needed.

int(* wpa_driver_ops::scan)(void *priv, const u8 *ssid, size_t ssid_len)
 

Request the driver to initiate scan.

Parameters:
priv private driver interface data
ssid specific SSID to scan for (ProbeReq) or NULL to scan for all SSIDs (either active scan with broadcast SSID or passive scan
ssid_len length of the SSID
Returns:
0 on success, -1 on failure
Once the scan results are ready, the driver should report scan results event for wpa_supplicant which will eventually request the results with wpa_driver_get_scan_results().

int(* wpa_driver_ops::send_eapol)(void *priv, const u8 *dest, u16 proto, const u8 *data, size_t data_len)
 

Optional function for sending EAPOL packets.

Parameters:
priv private driver interface data
dest Destination MAC address
proto Ethertype
data EAPOL packet starting with IEEE 802.1X header
data_len Size of the EAPOL packet
Returns:
0 on success, -1 on failure
This optional function can be used to override l2_packet operations with driver specific functionality. If this function pointer is set, l2_packet module is not used at all and the driver interface code is responsible for receiving and sending all EAPOL packets. The received EAPOL packets are sent to core code by calling wpa_supplicant_rx_eapol(). The driver interface is required to implement get_mac_addr() handler if send_eapol() is used.

int(* wpa_driver_ops::set_auth_alg)(void *priv, int auth_alg)
 

Set IEEE 802.11 authentication algorithm.

Parameters:
priv private driver interface data
auth_alg bit field of AUTH_ALG_*
If the driver supports more than one authentication algorithm at the same time, it should configure all supported algorithms. If not, one algorithm needs to be selected arbitrarily. Open System authentication should be ok for most cases and it is recommended to be used if other options are not supported. Static WEP configuration may also use Shared Key authentication and LEAP requires its own algorithm number. For LEAP, user can make sure that only one algorithm is used at a time by configuring LEAP as the only supported EAP method. This information is also available in associate() params, so set_auth_alg may not be needed in case of most drivers.

Returns:
0 on success, -1 on failure

int(* wpa_driver_ops::set_countermeasures)(void *priv, int enabled)
 

Enable/disable TKIP countermeasures.

Parameters:
priv private driver interface data
enabled 1 = countermeasures enabled, 0 = disabled
Returns:
0 on success, -1 on failure
Configure TKIP countermeasures. When these are enabled, the driver should drop all received and queued frames that are using TKIP.

int(* wpa_driver_ops::set_drop_unencrypted)(void *priv, int enabled)
 

Enable/disable unencrypted frame filtering.

Parameters:
priv private driver interface data
enabled 1 = unencrypted Tx/Rx frames will be dropped, 0 = disabled
Returns:
0 on success, -1 on failure
Configure the driver to drop all non-EAPOL frames (both receive and transmit paths). Unencrypted EAPOL frames (ethertype 0x888e) must still be allowed for key negotiation.

int(* wpa_driver_ops::set_key)(void *priv, wpa_alg alg, const u8 *addr, int key_idx, int set_tx, const u8 *seq, size_t seq_len, const u8 *key, size_t key_len)
 

Configure encryption key.

Parameters:
priv private driver interface data
alg encryption algorithm (WPA_ALG_NONE, WPA_ALG_WEP, WPA_ALG_TKIP, WPA_ALG_CCMP); WPA_ALG_NONE clears the key.
addr address of the peer STA or ff:ff:ff:ff:ff:ff for broadcast/default keys
key_idx key index (0..3), usually 0 for unicast keys
set_tx configure this key as the default Tx key (only used when driver does not support separate unicast/individual key
seq sequence number/packet number, seq_len octets, the next packet number to be used for in replay protection; configured for Rx keys (in most cases, this is only used with broadcast keys and set to zero for unicast keys)
seq_len length of the seq, depends on the algorithm: TKIP: 6 octets, CCMP: 6 octets
key key buffer; TKIP: 16-byte temporal key, 8-byte Tx Mic key, 8-byte Rx Mic Key
key_len length of the key buffer in octets (WEP: 5 or 13, TKIP: 32, CCMP: 16)
Returns:
0 on success, -1 on failure
Configure the given key for the kernel driver. If the driver supports separate individual keys (4 default keys + 1 individual), addr can be used to determine whether the key is default or individual. If only 4 keys are supported, the default key with key index 0 is used as the individual key. STA must be configured to use it as the default Tx key (set_tx is set) and accept Rx for all the key indexes. In most cases, WPA uses only key indexes 1 and 2 for broadcast keys, so key index 0 is available for this kind of configuration.

Please note that TKIP keys include separate TX and RX MIC keys and some drivers may expect them in different order than wpa_supplicant is using. If the TX/RX keys are swapped, all TKIP encrypted packets will tricker Michael MIC errors. This can be fixed by changing the order of MIC keys by swapping te bytes 16..23 and 24..31 of the key in driver_*.c set_key() implementation, see driver_ndis.c for an example on how this can be done.

int(* wpa_driver_ops::set_param)(void *priv, const char *param)
 

Set driver configuration parameters.

Parameters:
priv private driver interface data from init()
param driver specific configuration parameters
Returns:
0 on success, -1 on failure
Optional handler for notifying driver interface about configuration parameters (driver_param).

int(* wpa_driver_ops::set_wpa)(void *priv, int enabled)
 

Enable/disable WPA support (OBSOLETE).

Parameters:
priv private driver interface data
enabled 1 = enable, 0 = disable
Returns:
0 on success, -1 on failure
Note: This function is included for backwards compatibility. This is called only just after init and just before deinit, so these functions can be used to implement same functionality and the driver interface need not define this function.

Configure the kernel driver to enable/disable WPA support. This may be empty function, if WPA support is always enabled. Common configuration items are WPA IE (clearing it when WPA support is disabled), Privacy flag configuration for capability field (note: this the value need to set in associate handler to allow plaintext mode to be used) when trying to associate with, roaming mode (can allow wpa_supplicant to control roaming if ap_scan=1 is used; however, drivers can also implement roaming if desired, especially ap_scan=2 mode is used for this).


The documentation for this struct was generated from the following file:
Generated on Sat May 6 21:20:22 2006 for wpa_supplicant by  doxygen 1.4.2