driver.h

Go to the documentation of this file.

/*
 * Driver interface definition
 * Copyright (c) 2003-2010, Jouni Malinen <j@w1.fi>
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License version 2 as
 * published by the Free Software Foundation.
 *
 * Alternatively, this software may be distributed under the terms of BSD
 * license.
 *
 * See README and COPYING for more details.
 *
 * This file defines a driver interface used by both %wpa_supplicant and
 * hostapd. The first part of the file defines data structures used in various
 * driver operations. This is followed by the struct wpa_driver_ops that each
 * driver wrapper will beed to define with callback functions for requesting
 * driver operations. After this, there are definitions for driver event
 * reporting with wpa_supplicant_event() and some convenience helper functions
 * that can be used to report events.
 */

#ifndef DRIVER_H
#define DRIVER_H

#define WPA_SUPPLICANT_DRIVER_VERSION 4

#include "common/defs.h"

#define HOSTAPD_CHAN_DISABLED 0x00000001
#define HOSTAPD_CHAN_PASSIVE_SCAN 0x00000002
#define HOSTAPD_CHAN_NO_IBSS 0x00000004
#define HOSTAPD_CHAN_RADAR 0x00000008

struct hostapd_channel_data {
        short chan;

        short freq;

        int flag;

        u8 max_tx_power;
};

struct hostapd_hw_modes {
        enum hostapd_hw_mode mode;

        int num_channels;

        struct hostapd_channel_data *channels;

        int num_rates;

        int *rates;

        u16 ht_capab;

        u8 mcs_set[16];

        u8 a_mpdu_params;
};


#define IEEE80211_MODE_INFRA    0
#define IEEE80211_MODE_IBSS     1
#define IEEE80211_MODE_AP       2

#define IEEE80211_CAP_ESS       0x0001
#define IEEE80211_CAP_IBSS      0x0002
#define IEEE80211_CAP_PRIVACY   0x0010

#define WPA_SCAN_QUAL_INVALID           BIT(0)
#define WPA_SCAN_NOISE_INVALID          BIT(1)
#define WPA_SCAN_LEVEL_INVALID          BIT(2)
#define WPA_SCAN_LEVEL_DBM              BIT(3)
#define WPA_SCAN_AUTHENTICATED          BIT(4)
#define WPA_SCAN_ASSOCIATED             BIT(5)

struct wpa_scan_res {
        unsigned int flags;
        u8 bssid[ETH_ALEN];
        int freq;
        u16 beacon_int;
        u16 caps;
        int qual;
        int noise;
        int level;
        u64 tsf;
        unsigned int age;
        size_t ie_len;
        size_t beacon_ie_len;
        /*
         * Followed by ie_len octets of IEs from Probe Response frame (or if
         * the driver does not indicate source of IEs, these may also be from
         * Beacon frame). After the first set of IEs, another set of IEs may
         * follow (with beacon_ie_len octets of data) if the driver provides
         * both IE sets.
         */
};

struct wpa_scan_results {
        struct wpa_scan_res **res;
        size_t num;
};

struct wpa_interface_info {
        struct wpa_interface_info *next;
        char *ifname;
        char *desc;
        const char *drv_name;
};

#define WPAS_MAX_SCAN_SSIDS 4

struct wpa_driver_scan_params {
        struct wpa_driver_scan_ssid {
                const u8 *ssid;
                size_t ssid_len;
        } ssids[WPAS_MAX_SCAN_SSIDS];

        size_t num_ssids;

        const u8 *extra_ies;

        size_t extra_ies_len;

        int *freqs;

        struct wpa_driver_scan_filter {
                u8 ssid[32];
                size_t ssid_len;
        } *filter_ssids;

        size_t num_filter_ssids;
};

struct wpa_driver_auth_params {
        int freq;
        const u8 *bssid;
        const u8 *ssid;
        size_t ssid_len;
        int auth_alg;
        const u8 *ie;
        size_t ie_len;
        const u8 *wep_key[4];
        size_t wep_key_len[4];
        int wep_tx_keyidx;
        int local_state_change;
};

struct wpa_driver_associate_params {
        const u8 *bssid;

        const u8 *ssid;

        size_t ssid_len;

        int freq;

        const u8 *wpa_ie;

        size_t wpa_ie_len;

        enum wpa_cipher pairwise_suite;

        enum wpa_cipher group_suite;

        enum wpa_key_mgmt key_mgmt_suite;

        int auth_alg;

        int mode;

        const u8 *wep_key[4];

        size_t wep_key_len[4];

        int wep_tx_keyidx;

        enum mfp_options mgmt_frame_protection;

        const u8 *ft_ies;

        size_t ft_ies_len;

        const u8 *ft_md;

        const char *passphrase;

        const u8 *psk;

        int drop_unencrypted;

        const u8 *prev_bssid;
};

struct wpa_driver_capa {
#define WPA_DRIVER_CAPA_KEY_MGMT_WPA            0x00000001
#define WPA_DRIVER_CAPA_KEY_MGMT_WPA2           0x00000002
#define WPA_DRIVER_CAPA_KEY_MGMT_WPA_PSK        0x00000004
#define WPA_DRIVER_CAPA_KEY_MGMT_WPA2_PSK       0x00000008
#define WPA_DRIVER_CAPA_KEY_MGMT_WPA_NONE       0x00000010
#define WPA_DRIVER_CAPA_KEY_MGMT_FT             0x00000020
#define WPA_DRIVER_CAPA_KEY_MGMT_FT_PSK         0x00000040
        unsigned int key_mgmt;

#define WPA_DRIVER_CAPA_ENC_WEP40       0x00000001
#define WPA_DRIVER_CAPA_ENC_WEP104      0x00000002
#define WPA_DRIVER_CAPA_ENC_TKIP        0x00000004
#define WPA_DRIVER_CAPA_ENC_CCMP        0x00000008
        unsigned int enc;

#define WPA_DRIVER_AUTH_OPEN            0x00000001
#define WPA_DRIVER_AUTH_SHARED          0x00000002
#define WPA_DRIVER_AUTH_LEAP            0x00000004
        unsigned int auth;

/* Driver generated WPA/RSN IE */
#define WPA_DRIVER_FLAGS_DRIVER_IE      0x00000001
/* Driver needs static WEP key setup after association command */
#define WPA_DRIVER_FLAGS_SET_KEYS_AFTER_ASSOC 0x00000002
#define WPA_DRIVER_FLAGS_USER_SPACE_MLME 0x00000004
/* Driver takes care of RSN 4-way handshake internally; PMK is configured with
 * struct wpa_driver_ops::set_key using alg = WPA_ALG_PMK */
#define WPA_DRIVER_FLAGS_4WAY_HANDSHAKE 0x00000008
#define WPA_DRIVER_FLAGS_WIRED          0x00000010
/* Driver provides separate commands for authentication and association (SME in
 * wpa_supplicant). */
#define WPA_DRIVER_FLAGS_SME            0x00000020
/* Driver supports AP mode */
#define WPA_DRIVER_FLAGS_AP             0x00000040
/* Driver needs static WEP key setup after association has been completed */
#define WPA_DRIVER_FLAGS_SET_KEYS_AFTER_ASSOC_DONE      0x00000080
        unsigned int flags;

        int max_scan_ssids;

        unsigned int max_remain_on_chan;
};


struct hostapd_data;

struct hostap_sta_driver_data {
        unsigned long rx_packets, tx_packets, rx_bytes, tx_bytes;
        unsigned long current_tx_rate;
        unsigned long inactive_msec;
        unsigned long flags;
        unsigned long num_ps_buf_frames;
        unsigned long tx_retry_failed;
        unsigned long tx_retry_count;
        int last_rssi;
        int last_ack_rssi;
};

struct hostapd_sta_add_params {
        const u8 *addr;
        u16 aid;
        u16 capability;
        const u8 *supp_rates;
        size_t supp_rates_len;
        u16 listen_interval;
        const struct ieee80211_ht_capabilities *ht_capabilities;
};

struct hostapd_freq_params {
        int mode;
        int freq;
        int channel;
        int ht_enabled;
        int sec_channel_offset; /* 0 = HT40 disabled, -1 = HT40 enabled,
                                 * secondary channel below primary, 1 = HT40
                                 * enabled, secondary channel above primary */
};

enum wpa_driver_if_type {
        WPA_IF_STATION,

        WPA_IF_AP_VLAN,

        WPA_IF_AP_BSS,
};

struct wpa_init_params {
        const u8 *bssid;
        const char *ifname;
        const u8 *ssid;
        size_t ssid_len;
        const char *test_socket;
        int use_pae_group_addr;
        char **bridge;
        size_t num_bridge;

        u8 *own_addr; /* buffer for writing own MAC address */
};


struct wpa_bss_params {
        const char *ifname;
        int enabled;

        int wpa;
        int ieee802_1x;
        int wpa_group;
        int wpa_pairwise;
        int wpa_key_mgmt;
        int rsn_preauth;
};

#define WPA_STA_AUTHORIZED BIT(0)
#define WPA_STA_WMM BIT(1)
#define WPA_STA_SHORT_PREAMBLE BIT(2)
#define WPA_STA_MFP BIT(3)

struct wpa_driver_ops {
        const char *name;
        const char *desc;

        int (*get_bssid)(void *priv, u8 *bssid);

        int (*get_ssid)(void *priv, u8 *ssid);

        int (*set_key)(const char *ifname, void *priv, enum 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);

        void * (*init)(void *ctx, const char *ifname);

        void (*deinit)(void *priv);

        int (*set_param)(void *priv, const char *param);

        int (*set_countermeasures)(void *priv, int enabled);

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

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

        int (*associate)(void *priv,
                         struct wpa_driver_associate_params *params);

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

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

        int (*flush_pmkid)(void *priv);

        int (*get_capa)(void *priv, struct wpa_driver_capa *capa);

        void (*poll)(void *priv);

        const char * (*get_ifname)(void *priv);

        const u8 * (*get_mac_addr)(void *priv);

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

        int (*set_operstate)(void *priv, int state);

        int (*mlme_setprotection)(void *priv, const u8 *addr, int protect_type,
                                  int key_type);

        struct hostapd_hw_modes * (*get_hw_feature_data)(void *priv,
                                                         u16 *num_modes,
                                                         u16 *flags);

        int (*set_channel)(void *priv, enum hostapd_hw_mode phymode, int chan,
                           int freq);

        int (*set_ssid)(void *priv, const u8 *ssid, size_t ssid_len);

        int (*set_bssid)(void *priv, const u8 *bssid);

        int (*send_mlme)(void *priv, const u8 *data, size_t data_len);

        int (*mlme_add_sta)(void *priv, const u8 *addr, const u8 *supp_rates,
                            size_t supp_rates_len);

        int (*mlme_remove_sta)(void *priv, const u8 *addr);

        int (*update_ft_ies)(void *priv, const u8 *md, const u8 *ies,
                             size_t ies_len);

        int (*send_ft_action)(void *priv, u8 action, const u8 *target_ap,
                              const u8 *ies, size_t ies_len);

         struct wpa_scan_results * (*get_scan_results2)(void *priv);

        int (*set_country)(void *priv, const char *alpha2);

        void * (*global_init)(void);

        void (*global_deinit)(void *priv);

        void * (*init2)(void *ctx, const char *ifname, void *global_priv);

        struct wpa_interface_info * (*get_interfaces)(void *global_priv);

        int (*scan2)(void *priv, struct wpa_driver_scan_params *params);

        int (*authenticate)(void *priv,
                            struct wpa_driver_auth_params *params);

        int (*set_beacon)(void *priv, const u8 *head, size_t head_len,
                          const u8 *tail, size_t tail_len, int dtim_period,
                          int beacon_int);

        void * (*hapd_init)(struct hostapd_data *hapd,
                            struct wpa_init_params *params);

        void (*hapd_deinit)(void *priv);

        int (*set_ieee8021x)(void *priv, struct wpa_bss_params *params);

        int (*set_privacy)(void *priv, int enabled);

        int (*get_seqnum)(const char *ifname, void *priv, const u8 *addr,
                          int idx, u8 *seq);

        int (*flush)(void *priv);

        int (*set_generic_elem)(void *priv, const u8 *elem, size_t elem_len);

        int (*read_sta_data)(void *priv, struct hostap_sta_driver_data *data,
                             const u8 *addr);

        int (*hapd_send_eapol)(void *priv, const u8 *addr, const u8 *data,
                               size_t data_len, int encrypt,
                               const u8 *own_addr);

        int (*sta_deauth)(void *priv, const u8 *own_addr, const u8 *addr,
                          int reason);

        int (*sta_disassoc)(void *priv, const u8 *own_addr, const u8 *addr,
                            int reason);

        int (*sta_remove)(void *priv, const u8 *addr);

        int (*hapd_get_ssid)(void *priv, u8 *buf, int len);

        int (*hapd_set_ssid)(void *priv, const u8 *buf, int len);

        int (*hapd_set_countermeasures)(void *priv, int enabled);

        int (*sta_add)(void *priv, struct hostapd_sta_add_params *params);

        int (*get_inact_sec)(void *priv, const u8 *addr);

        int (*sta_clear_stats)(void *priv, const u8 *addr);

        int (*set_freq)(void *priv, struct hostapd_freq_params *freq);

        int (*set_rts)(void *priv, int rts);

        int (*set_frag)(void *priv, int frag);

        int (*sta_set_flags)(void *priv, const u8 *addr,
                             int total_flags, int flags_or, int flags_and);

        int (*set_rate_sets)(void *priv, int *supp_rates, int *basic_rates,
                             int mode);

        int (*set_cts_protect)(void *priv, int value);

        int (*set_preamble)(void *priv, int value);

        int (*set_short_slot_time)(void *priv, int value);

        int (*set_tx_queue_params)(void *priv, int queue, int aifs, int cw_min,
                                   int cw_max, int burst_time);

        int (*valid_bss_mask)(void *priv, const u8 *addr, const u8 *mask);

        int (*if_add)(void *priv, enum wpa_driver_if_type type,
                      const char *ifname, const u8 *addr, void *bss_ctx,
                      void **drv_priv, char *force_ifname, u8 *if_addr);

        int (*if_remove)(void *priv, enum wpa_driver_if_type type,
                         const char *ifname);

        int (*set_sta_vlan)(void *priv, const u8 *addr, const char *ifname,
                            int vlan_id);

        int (*commit)(void *priv);

        int (*send_ether)(void *priv, const u8 *dst, const u8 *src, u16 proto,
                          const u8 *data, size_t data_len);

        int (*set_radius_acl_auth)(void *priv, const u8 *mac, int accepted, 
                                   u32 session_timeout);

        int (*set_radius_acl_expire)(void *priv, const u8 *mac);

        int (*set_ht_params)(void *priv,
                             const u8 *ht_capab, size_t ht_capab_len,
                             const u8 *ht_oper, size_t ht_oper_len);

        int (*set_ap_wps_ie)(void *priv, const struct wpabuf *beacon,
                             const struct wpabuf *proberesp);

        int (*set_supp_port)(void *priv, int authorized);

        int (*set_wds_sta)(void *priv, const u8 *addr, int aid, int val);

        int (*send_action)(void *priv, unsigned int freq,
                           const u8 *dst, const u8 *src, const u8 *bssid,
                           const u8 *data, size_t data_len);

        int (*remain_on_channel)(void *priv, unsigned int freq,
                                 unsigned int duration);

        int (*cancel_remain_on_channel)(void *priv);

        int (*probe_req_report)(void *priv, int report);

        int (*disable_11b_rates)(void *priv, int disabled);

        int (*deinit_ap)(void *priv);

        void (*suspend)(void *priv);

        void (*resume)(void *priv);

        int (*signal_monitor)(void *priv, int threshold, int hysteresis);

        int (*send_frame)(void *priv, const u8 *data, size_t data_len,
                          int encrypt);
};


enum wpa_event_type {
        EVENT_ASSOC,

        EVENT_DISASSOC,

        EVENT_MICHAEL_MIC_FAILURE,

        EVENT_SCAN_RESULTS,

        EVENT_ASSOCINFO,

        EVENT_INTERFACE_STATUS,

        EVENT_PMKID_CANDIDATE,

        EVENT_STKSTART,

        EVENT_FT_RESPONSE,

        EVENT_IBSS_RSN_START,

        EVENT_AUTH,

        EVENT_DEAUTH,

        EVENT_ASSOC_REJECT,

        EVENT_AUTH_TIMED_OUT,

        EVENT_ASSOC_TIMED_OUT,

        EVENT_FT_RRB_RX,

        EVENT_WPS_BUTTON_PUSHED,

        EVENT_TX_STATUS,

        EVENT_RX_FROM_UNKNOWN,

        EVENT_RX_MGMT,

        EVENT_RX_ACTION,

        EVENT_REMAIN_ON_CHANNEL,

        EVENT_CANCEL_REMAIN_ON_CHANNEL,

        EVENT_MLME_RX,

        EVENT_RX_PROBE_REQ,

        EVENT_NEW_STA,

        EVENT_EAPOL_RX,

        EVENT_SIGNAL_CHANGE
};


union wpa_event_data {
        struct assoc_info {
                const u8 *req_ies;

                size_t req_ies_len;

                const u8 *resp_ies;

                size_t resp_ies_len;

                const u8 *beacon_ies;

                size_t beacon_ies_len;

                unsigned int freq;

                const u8 *addr;
        } assoc_info;

        struct disassoc_info {
                const u8 *addr;

                u16 reason_code;
        } disassoc_info;

        struct deauth_info {
                const u8 *addr;

                u16 reason_code;
        } deauth_info;

        struct michael_mic_failure {
                int unicast;
                const u8 *src;
        } michael_mic_failure;

        struct interface_status {
                char ifname[100];
                enum {
                        EVENT_INTERFACE_ADDED, EVENT_INTERFACE_REMOVED
                } ievent;
        } interface_status;

        struct pmkid_candidate {
                u8 bssid[ETH_ALEN];
                int index;
                int preauth;
        } pmkid_candidate;

        struct stkstart {
                u8 peer[ETH_ALEN];
        } stkstart;

        struct ft_ies {
                const u8 *ies;
                size_t ies_len;
                int ft_action;
                u8 target_ap[ETH_ALEN];
                const u8 *ric_ies;
                size_t ric_ies_len;
        } ft_ies;

        struct ibss_rsn_start {
                u8 peer[ETH_ALEN];
        } ibss_rsn_start;

        struct auth_info {
                u8 peer[ETH_ALEN];
                u16 auth_type;
                u16 status_code;
                const u8 *ies;
                size_t ies_len;
        } auth;

        struct assoc_reject {
                u8 *resp_ies;

                size_t resp_ies_len;

                u16 status_code;
        } assoc_reject;

        struct timeout_event {
                u8 addr[ETH_ALEN];
        } timeout_event;

        struct ft_rrb_rx {
                const u8 *src;
                const u8 *data;
                size_t data_len;
        } ft_rrb_rx;

        struct tx_status {
                u16 type;
                u16 stype;
                const u8 *dst;
                const u8 *data;
                size_t data_len;
                int ack;
        } tx_status;

        struct rx_from_unknown {
                const u8 *frame;
                size_t len;
        } rx_from_unknown;

        struct rx_mgmt {
                const u8 *frame;
                size_t frame_len;
                u32 datarate;
                u32 ssi_signal;
        } rx_mgmt;

        struct rx_action {
                const u8 *da;

                const u8 *sa;

                const u8 *bssid;

                u8 category;

                const u8 *data;

                size_t len;

                int freq;
        } rx_action;

        struct remain_on_channel {
                unsigned int freq;

                unsigned int duration;
        } remain_on_channel;

        struct scan_info {
                int aborted;
                const int *freqs;
                size_t num_freqs;
                struct wpa_driver_scan_ssid ssids[WPAS_MAX_SCAN_SSIDS];
                size_t num_ssids;
        } scan_info;

        struct mlme_rx {
                const u8 *buf;
                size_t len;
                int freq;
                int channel;
                int ssi;
        } mlme_rx;

        struct rx_probe_req {
                const u8 *sa;

                const u8 *ie;

                size_t ie_len;
        } rx_probe_req;

        struct new_sta {
                const u8 *addr;
        } new_sta;

        struct eapol_rx {
                const u8 *src;
                const u8 *data;
                size_t data_len;
        } eapol_rx;

        struct signal_change {
                int above_threshold;
        } signal_change;
};

void wpa_supplicant_event(void *ctx, enum wpa_event_type event,
                          union wpa_event_data *data);


/*
 * The following inline functions are provided for convenience to simplify
 * event indication for some of the common events.
 */

static inline void drv_event_assoc(void *ctx, const u8 *addr, const u8 *ie,
                                   size_t ielen)
{
        union wpa_event_data event;
        os_memset(&event, 0, sizeof(event));
        event.assoc_info.req_ies = ie;
        event.assoc_info.req_ies_len = ielen;
        event.assoc_info.addr = addr;
        wpa_supplicant_event(ctx, EVENT_ASSOC, &event);
}

static inline void drv_event_disassoc(void *ctx, const u8 *addr)
{
        union wpa_event_data event;
        os_memset(&event, 0, sizeof(event));
        event.disassoc_info.addr = addr;
        wpa_supplicant_event(ctx, EVENT_DISASSOC, &event);
}

static inline void drv_event_eapol_rx(void *ctx, const u8 *src, const u8 *data,
                                      size_t data_len)
{
        union wpa_event_data event;
        os_memset(&event, 0, sizeof(event));
        event.eapol_rx.src = src;
        event.eapol_rx.data = data;
        event.eapol_rx.data_len = data_len;
        wpa_supplicant_event(ctx, EVENT_EAPOL_RX, &event);
}

#endif /* DRIVER_H */