Added Doxygen documentation for WPS code

This commit is contained in:
Jouni Malinen 2009-01-03 19:50:49 +02:00
parent 875f6d7b93
commit f90c86d4a3
11 changed files with 394 additions and 43 deletions

View File

@ -27,7 +27,7 @@ struct eap_wsc_data {
int registrar;
struct wpabuf *in_buf;
struct wpabuf *out_buf;
u8 in_op_code, out_op_code;
enum wsc_op_code in_op_code, out_op_code;
size_t out_used;
size_t fragment_size;
struct wps_data *wps;

View File

@ -25,7 +25,7 @@ struct eap_wsc_data {
int registrar;
struct wpabuf *in_buf;
struct wpabuf *out_buf;
u8 in_op_code, out_op_code;
enum wsc_op_code in_op_code, out_op_code;
size_t out_used;
size_t fragment_size;
struct wps_data *wps;

View File

@ -20,6 +20,16 @@
#include "ieee802_11_defs.h"
/**
* wps_init - Initialize WPS Registration protocol data
* @cfg: WPS configuration
* Returns: Pointer to allocated data or %NULL on failure
*
* This function is used to initialize WPS data for a registration protocol
* instance (i.e., each run of registration protocol as a Registrar of
* Enrollee. The caller is responsible for freeing this data after the
* registration run has been completed by calling wps_deinit().
*/
struct wps_data * wps_init(const struct wps_config *cfg)
{
struct wps_data *data = os_zalloc(sizeof(*data));
@ -83,6 +93,10 @@ struct wps_data * wps_init(const struct wps_config *cfg)
}
/**
* wps_deinit - Deinitialize WPS Registration protocol data
* @data: WPS Registration protocol data from wps_init()
*/
void wps_deinit(struct wps_data *data)
{
if (data->wps_pin_revealed) {
@ -105,7 +119,20 @@ void wps_deinit(struct wps_data *data)
}
enum wps_process_res wps_process_msg(struct wps_data *wps, u8 op_code,
/**
* wps_process_msg - Process a WPS message
* @wps: WPS Registration protocol data from wps_init()
* @op_code: Message OP Code
* @msg: Message data
* Returns: Processing result
*
* This function is used to process WPS messages with OP Codes WSC_ACK,
* WSC_NACK, WSC_MSG, and WSC_Done. The caller (e.g., EAP server/peer) is
* responsible for reassembling the messages before calling this function.
* Response to this message is built by calling wps_get_msg().
*/
enum wps_process_res wps_process_msg(struct wps_data *wps,
enum wsc_op_code op_code,
const struct wpabuf *msg)
{
if (wps->registrar)
@ -115,7 +142,16 @@ enum wps_process_res wps_process_msg(struct wps_data *wps, u8 op_code,
}
struct wpabuf * wps_get_msg(struct wps_data *wps, u8 *op_code)
/**
* wps_get_msg - Build a WPS message
* @wps: WPS Registration protocol data from wps_init()
* @op_code: Buffer for returning message OP Code
* Returns: The generated WPS message or %NULL on failure
*
* This function is used to build a response to a message processed by calling
* wps_process_msg(). The caller is responsible for freeing the buffer.
*/
struct wpabuf * wps_get_msg(struct wps_data *wps, enum wsc_op_code *op_code)
{
if (wps->registrar)
return wps_registrar_get_msg(wps, op_code);
@ -124,6 +160,11 @@ struct wpabuf * wps_get_msg(struct wps_data *wps, u8 *op_code)
}
/**
* wps_is_selected_pbc_registrar - Check whether WPS IE indicates active PBC
* @msg: WPS IE contents from Beacon or Probe Response frame
* Returns: 1 if PBC Registrar is active, 0 if not
*/
int wps_is_selected_pbc_registrar(const struct wpabuf *msg)
{
struct wps_parse_attr attr;
@ -145,6 +186,11 @@ int wps_is_selected_pbc_registrar(const struct wpabuf *msg)
}
/**
* wps_is_selected_pbc_registrar - Check whether WPS IE indicates active PIN
* @msg: WPS IE contents from Beacon or Probe Response frame
* Returns: 1 if PIN Registrar is active, 0 if not
*/
int wps_is_selected_pin_registrar(const struct wpabuf *msg)
{
struct wps_parse_attr attr;
@ -167,6 +213,14 @@ int wps_is_selected_pin_registrar(const struct wpabuf *msg)
}
/**
* wps_get_uuid_e - Get UUID-E from WPS IE
* @msg: WPS IE contents from Beacon or Probe Response frame
* Returns: Pointer to UUID-E or %NULL if not included
*
* The returned pointer is to the msg contents and it remains valid only as
* long as the msg buffer is valid.
*/
const u8 * wps_get_uuid_e(const struct wpabuf *msg)
{
struct wps_parse_attr attr;
@ -177,7 +231,14 @@ const u8 * wps_get_uuid_e(const struct wpabuf *msg)
}
struct wpabuf * wps_build_assoc_req_ie(u8 req_type)
/**
* wps_build_assoc_req_ie - Build WPS IE for (Re)Association Request
* @req_type: Value for Request Type attribute
* Returns: WPS IE or %NULL on failure
*
* The caller is responsible for freeing the buffer.
*/
struct wpabuf * wps_build_assoc_req_ie(enum wps_request_type req_type)
{
struct wpabuf *ie;
u8 *len;
@ -204,8 +265,19 @@ struct wpabuf * wps_build_assoc_req_ie(u8 req_type)
}
/**
* wps_build_probe_req_ie - Build WPS IE for Probe Request
* @pbc: Whether searching for PBC mode APs
* @dev: Device attributes
* @uuid: Own UUID
* @req_type: Value for Request Type attribute
* Returns: WPS IE or %NULL on failure
*
* The caller is responsible for freeing the buffer.
*/
struct wpabuf * wps_build_probe_req_ie(int pbc, struct wps_device_data *dev,
const u8 *uuid, u8 req_type)
const u8 *uuid,
enum wps_request_type req_type)
{
struct wpabuf *ie;
u8 *len;

View File

@ -15,6 +15,11 @@
#ifndef WPS_H
#define WPS_H
#include "wps_defs.h"
/**
* enum wsc_op_code - EAP-WSC OP-Code values
*/
enum wsc_op_code {
WSC_Start = 0x01,
WSC_ACK = 0x02,
@ -26,6 +31,17 @@ enum wsc_op_code {
struct wps_registrar;
/**
* struct wps_credential - WPS Credential
* @ssid: SSID
* @ssid_len: Length of SSID
* @auth_type: Authentication Type (WPS_AUTH_OPEN, .. flags)
* @encr_type: Encryption Type (WPS_ENCR_NONE, .. flags)
* @key_idx: Key index
* @key: Key
* @key_len: Key length in octets
* @mac_addr: MAC address of the peer
*/
struct wps_credential {
u8 ssid[32];
size_t ssid_len;
@ -37,6 +53,20 @@ struct wps_credential {
u8 mac_addr[ETH_ALEN];
};
/**
* struct wps_device_data - WPS Device Data
* @mac_addr: Device MAC address
* @device_name: Device Name (0..32 octets encoded in UTF-8)
* @manufacturer: Manufacturer (0..64 octets encoded in UTF-8)
* @model_name: Model Name (0..32 octets encoded in UTF-8)
* @model_number: Model Number (0..32 octets encoded in UTF-8)
* @serial_number: Serial Number (0..32 octets encoded in UTF-8)
* @categ: Primary Device Category
* @oui: Primary Device OUI
* @sub_categ: Primary Device Sub-Category
* @os_version: OS Version
* @rf_bands: RF bands (WPS_RF_24GHZ, WPS_RF_50GHZ flags)
*/
struct wps_device_data {
u8 mac_addr[ETH_ALEN];
char *device_name;
@ -48,58 +78,175 @@ struct wps_device_data {
u32 oui;
u16 sub_categ;
u32 os_version;
u8 rf_bands; /* WPS_RF_* */
u8 rf_bands;
};
/**
* struct wps_config - WPS configuration for a single registration protocol run
*/
struct wps_config {
/**
* authenticator - Whether the local end is Authenticator
* 1 = Authenticator, 0 = Supplicant
*/
int authenticator;
/**
* wps - Pointer to long term WPS context
*/
struct wps_context *wps;
struct wps_registrar *registrar; /* NULL for Enrollee */
const u8 *pin; /* Enrollee Device Password (NULL for Registrar or PBC)
*/
/**
* registrar - Pointer to WPS registrar data from wps_registrar_init()
* This is only used if the local end is Registrar; set to %NULL for
* Enrollee.
*/
struct wps_registrar *registrar;
/**
* pin - Enrollee Device Password (%NULL for Registrar or PBC)
*/
const u8 *pin;
/**
* pin_len - Length on pin in octets
*/
size_t pin_len;
/**
* pbc - Whether this is protocol run uses PBC
*/
int pbc;
const struct wpabuf *assoc_wps_ie; /* (Re)AssocReq WPS IE (in AP) */
/**
* assoc_wps_ie: (Re)AssocReq WPS IE (in AP; %NULL if not AP)
*/
const struct wpabuf *assoc_wps_ie;
};
struct wps_data * wps_init(const struct wps_config *cfg);
void wps_deinit(struct wps_data *data);
/**
* enum wps_process_res - WPS message processing result
*/
enum wps_process_res {
WPS_DONE, WPS_CONTINUE, WPS_FAILURE, WPS_PENDING
/**
* WPS_DONE - Processing done
*/
WPS_DONE,
/**
* WPS_CONTINUE - Processing continues
*/
WPS_CONTINUE,
/**
* WPS_FAILURE - Processing failed
*/
WPS_FAILURE,
/**
* WPS_PENDING - Processing pending
*/
WPS_PENDING
};
enum wps_process_res wps_process_msg(struct wps_data *wps, u8 op_code,
enum wps_process_res wps_process_msg(struct wps_data *wps,
enum wsc_op_code op_code,
const struct wpabuf *msg);
struct wpabuf * wps_get_msg(struct wps_data *wps, u8 *op_code);
struct wpabuf * wps_get_msg(struct wps_data *wps, enum wsc_op_code *op_code);
int wps_is_selected_pbc_registrar(const struct wpabuf *msg);
int wps_is_selected_pin_registrar(const struct wpabuf *msg);
const u8 * wps_get_uuid_e(const struct wpabuf *msg);
struct wpabuf * wps_build_assoc_req_ie(u8 req_type);
struct wpabuf * wps_build_assoc_req_ie(enum wps_request_type req_type);
struct wpabuf * wps_build_probe_req_ie(int pbc, struct wps_device_data *dev,
const u8 *uuid, u8 req_type);
const u8 *uuid,
enum wps_request_type req_type);
/**
* struct wps_registrar_config - WPS Registrar configuration
*/
struct wps_registrar_config {
/**
* new_psk_cb - Callback for new PSK
* @ctx: Higher layer context data (cb_ctx)
* @mac_addr: MAC address of the Enrollee
* @psk: The new PSK
* @psk_len: The length of psk in octets
* Returns: 0 on success, -1 on failure
*
* This callback is called when a new per-device PSK is provisioned.
*/
int (*new_psk_cb)(void *ctx, const u8 *mac_addr, const u8 *psk,
size_t psk_len);
/**
* set_ie_cb - Callback for WPS IE changes
* @ctx: Higher layer context data (cb_ctx)
* @beacon_ie: WPS IE for Beacon
* @beacon_ie_len: WPS IE length for Beacon
* @probe_resp_ie: WPS IE for Probe Response
* @probe_resp_ie_len: WPS IE length for Probe Response
* Returns: 0 on success, -1 on failure
*
* This callback is called whenever the WPS IE in Beacon or Probe
* Response frames needs to be changed (AP only).
*/
int (*set_ie_cb)(void *ctx, const u8 *beacon_ie, size_t beacon_ie_len,
const u8 *probe_resp_ie, size_t probe_resp_ie_len);
/**
* pin_needed_cb - Callback for requesting a PIN
* @ctx: Higher layer context data (cb_ctx)
* @uuid_e: UUID-E of the unknown Enrollee
* @dev: Device Data from the unknown Enrollee
*
* This callback is called whenever an unknown Enrollee requests to use
* PIN method and a matching PIN (Device Password) is not found in
* Registrar data.
*/
void (*pin_needed_cb)(void *ctx, const u8 *uuid_e,
const struct wps_device_data *dev);
/**
* cb_ctx: Higher layer context data for Registrar callbacks
*/
void *cb_ctx;
};
/**
* enum wps_event - WPS event types
*/
enum wps_event {
/**
* WPS_EV_M2D - M2D received (Registrar did not know us)
*/
WPS_EV_M2D,
/**
* WPS_EV_FAIL - Registration failed
*/
WPS_EV_FAIL,
/**
* WPS_EV_SUCCESS - Registration succeeded
*/
WPS_EV_SUCCESS
};
/**
* union wps_event_data - WPS event data
*/
union wps_event_data {
/**
* struct wps_event_m2d - M2D event data
*/
struct wps_event_m2d {
u16 config_methods;
const u8 *manufacturer;
@ -116,8 +263,13 @@ union wps_event_data {
u16 config_error;
u16 dev_password_id;
} m2d;
/**
* struct wps_event_fail - Registration failure information
* @msg: enum wps_msg_type
*/
struct wps_event_fail {
int msg; /* enum wps_msg_type */
int msg;
} fail;
};
@ -128,23 +280,101 @@ union wps_event_data {
* structures and it is maintained over multiple registration protocol runs.
*/
struct wps_context {
/**
* ap - Whether the local end is an access point
*/
int ap;
/**
* registrar - Pointer to WPS registrar data from wps_registrar_init()
*/
struct wps_registrar *registrar;
int wps_state;
/**
* wps_state - Current WPS state
*/
enum wps_state wps_state;
/**
* ap_setup_locked - Whether AP setup is locked (only used at AP)
*/
int ap_setup_locked;
/**
* uuid - Own UUID
*/
u8 uuid[16];
/**
* ssid - SSID
*
* This SSID is used by the Registrar to fill in information for
* Credentials. In addition, AP uses it when acting as an Enrollee to
* notify Registrar of the current configuration.
*/
u8 ssid[32];
/**
* ssid_len - Length of ssid in octets
*/
size_t ssid_len;
/**
* dev - Own WPS device data
*/
struct wps_device_data dev;
u16 config_methods; /* bit field of WPS_CONFIG_* */
u16 encr_types; /* bit field of WPS_ENCR_* */
u16 auth_types; /* bit field of WPS_AUTH_* */
u8 *network_key; /* or NULL to generate per-device PSK */
/**
* config_methods - Enabled configuration methods
*
* Bit field of WPS_CONFIG_*
*/
u16 config_methods;
/**
* encr_types - Enabled encryption types (bit field of WPS_ENCR_*)
*/
u16 encr_types;
/**
* auth_types - Authentication types (bit field of WPS_AUTH_*)
*/
u16 auth_types;
/**
* network_key - The current Network Key (PSK) or %NULL to generate new
*
* If %NULL, Registrar will generate per-device PSK. In addition, AP
* uses this when acting as an Enrollee to notify Registrar of the
* current configuration.
*/
u8 *network_key;
/**
* network_key_len - Length of network_key in octets
*/
size_t network_key_len;
/**
* cred_cb - Callback to notify that new Credentials were received
* @ctx: Higher layer context data (cb_ctx)
* @cred: The received Credential
* Return: 0 on success, -1 on failure
*/
int (*cred_cb)(void *ctx, const struct wps_credential *cred);
/**
* event_cb - Event callback (state information about progress)
* @ctx: Higher layer context data (cb_ctx)
* @event: Event type
* @data: Event data
*/
void (*event_cb)(void *ctx, enum wps_event event,
union wps_event_data *data);
/**
* cb_ctx: Higher layer context data for callbacks
*/
void *cb_ctx;
};

View File

@ -381,7 +381,8 @@ static struct wpabuf * wps_build_wsc_nack(struct wps_data *wps)
}
struct wpabuf * wps_enrollee_get_msg(struct wps_data *wps, u8 *op_code)
struct wpabuf * wps_enrollee_get_msg(struct wps_data *wps,
enum wsc_op_code *op_code)
{
struct wpabuf *msg;
@ -1113,7 +1114,8 @@ static enum wps_process_res wps_process_wsc_nack(struct wps_data *wps,
}
enum wps_process_res wps_enrollee_process_msg(struct wps_data *wps, u8 op_code,
enum wps_process_res wps_enrollee_process_msg(struct wps_data *wps,
enum wsc_op_code op_code,
const struct wpabuf *msg)
{

View File

@ -16,7 +16,6 @@
#define WPS_I_H
#include "wps.h"
#include "wps_defs.h"
/**
* struct wps_data - WPS registration protocol data
@ -25,9 +24,23 @@
* single registration protocol run.
*/
struct wps_data {
/**
* authenticator - Whether the local end is Authenticator
* 1 = Authenticator, 0 = Supplicant
*/
int authenticator;
/**
* wps - Pointer to long term WPS context
*/
struct wps_context *wps;
/**
* registrar - Pointer to WPS registrar data from wps_registrar_init()
* This is only used if the local end is Registrar.
*/
struct wps_registrar *registrar;
enum {
/* Enrollee states */
SEND_M1, RECV_M2, SEND_M3, RECV_M4, SEND_M5, RECV_M6, SEND_M7,
@ -67,10 +80,21 @@ struct wps_data {
size_t dev_password_len;
u16 dev_pw_id;
int pbc;
u8 request_type; /* Request Type attribute from (Re)AssocReq */
u16 encr_type; /* available encryption types */
u16 auth_type; /* available authentication types */
/**
* request_type - Request Type attribute from (Re)AssocReq
*/
u8 request_type;
/**
* encr_type - Available encryption types
*/
u16 encr_type;
/**
* auth_type - Available authentication types
*/
u16 auth_type;
u8 *new_psk;
size_t new_psk_len;
@ -80,7 +104,10 @@ struct wps_data {
struct wps_device_data peer_dev;
u16 config_error; /* Configuration Error value to be used in NACK. */
/**
* config_error - Configuration Error value to be used in NACK
*/
u16 config_error;
};
@ -202,14 +229,17 @@ int wps_process_ap_settings(struct wps_parse_attr *attr,
struct wps_credential *cred);
/* wps_enrollee.c */
struct wpabuf * wps_enrollee_get_msg(struct wps_data *wps, u8 *op_code);
enum wps_process_res wps_enrollee_process_msg(struct wps_data *wps, u8 op_code,
struct wpabuf * wps_enrollee_get_msg(struct wps_data *wps,
enum wsc_op_code *op_code);
enum wps_process_res wps_enrollee_process_msg(struct wps_data *wps,
enum wsc_op_code op_code,
const struct wpabuf *msg);
/* wps_registrar.c */
struct wpabuf * wps_registrar_get_msg(struct wps_data *wps, u8 *op_code);
struct wpabuf * wps_registrar_get_msg(struct wps_data *wps,
enum wsc_op_code *op_code);
enum wps_process_res wps_registrar_process_msg(struct wps_data *wps,
u8 op_code,
enum wsc_op_code op_code,
const struct wpabuf *msg);
#endif /* WPS_I_H */

View File

@ -298,6 +298,18 @@ static int wps_build_resp_type(struct wps_registrar *reg, struct wpabuf *msg)
}
/**
* wps_registrar_init - Initialize WPS Registrar data
* @wps: Pointer to longterm WPS context
* @cfg: Registrar configuration
* Returns: Pointer to allocated Registrar data or %NULL on failure
*
* This function is used to initialize WPS Registrar functionality. It can be
* used for a single Registrar run (e.g., when run in a supplicant) or multiple
* runs (e.g., when run as an internal Registrar in an AP). Caller is
* responsible for freeing the returned data with wps_registrar_deinit() when
* Registrar functionality is not needed anymore.
*/
struct wps_registrar *
wps_registrar_init(struct wps_context *wps,
const struct wps_registrar_config *cfg)
@ -321,6 +333,10 @@ wps_registrar_init(struct wps_context *wps,
}
/**
* wps_registrar_deinit - Deinitialize WPS Registrar data
* @reg: Registrar data from wps_registrar_deinit()
*/
void wps_registrar_deinit(struct wps_registrar *reg)
{
if (reg == NULL)
@ -1202,7 +1218,8 @@ static struct wpabuf * wps_build_wsc_nack(struct wps_data *wps)
}
struct wpabuf * wps_registrar_get_msg(struct wps_data *wps, u8 *op_code)
struct wpabuf * wps_registrar_get_msg(struct wps_data *wps,
enum wsc_op_code *op_code)
{
struct wpabuf *msg;
@ -2083,7 +2100,7 @@ static enum wps_process_res wps_process_wsc_done(struct wps_data *wps,
enum wps_process_res wps_registrar_process_msg(struct wps_data *wps,
u8 op_code,
enum wsc_op_code op_code,
const struct wpabuf *msg)
{
enum wps_process_res ret;

View File

@ -19,7 +19,6 @@
#include "config.h"
#include "wpa_supplicant_i.h"
#include "mlme.h"
#include "wps/wps.h"
#include "wps_supplicant.h"
@ -43,7 +42,8 @@ static void wpa_supplicant_gen_assoc_event(struct wpa_supplicant *wpa_s)
#ifdef CONFIG_WPS
static int wpas_wps_in_use(struct wpa_config *conf, u8 *req_type)
static int wpas_wps_in_use(struct wpa_config *conf,
enum wps_request_type *req_type)
{
struct wpa_ssid *ssid;
int wps = 0;
@ -75,7 +75,7 @@ static void wpa_supplicant_scan(void *eloop_ctx, void *timeout_ctx)
size_t extra_ie_len = 0;
int wps = 0;
#ifdef CONFIG_WPS
u8 req_type = 0;
enum wps_request_type req_type = WPS_REQ_ENROLLEE_INFO;
#endif /* CONFIG_WPS */
if (wpa_s->disconnected && !wpa_s->scan_req)

View File

@ -38,7 +38,6 @@
#include "ieee802_11_defs.h"
#include "blacklist.h"
#include "wpas_glue.h"
#include "wps/wps.h"
#include "wps_supplicant.h"
const char *wpa_supplicant_version =

View File

@ -24,8 +24,6 @@
#include "uuid.h"
#include "wpa_ctrl.h"
#include "eap_common/eap_wsc_common.h"
#include "wps/wps.h"
#include "wps/wps_defs.h"
#include "wps_supplicant.h"
@ -223,7 +221,7 @@ static void wpa_supplicant_wps_event(void *ctx, enum wps_event event,
}
u8 wpas_wps_get_req_type(struct wpa_ssid *ssid)
enum wps_request_type wpas_wps_get_req_type(struct wpa_ssid *ssid)
{
if (eap_is_wps_pbc_enrollee(&ssid->eap) ||
eap_is_wps_pin_enrollee(&ssid->eap))

View File

@ -17,10 +17,13 @@
#ifdef CONFIG_WPS
#include "wps/wps.h"
#include "wps/wps_defs.h"
int wpas_wps_init(struct wpa_supplicant *wpa_s);
void wpas_wps_deinit(struct wpa_supplicant *wpa_s);
int wpas_wps_eapol_cb(struct wpa_supplicant *wpa_s);
u8 wpas_wps_get_req_type(struct wpa_ssid *ssid);
enum wps_request_type wpas_wps_get_req_type(struct wpa_ssid *ssid);
int wpas_wps_start_pbc(struct wpa_supplicant *wpa_s, const u8 *bssid);
int wpas_wps_start_pin(struct wpa_supplicant *wpa_s, const u8 *bssid,
const char *pin);