wps.h File Reference

Wi-Fi Protected Setup. More...

#include "wps_defs.h"

Go to the source code of this file.

Data Structures
struct	wps_credential
	WPS Credential. More...
struct	wps_device_data
	WPS Device Data. More...
struct	oob_conf_data
struct	wps_config
	WPS configuration for a single registration protocol run. More...
struct	wps_registrar_config
	WPS Registrar configuration. More...
union	wps_event_data
struct	wps_event_data::wps_event_m2d
	M2D event data. More...
struct	wps_event_data::wps_event_fail
	Registration failure information. More...
struct	wps_event_data::wps_event_pwd_auth_fail
struct	wps_event_data::wps_event_er_ap
struct	wps_event_data::wps_event_er_enrollee
struct	wps_event_data::wps_event_er_ap_settings
struct	wps_event_data::wps_event_er_set_selected_registrar
struct	upnp_pending_message
	Pending PutWLANResponse messages. More...
struct	wps_context
	Long term WPS context data. More...
struct	oob_device_data
struct	oob_nfc_device_data
Defines
#define	WPS_DEV_TYPE_LEN   8
#define	WPS_DEV_TYPE_BUFSIZE   21
#define	WPS_SEC_DEV_TYPE_MAX_LEN   128
#define	MAX_WPS_VENDOR_EXTENSIONS   10
#define	WPS_MAX_VENDOR_EXT_LEN   1024
#define	MAX_WPS_PARSE_VENDOR_EXT   10
#define	WPS_SEC_DEVICE_TYPES   5
Enumerations
enum	wsc_op_code {   WSC_UPnP = 0, WSC_Start = 0x01, WSC_ACK = 0x02, WSC_NACK = 0x03,   WSC_MSG = 0x04, WSC_Done = 0x05, WSC_FRAG_ACK = 0x06 }
enum	wps_process_res { WPS_DONE, WPS_CONTINUE, WPS_FAILURE, WPS_PENDING }
enum	wps_event {   WPS_EV_M2D, WPS_EV_FAIL, WPS_EV_SUCCESS, WPS_EV_PWD_AUTH_FAIL,   WPS_EV_PBC_OVERLAP, WPS_EV_PBC_TIMEOUT, WPS_EV_ER_AP_ADD, WPS_EV_ER_AP_REMOVE,   WPS_EV_ER_ENROLLEE_ADD, WPS_EV_ER_ENROLLEE_REMOVE, WPS_EV_ER_AP_SETTINGS, WPS_EV_ER_SET_SELECTED_REGISTRAR,   WPS_EV_AP_PIN_SUCCESS }
Functions
struct wps_data *	wps_init (const struct wps_config *cfg)
	Initialize WPS Registration protocol data.
void	wps_deinit (struct wps_data *data)
	Deinitialize WPS Registration protocol data.
enum wps_process_res	wps_process_msg (struct wps_data *wps, enum wsc_op_code op_code, const struct wpabuf *msg)
	Process a WPS message.
struct wpabuf *	wps_get_msg (struct wps_data *wps, enum wsc_op_code *op_code)
	Build a WPS message.
int	wps_is_selected_pbc_registrar (const struct wpabuf *msg)
	Check whether WPS IE indicates active PBC.
int	wps_is_selected_pin_registrar (const struct wpabuf *msg)
	Check whether WPS IE indicates active PIN.
int	wps_ap_priority_compar (const struct wpabuf *wps_a, const struct wpabuf *wps_b)
	Prioritize WPS IE from two APs.
int	wps_is_addr_authorized (const struct wpabuf *msg, const u8 *addr, int ver1_compat)
	Check whether WPS IE authorizes MAC address.
const u8 *	wps_get_uuid_e (const struct wpabuf *msg)
	Get UUID-E from WPS IE.
int	wps_is_20 (const struct wpabuf *msg)
	Check whether WPS attributes claim support for WPS 2.0.
struct wpabuf *	wps_build_assoc_req_ie (enum wps_request_type req_type)
	Build WPS IE for (Re)Association Request.
struct wpabuf *	wps_build_assoc_resp_ie (void)
	Build WPS IE for (Re)Association Response.
struct wpabuf *	wps_build_probe_req_ie (u16 pw_id, struct wps_device_data *dev, const u8 *uuid, enum wps_request_type req_type, unsigned int num_req_dev_types, const u8 *req_dev_types)
	Build WPS IE for Probe Request.
struct wps_registrar *	wps_registrar_init (struct wps_context *wps, const struct wps_registrar_config *cfg)
	Initialize WPS Registrar data.
void	wps_registrar_deinit (struct wps_registrar *reg)
	Deinitialize WPS Registrar data.
int	wps_registrar_add_pin (struct wps_registrar *reg, const u8 *addr, const u8 *uuid, const u8 *pin, size_t pin_len, int timeout)
	Configure a new PIN for Registrar.
int	wps_registrar_invalidate_pin (struct wps_registrar *reg, const u8 *uuid)
	Invalidate a PIN for a specific UUID-E.
int	wps_registrar_wps_cancel (struct wps_registrar *reg)
int	wps_registrar_unlock_pin (struct wps_registrar *reg, const u8 *uuid)
	Unlock a PIN for a specific UUID-E.
int	wps_registrar_button_pushed (struct wps_registrar *reg, const u8 *p2p_dev_addr)
	Notify Registrar that AP button was pushed.
void	wps_registrar_complete (struct wps_registrar *registrar, const u8 *uuid_e, const u8 *dev_pw, size_t dev_pw_len)
void	wps_registrar_probe_req_rx (struct wps_registrar *reg, const u8 *addr, const struct wpabuf *wps_data, int p2p_wildcard)
	Notify Registrar of Probe Request.
int	wps_registrar_update_ie (struct wps_registrar *reg)
int	wps_registrar_get_info (struct wps_registrar *reg, const u8 *addr, char *buf, size_t buflen)
int	wps_registrar_config_ap (struct wps_registrar *reg, struct wps_credential *cred)
int	wps_build_credential_wrap (struct wpabuf *msg, const struct wps_credential *cred)
unsigned int	wps_pin_checksum (unsigned int pin)
	Compute PIN checksum.
unsigned int	wps_pin_valid (unsigned int pin)
	Check whether a PIN has a valid checksum.
unsigned int	wps_generate_pin (void)
	Generate a random PIN.
void	wps_free_pending_msgs (struct upnp_pending_message *msgs)
struct oob_device_data *	wps_get_oob_device (char *device_type)
struct oob_nfc_device_data *	wps_get_oob_nfc_device (char *device_name)
int	wps_get_oob_method (char *method)
int	wps_process_oob (struct wps_context *wps, struct oob_device_data *oob_dev, int registrar)
int	wps_attr_text (struct wpabuf *data, char *buf, char *end)
struct wps_er *	wps_er_init (struct wps_context *wps, const char *ifname, const char *filter)
void	wps_er_refresh (struct wps_er *er)
void	wps_er_deinit (struct wps_er *er, void(*cb)(void *ctx), void *ctx)
void	wps_er_set_sel_reg (struct wps_er *er, int sel_reg, u16 dev_passwd_id, u16 sel_reg_config_methods)
int	wps_er_pbc (struct wps_er *er, const u8 *uuid)
int	wps_er_learn (struct wps_er *er, const u8 *uuid, const u8 *pin, size_t pin_len)
int	wps_er_set_config (struct wps_er *er, const u8 *uuid, const struct wps_credential *cred)
int	wps_er_config (struct wps_er *er, const u8 *uuid, const u8 *pin, size_t pin_len, const struct wps_credential *cred)
int	wps_dev_type_str2bin (const char *str, u8 dev_type[WPS_DEV_TYPE_LEN])
char *	wps_dev_type_bin2str (const u8 dev_type[WPS_DEV_TYPE_LEN], char *buf, size_t buf_len)
void	uuid_gen_mac_addr (const u8 *mac_addr, u8 *uuid)
u16	wps_config_methods_str2bin (const char *str)

---

Detailed Description

Wi-Fi Protected Setup.

Copyright

Copyright (c) 2007-2009, Jouni Malinen <j@w1.fi>

This software may be distributed under the terms of the BSD license. See README for more details.

---

Enumeration Type Documentation

enum wps_event

enum wps_event - WPS event types

Enumerator:

WPS_EV_M2D	M2D received (Registrar did not know us)
WPS_EV_FAIL	Registration failed.
WPS_EV_SUCCESS	Registration succeeded.
WPS_EV_PWD_AUTH_FAIL	Password authentication failed.
WPS_EV_PBC_OVERLAP	PBC session overlap detected.
WPS_EV_PBC_TIMEOUT	PBC walktime expired before protocol run start.
WPS_EV_ER_AP_ADD	ER: AP added.
WPS_EV_ER_AP_REMOVE	ER: AP removed.
WPS_EV_ER_ENROLLEE_ADD	ER: Enrollee added.
WPS_EV_ER_ENROLLEE_REMOVE	ER: Enrollee removed.
WPS_EV_ER_AP_SETTINGS	ER: AP Settings learned.
WPS_EV_ER_SET_SELECTED_REGISTRAR	ER: SetSelectedRegistrar event.
WPS_EV_AP_PIN_SUCCESS	External Registrar used correct AP PIN.

enum wps_process_res

enum wps_process_res - WPS message processing result

Enumerator:

WPS_DONE	Processing done.
WPS_CONTINUE	Processing continues.
WPS_FAILURE	Processing failed.
WPS_PENDING	Processing continues, but waiting for an external. event (e.g., UPnP message from an external Registrar)

enum wsc_op_code

enum wsc_op_code - EAP-WSC OP-Code values

---

Function Documentation

int wps_ap_priority_compar	(	const struct wpabuf *	wps_a,
		const struct wpabuf *	wps_b
	)

Prioritize WPS IE from two APs.

Parameters:

wps_a	WPS IE contents from Beacon or Probe Response frame
wps_b	WPS IE contents from Beacon or Probe Response frame

Returns:

1 if wps_b is considered more likely selection for WPS provisioning, -1 if wps_a is considered more like, or 0 if no preference

struct wpabuf* wps_build_assoc_req_ie

(

enum wps_request_type

req_type

)

[read]

Build WPS IE for (Re)Association Request.

Parameters:

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_resp_ie

(

void

)

[read]

Build WPS IE for (Re)Association Response.

Returns:

WPS IE or NULL on failure

The caller is responsible for freeing the buffer.

struct wpabuf* wps_build_probe_req_ie	(	u16	pw_id,
		struct wps_device_data *	dev,
		const u8 *	uuid,
		enum wps_request_type	req_type,
		unsigned int	num_req_dev_types,
		const u8 *	req_dev_types
	)		[read]

Build WPS IE for Probe Request.

Parameters:

pw_id	Password ID (DEV_PW_PUSHBUTTON for active PBC and DEV_PW_DEFAULT for most other use cases)
dev	Device attributes
uuid	Own UUID
req_type	Value for Request Type attribute
num_req_dev_types	Number of requested device types
req_dev_types	Requested device types (8 * num_req_dev_types octets) or NULL if none

Returns:

WPS IE or NULL on failure

The caller is responsible for freeing the buffer.

void wps_deinit

(

struct wps_data *

data

)

Deinitialize WPS Registration protocol data.

Parameters:

data	WPS Registration protocol data from wps_init()

unsigned int wps_generate_pin

(

void

)

Generate a random PIN.

Returns:

Eight digit PIN (i.e., including the checksum digit)

struct wpabuf* wps_get_msg	(	struct wps_data *	wps,
		enum wsc_op_code *	op_code
	)		[read]

Build a WPS message.

Parameters:

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.

const u8* wps_get_uuid_e

(

const struct wpabuf *

msg

)

Get UUID-E from WPS IE.

Parameters:

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.

struct wps_data* wps_init

(

const struct wps_config *

cfg

)

[read]

Initialize WPS Registration protocol data.

Parameters:

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().

int wps_is_addr_authorized	(	const struct wpabuf *	msg,
		const u8 *	addr,
		int	ver1_compat
	)

Check whether WPS IE authorizes MAC address.

Parameters:

msg	WPS IE contents from Beacon or Probe Response frame
addr	MAC address to search for
ver1_compat	Whether to use version 1 compatibility mode

Returns:

1 if address is authorized, 0 if not

int wps_is_selected_pbc_registrar

(

const struct wpabuf *

msg

)

Check whether WPS IE indicates active PBC.

Parameters:

msg	WPS IE contents from Beacon or Probe Response frame

Returns:

1 if PBC Registrar is active, 0 if not

int wps_is_selected_pin_registrar

(

const struct wpabuf *

msg

)

Check whether WPS IE indicates active PIN.

Parameters:

msg	WPS IE contents from Beacon or Probe Response frame

Returns:

1 if PIN Registrar is active, 0 if not

unsigned int wps_pin_checksum

(

unsigned int

pin

)

Compute PIN checksum.

Parameters:

pin	Seven digit PIN (i.e., eight digit PIN without the checksum digit)

Returns:

Checksum digit

unsigned int wps_pin_valid

(

unsigned int

pin

)

Check whether a PIN has a valid checksum.

Parameters:

pin	Eight digit PIN (i.e., including the checksum digit)

Returns:

1 if checksum digit is valid, or 0 if not

enum wps_process_res wps_process_msg	(	struct wps_data *	wps,
		enum wsc_op_code	op_code,
		const struct wpabuf *	msg
	)

Process a WPS message.

Parameters:

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().

int wps_registrar_add_pin	(	struct wps_registrar *	reg,
		const u8 *	addr,
		const u8 *	uuid,
		const u8 *	pin,
		size_t	pin_len,
		int	timeout
	)

Configure a new PIN for Registrar.

Parameters:

reg	Registrar data from wps_registrar_init()
addr	Enrollee MAC address or NULL if not known
uuid	UUID-E or NULL for wildcard (any UUID)
pin	PIN (Device Password)
pin_len	Length of pin in octets
timeout	Time (in seconds) when the PIN will be invalidated; 0 = no timeout

Returns:

0 on success, -1 on failure

int wps_registrar_button_pushed	(	struct wps_registrar *	reg,
		const u8 *	p2p_dev_addr
	)

Notify Registrar that AP button was pushed.

Parameters:

reg	Registrar data from wps_registrar_init()
p2p_dev_addr	Limit allowed PBC devices to the specified P2P device, NULL indicates no such filtering

Returns:

0 on success, -1 on failure, -2 on session overlap

This function is called on an AP when a push button is pushed to activate PBC mode. The PBC mode will be stopped after walk time (2 minutes) timeout or when a PBC registration is completed. If more than one Enrollee in active PBC mode has been detected during the monitor time (previous 2 minutes), the PBC mode is not activated and -2 is returned to indicate session overlap. This is skipped if a specific Enrollee is selected.

void wps_registrar_deinit

(

struct wps_registrar *

reg

)

Deinitialize WPS Registrar data.

Parameters:

reg	Registrar data from wps_registrar_init()

struct wps_registrar* wps_registrar_init	(	struct wps_context *	wps,
		const struct wps_registrar_config *	cfg
	)		[read]

Initialize WPS Registrar data.

Parameters:

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.

int wps_registrar_invalidate_pin	(	struct wps_registrar *	reg,
		const u8 *	uuid
	)

Invalidate a PIN for a specific UUID-E.

Parameters:

reg	Registrar data from wps_registrar_init()
uuid	UUID-E

Returns:

0 on success, -1 on failure (e.g., PIN not found)

void wps_registrar_probe_req_rx	(	struct wps_registrar *	reg,
		const u8 *	addr,
		const struct wpabuf *	wps_data,
		int	p2p_wildcard
	)

Notify Registrar of Probe Request.

Parameters:

reg	Registrar data from wps_registrar_init()
addr	MAC address of the Probe Request sender
wps_data	WPS IE contents

This function is called on an AP when a Probe Request with WPS IE is received. This is used to track PBC mode use and to detect possible overlap situation with other WPS APs.

int wps_registrar_unlock_pin	(	struct wps_registrar *	reg,
		const u8 *	uuid
	)

Unlock a PIN for a specific UUID-E.

Parameters:

reg	Registrar data from wps_registrar_init()
uuid	UUID-E

Returns:

0 on success, -1 on failure

PINs are locked to enforce only one concurrent use. This function unlocks a PIN to allow it to be used again. If the specified PIN was configured using a wildcard UUID, it will be removed instead of allowing multiple uses.