EAPOL supplicant state machines. More...

#include "includes.h"
#include "common.h"
#include "state_machine.h"
#include "wpabuf.h"
#include "eloop.h"
#include "crypto/crypto.h"
#include "crypto/md5.h"
#include "common/eapol_common.h"
#include "eap_peer/eap.h"
#include "eap_peer/eap_proxy.h"
#include "eapol_supp_sm.h"

Data Structures
struct	eapol_sm
	Internal data for EAPOL state machines. More...

struct	eap_key_data

Macros
#define	STATE_MACHINE_DATA struct eapol_sm

#define	STATE_MACHINE_DEBUG_PREFIX "EAPOL"

#define	IEEE8021X_ENCR_KEY_LEN 32

#define	IEEE8021X_SIGN_KEY_LEN 32

Functions
	SM_STATE (SUPP_PAE, LOGOFF)

	SM_STATE (SUPP_PAE, DISCONNECTED)

	SM_STATE (SUPP_PAE, CONNECTING)

	SM_STATE (SUPP_PAE, AUTHENTICATING)

	SM_STATE (SUPP_PAE, HELD)

	SM_STATE (SUPP_PAE, AUTHENTICATED)

	SM_STATE (SUPP_PAE, RESTART)

	SM_STATE (SUPP_PAE, S_FORCE_AUTH)

	SM_STATE (SUPP_PAE, S_FORCE_UNAUTH)

	SM_STEP (SUPP_PAE)

	SM_STATE (KEY_RX, NO_KEY_RECEIVE)

	SM_STATE (KEY_RX, KEY_RECEIVE)

	SM_STEP (KEY_RX)

	SM_STATE (SUPP_BE, REQUEST)

	SM_STATE (SUPP_BE, RESPONSE)

	SM_STATE (SUPP_BE, SUCCESS)

	SM_STATE (SUPP_BE, FAIL)

	SM_STATE (SUPP_BE, TIMEOUT)

	SM_STATE (SUPP_BE, IDLE)

	SM_STATE (SUPP_BE, INITIALIZE)

	SM_STATE (SUPP_BE, RECEIVE)

	SM_STEP (SUPP_BE)

void	eapol_sm_step (struct eapol_sm *sm)
	EAPOL state machine step function. More...

void	eapol_sm_configure (struct eapol_sm *sm, int heldPeriod, int authPeriod, int startPeriod, int maxStart)
	Set EAPOL variables. More...

const char *	eapol_sm_get_method_name (struct eapol_sm *sm)
	Get EAPOL method name. More...

int	eapol_sm_get_status (struct eapol_sm sm, char buf, size_t buflen, int verbose)
	Get EAPOL state machine status. More...

int	eapol_sm_get_mib (struct eapol_sm sm, char buf, size_t buflen)
	Get EAPOL state machine MIBs. More...

int	eapol_sm_rx_eapol (struct eapol_sm sm, const u8 src, const u8 *buf, size_t len)
	Process received EAPOL frames. More...

void	eapol_sm_notify_tx_eapol_key (struct eapol_sm *sm)
	Notification about transmitted EAPOL packet. More...

void	eapol_sm_notify_portEnabled (struct eapol_sm *sm, Boolean enabled)
	Notification about portEnabled change. More...

void	eapol_sm_notify_portValid (struct eapol_sm *sm, Boolean valid)
	Notification about portValid change. More...

void	eapol_sm_notify_eap_success (struct eapol_sm *sm, Boolean success)
	Notification of external EAP success trigger. More...

void	eapol_sm_notify_eap_fail (struct eapol_sm *sm, Boolean fail)
	Notification of external EAP failure trigger. More...

void	eapol_sm_notify_config (struct eapol_sm sm, struct eap_peer_config config, const struct eapol_config *conf)
	Notification of EAPOL configuration change. More...

int	eapol_sm_get_key (struct eapol_sm sm, u8 key, size_t len)
	Get master session key (MSK) from EAP. More...

const u8 *	eapol_sm_get_session_id (struct eapol_sm sm, size_t len)
	Get EAP Session-Id. More...

void	eapol_sm_notify_logoff (struct eapol_sm *sm, Boolean logoff)
	Notification of logon/logoff commands. More...

void	eapol_sm_notify_cached (struct eapol_sm *sm)
	Notification of successful PMKSA caching. More...

void	eapol_sm_notify_pmkid_attempt (struct eapol_sm *sm)
	Notification of PMKSA caching. More...

void	eapol_sm_register_scard_ctx (struct eapol_sm sm, void ctx)
	Notification of smart card context. More...

void	eapol_sm_notify_portControl (struct eapol_sm *sm, PortControl portControl)
	Notification of portControl changes. More...

void	eapol_sm_notify_ctrl_attached (struct eapol_sm *sm)
	Notification of attached monitor. More...

void	eapol_sm_notify_ctrl_response (struct eapol_sm *sm)
	Notification of received user input. More...

void	eapol_sm_request_reauth (struct eapol_sm *sm)
	Request reauthentication. More...

void	eapol_sm_notify_lower_layer_success (struct eapol_sm *sm, int in_eapol_sm)
	Notification of lower layer success. More...

void	eapol_sm_invalidate_cached_session (struct eapol_sm *sm)
	Mark cached EAP session data invalid. More...

struct eapol_sm *	eapol_sm_init (struct eapol_ctx *ctx)
	Initialize EAPOL state machine. More...

void	eapol_sm_deinit (struct eapol_sm *sm)
	Deinitialize EAPOL state machine. More...

void	eapol_sm_set_ext_pw_ctx (struct eapol_sm sm, struct ext_password_data ext)

int	eapol_sm_failed (struct eapol_sm *sm)

int	eapol_sm_get_eap_proxy_imsi (struct eapol_sm sm, char imsi, size_t *len)

void	eapol_sm_erp_flush (struct eapol_sm *sm)

Detailed Description

EAPOL supplicant state machines.

Function Documentation

void eapol_sm_configure	(	struct eapol_sm *	sm,
		int	heldPeriod,
		int	authPeriod,
		int	startPeriod,
		int	maxStart
	)

Set EAPOL variables.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
heldPeriod	dot1xSuppHeldPeriod
authPeriod	dot1xSuppAuthPeriod
startPeriod	dot1xSuppStartPeriod
maxStart	dot1xSuppMaxStart

Set configurable EAPOL state machine variables. Each variable can be set to the given value or ignored if set to -1 (to set only some of the variables).

void eapol_sm_deinit ( struct eapol_sm * sm )

Deinitialize EAPOL state machine.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Deinitialize and free EAPOL state machine.

int eapol_sm_get_key	(	struct eapol_sm *	sm,
		u8 *	key,
		size_t	len
	)

Get master session key (MSK) from EAP.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
key	Pointer for key buffer
len	Number of bytes to copy to key

Returns: 0 on success (len of key available), maximum available key len (>0) if key is available but it is shorter than len, or -1 on failure.

Fetch EAP keying material (MSK, eapKeyData) from EAP state machine. The key is available only after a successful authentication.

const char* eapol_sm_get_method_name ( struct eapol_sm * sm )

Get EAPOL method name.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Returns: Static string containing name of current eap method or NULL

int eapol_sm_get_mib	(	struct eapol_sm *	sm,
		char *	buf,
		size_t	buflen
	)

Get EAPOL state machine MIBs.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
buf	Buffer for MIB information
buflen	Maximum buffer length

Returns: Number of bytes written to buf.

Query EAPOL state machine for MIB information. This function fills in a text area with current MIB information from the EAPOL state machine. If the buffer (buf) is not large enough, MIB information will be truncated to fit the buffer.

const u8* eapol_sm_get_session_id	(	struct eapol_sm *	sm,
		size_t *	len
	)

Get EAP Session-Id.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
len	Pointer to variable that will be set to number of bytes in the session

Returns: Pointer to the EAP Session-Id or NULL on failure

The Session-Id is available only after a successful authentication.

int eapol_sm_get_status	(	struct eapol_sm *	sm,
		char *	buf,
		size_t	buflen,
		int	verbose
	)

Get EAPOL state machine status.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
buf	Buffer for status information
buflen	Maximum buffer length
verbose	Whether to include verbose status information

Returns: Number of bytes written to buf.

Query EAPOL state machine for status information. This function fills in a text area with current status information from the EAPOL state machine. If the buffer (buf) is not large enough, status information will be truncated to fit the buffer.

struct eapol_sm* eapol_sm_init ( struct eapol_ctx * ctx )

Initialize EAPOL state machine.

Parameters

ctx	Pointer to EAPOL context data; this needs to be an allocated buffer and EAPOL state machine will free it in eapol_sm_deinit()

Returns: Pointer to the allocated EAPOL state machine or NULL on failure

Allocate and initialize an EAPOL state machine.

void eapol_sm_invalidate_cached_session ( struct eapol_sm * sm )

Mark cached EAP session data invalid.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

void eapol_sm_notify_cached ( struct eapol_sm * sm )

Notification of successful PMKSA caching.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Notify EAPOL state machines that PMKSA caching was successful. This is used to move EAPOL and EAP state machines into authenticated/successful state.

void eapol_sm_notify_config	(	struct eapol_sm *	sm,
		struct eap_peer_config *	config,
		const struct eapol_config *	conf
	)

Notification of EAPOL configuration change.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
config	Pointer to current network EAP configuration
conf	Pointer to EAPOL configuration data

Notify EAPOL state machine that configuration has changed. config will be stored as a backpointer to network configuration. This can be NULL to clear the stored pointed. conf will be copied to local EAPOL/EAP configuration data. If conf is NULL, this part of the configuration change will be skipped.

void eapol_sm_notify_ctrl_attached ( struct eapol_sm * sm )

Notification of attached monitor.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Notify EAPOL state machines that a monitor was attached to the control interface to trigger re-sending of pending requests for user input.

void eapol_sm_notify_ctrl_response ( struct eapol_sm * sm )

Notification of received user input.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Notify EAPOL state machines that a control response, i.e., user input, was received in order to trigger retrying of a pending EAP request.

void eapol_sm_notify_eap_fail	(	struct eapol_sm *	sm,
		Boolean	fail
	)

Notification of external EAP failure trigger.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
fail	TRUE = set failure, FALSE = clear failure

Notify EAPOL state machine that external event has forced EAP state to failure (fail = TRUE). This can be cleared by setting fail = FALSE.

void eapol_sm_notify_eap_success	(	struct eapol_sm *	sm,
		Boolean	success
	)

Notification of external EAP success trigger.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
success	TRUE = set success, FALSE = clear success

Notify the EAPOL state machine that external event has forced EAP state to success (success = TRUE). This can be cleared by setting success = FALSE.

This function is called to update EAP state when WPA-PSK key handshake has been completed successfully since WPA-PSK does not use EAP state machine.

void eapol_sm_notify_logoff	(	struct eapol_sm *	sm,
		Boolean	logoff
	)

Notification of logon/logoff commands.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
logoff	Whether command was logoff

Notify EAPOL state machines that user requested logon/logoff.

void eapol_sm_notify_lower_layer_success	(	struct eapol_sm *	sm,
		int	in_eapol_sm
	)

Notification of lower layer success.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
in_eapol_sm	Whether the caller is already running inside EAPOL state machine loop (eapol_sm_step())

Notify EAPOL (and EAP) state machines that a lower layer has detected a successful authentication. This is used to recover from dropped EAP-Success messages.

void eapol_sm_notify_pmkid_attempt ( struct eapol_sm * sm )

Notification of PMKSA caching.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Notify EAPOL state machines if PMKSA caching is used.

void eapol_sm_notify_portControl	(	struct eapol_sm *	sm,
		PortControl	portControl
	)

Notification of portControl changes.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
portControl	New value for portControl variable

Notify EAPOL state machines that portControl variable has changed.

void eapol_sm_notify_portEnabled	(	struct eapol_sm *	sm,
		Boolean	enabled
	)

Notification about portEnabled change.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
enabled	New portEnabled value

Notify EAPOL state machine about new portEnabled value.

void eapol_sm_notify_portValid	(	struct eapol_sm *	sm,
		Boolean	valid
	)

Notification about portValid change.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
valid	New portValid value

Notify EAPOL state machine about new portValid value.

void eapol_sm_notify_tx_eapol_key ( struct eapol_sm * sm )

Notification about transmitted EAPOL packet.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

Notify EAPOL state machine about transmitted EAPOL packet from an external component, e.g., WPA. This will update the statistics.

void eapol_sm_register_scard_ctx	(	struct eapol_sm *	sm,
		void *	ctx
	)

Notification of smart card context.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
ctx	Context data for smart card operations

Notify EAPOL state machines of context data for smart card operations. This context data will be used as a parameter for scard_*() functions.

void eapol_sm_request_reauth ( struct eapol_sm * sm )

Request reauthentication.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

This function can be used to request EAPOL reauthentication, e.g., when the current PMKSA entry is nearing expiration.

int eapol_sm_rx_eapol	(	struct eapol_sm *	sm,
		const u8 *	src,
		const u8 *	buf,
		size_t	len
	)

Process received EAPOL frames.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()
src	Source MAC address of the EAPOL packet
buf	Pointer to the beginning of the EAPOL data (EAPOL header)
len	Length of the EAPOL frame

Returns: 1 = EAPOL frame processed, 0 = not for EAPOL state machine, -1 failure

void eapol_sm_step ( struct eapol_sm * sm )

EAPOL state machine step function.

Parameters

sm	Pointer to EAPOL state machine allocated with eapol_sm_init()

This function is called to notify the state machine about changed external variables. It will step through the EAPOL state machines in loop to process all triggered state changes.

Data Structures

Macros

Functions

Detailed Description

Function Documentation