EAP peer state machines (RFC 4137) More...

#include "includes.h"
#include "common.h"
#include "pcsc_funcs.h"
#include "state_machine.h"
#include "ext_password.h"
#include "crypto/crypto.h"
#include "crypto/tls.h"
#include "crypto/sha256.h"
#include "common/wpa_ctrl.h"
#include "eap_common/eap_wsc_common.h"
#include "eap_i.h"
#include "eap_config.h"

Macros
#define	STATE_MACHINE_DATA struct eap_sm

#define	STATE_MACHINE_DEBUG_PREFIX "EAP"

#define	EAP_MAX_AUTH_ROUNDS 50

#define	EAP_CLIENT_TIMEOUT_DEFAULT 60

Functions
int	eap_allowed_method (struct eap_sm *sm, int vendor, u32 method)
	Check whether EAP method is allowed. More...

	SM_STATE (EAP, INITIALIZE)

	SM_STATE (EAP, DISABLED)

	SM_STATE (EAP, IDLE)

	SM_STATE (EAP, RECEIVED)

	SM_STATE (EAP, GET_METHOD)

void	eap_peer_erp_free_keys (struct eap_sm *sm)

	SM_STATE (EAP, METHOD)

	SM_STATE (EAP, SEND_RESPONSE)

	SM_STATE (EAP, DISCARD)

	SM_STATE (EAP, IDENTITY)

	SM_STATE (EAP, NOTIFICATION)

	SM_STATE (EAP, RETRANSMIT)

	SM_STATE (EAP, SUCCESS)

	SM_STATE (EAP, FAILURE)

	SM_STEP (EAP)

struct wpabuf *	eap_sm_buildIdentity (struct eap_sm *sm, int id, int encrypted)
	Build EAP-Identity/Response for the current network. More...

struct eap_sm *	eap_peer_sm_init (void eapol_ctx, const struct eapol_callbacks eapol_cb, void msg_ctx, struct eap_config conf)
	Allocate and initialize EAP peer state machine. More...

void	eap_peer_sm_deinit (struct eap_sm *sm)
	Deinitialize and free an EAP peer state machine. More...

int	eap_peer_sm_step (struct eap_sm *sm)
	Step EAP peer state machine. More...

void	eap_sm_abort (struct eap_sm *sm)
	Abort EAP authentication. More...

int	eap_sm_get_status (struct eap_sm sm, char buf, size_t buflen, int verbose)
	Get EAP state machine status. More...

const char *	eap_sm_get_method_name (struct eap_sm *sm)

void	eap_sm_request_identity (struct eap_sm *sm)
	Request identity from user (ctrl_iface) More...

void	eap_sm_request_password (struct eap_sm *sm)
	Request password from user (ctrl_iface) More...

void	eap_sm_request_new_password (struct eap_sm *sm)
	Request new password from user (ctrl_iface) More...

void	eap_sm_request_pin (struct eap_sm *sm)
	Request SIM or smart card PIN from user (ctrl_iface) More...

void	eap_sm_request_otp (struct eap_sm sm, const char msg, size_t msg_len)
	Request one time password from user (ctrl_iface) More...

void	eap_sm_request_passphrase (struct eap_sm *sm)
	Request passphrase from user (ctrl_iface) More...

void	eap_sm_request_sim (struct eap_sm sm, const char req)
	Request external SIM processing. More...

void	eap_sm_notify_ctrl_attached (struct eap_sm *sm)
	Notification of attached monitor. More...

u32	eap_get_phase2_type (const char name, int vendor)
	Get EAP type for the given EAP phase 2 method name. More...

struct eap_method_type *	eap_get_phase2_types (struct eap_peer_config config, size_t count)
	Get list of allowed EAP phase 2 types. More...

void	eap_set_fast_reauth (struct eap_sm *sm, int enabled)
	Update fast_reauth setting. More...

void	eap_set_workaround (struct eap_sm *sm, unsigned int workaround)
	Update EAP workarounds setting. More...

struct eap_peer_config *	eap_get_config (struct eap_sm *sm)
	Get current network configuration. More...

const u8 *	eap_get_config_identity (struct eap_sm sm, size_t len)
	Get identity from the network configuration. More...

const u8 *	eap_get_config_password (struct eap_sm sm, size_t len)
	Get password from the network configuration. More...

const u8 *	eap_get_config_password2 (struct eap_sm sm, size_t len, int *hash)
	Get password from the network configuration. More...

const u8 *	eap_get_config_new_password (struct eap_sm sm, size_t len)
	Get new password from network configuration. More...

const u8 *	eap_get_config_otp (struct eap_sm sm, size_t len)
	Get one-time password from the network configuration. More...

void	eap_clear_config_otp (struct eap_sm *sm)
	Clear used one-time password. More...

const char *	eap_get_config_phase1 (struct eap_sm *sm)
	Get phase1 data from the network configuration. More...

const char *	eap_get_config_phase2 (struct eap_sm *sm)
	Get phase2 data from the network configuration. More...

int	eap_get_config_fragment_size (struct eap_sm *sm)

int	eap_key_available (struct eap_sm *sm)
	Get key availability (eapKeyAvailable variable) More...

void	eap_notify_success (struct eap_sm *sm)
	Notify EAP state machine about external success trigger. More...

void	eap_notify_lower_layer_success (struct eap_sm *sm)
	Notification of lower layer success. More...

const u8 *	eap_get_eapSessionId (struct eap_sm sm, size_t len)
	Get Session-Id from EAP state machine. More...

const u8 *	eap_get_eapKeyData (struct eap_sm sm, size_t len)
	Get master session key (MSK) from EAP state machine. More...

struct wpabuf *	eap_get_eapRespData (struct eap_sm *sm)
	Get EAP response data. More...

void	eap_register_scard_ctx (struct eap_sm sm, void ctx)
	Notification of smart card context. More...

void	eap_set_config_blob (struct eap_sm sm, struct wpa_config_blob blob)
	Set or add a named configuration blob. More...

const struct wpa_config_blob *	eap_get_config_blob (struct eap_sm sm, const char name)
	Get a named configuration blob. More...

void	eap_set_force_disabled (struct eap_sm *sm, int disabled)
	Set force_disabled flag. More...

void	eap_set_external_sim (struct eap_sm *sm, int external_sim)
	Set external_sim flag. More...

void	eap_notify_pending (struct eap_sm *sm)
	Notify that EAP method is ready to re-process a request. More...

void	eap_invalidate_cached_session (struct eap_sm *sm)
	Mark cached session data invalid. More...

int	eap_is_wps_pbc_enrollee (struct eap_peer_config *conf)

int	eap_is_wps_pin_enrollee (struct eap_peer_config *conf)

void	eap_sm_set_ext_pw_ctx (struct eap_sm sm, struct ext_password_data ext)

void	eap_set_anon_id (struct eap_sm sm, const u8 id, size_t len)
	Set or add anonymous identity. More...

int	eap_peer_was_failure_expected (struct eap_sm *sm)

Detailed Description

EAP peer state machines (RFC 4137)

This file implements the Peer State Machine as defined in RFC 4137. The used states and state transitions match mostly with the RFC. However, there are couple of additional transitions for working around small issues noticed during testing. These exceptions are explained in comments within the functions in this file. The method functions, m.func(), are similar to the ones used in RFC 4137, but some small changes have used here to optimize operations and to add functionality needed for fast re-authentication (session resumption).

Function Documentation

int eap_allowed_method	(	struct eap_sm *	sm,
		int	vendor,
		u32	method
	)

Check whether EAP method is allowed.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
vendor	Vendor-Id for expanded types or 0 = IETF for legacy types
method	EAP type

Returns: 1 = allowed EAP method, 0 = not allowed

void eap_clear_config_otp ( struct eap_sm * sm )

Clear used one-time password.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

This function clears a used one-time password (OTP) from the current network configuration. This should be called when the OTP has been used and is not needed anymore.

struct eap_peer_config* eap_get_config ( struct eap_sm * sm )

Get current network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Returns: Pointer to the current network configuration or NULL if not found

EAP peer methods should avoid using this function if they can use other access functions, like eap_get_config_identity() and eap_get_config_password(), that do not require direct access to struct eap_peer_config.

const struct wpa_config_blob* eap_get_config_blob	(	struct eap_sm *	sm,
		const char *	name
	)

Get a named configuration blob.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
name	Name of the blob

Returns: Pointer to blob data or NULL if not found

const u8* eap_get_config_identity	(	struct eap_sm *	sm,
		size_t *	len
	)

Get identity from the network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
len	Buffer for the length of the identity

Returns: Pointer to the identity or NULL if not found

const u8* eap_get_config_new_password	(	struct eap_sm *	sm,
		size_t *	len
	)

Get new password from network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
len	Buffer for the length of the new password

Returns: Pointer to the new password or NULL if not found

const u8* eap_get_config_otp	(	struct eap_sm *	sm,
		size_t *	len
	)

Get one-time password from the network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
len	Buffer for the length of the one-time password

Returns: Pointer to the one-time password or NULL if not found

const u8* eap_get_config_password	(	struct eap_sm *	sm,
		size_t *	len
	)

Get password from the network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
len	Buffer for the length of the password

Returns: Pointer to the password or NULL if not found

const u8* eap_get_config_password2	(	struct eap_sm *	sm,
		size_t *	len,
		int *	hash
	)

Get password from the network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
len	Buffer for the length of the password
hash	Buffer for returning whether the password is stored as a NtPasswordHash instead of plaintext password; can be NULL if this information is not needed

Returns: Pointer to the password or NULL if not found

const char* eap_get_config_phase1 ( struct eap_sm * sm )

Get phase1 data from the network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Returns: Pointer to the phase1 data or NULL if not found

const char* eap_get_config_phase2 ( struct eap_sm * sm )

Get phase2 data from the network configuration.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Returns: Pointer to the phase1 data or NULL if not found

const u8* eap_get_eapKeyData	(	struct eap_sm *	sm,
		size_t *	len
	)

Get master session key (MSK) from EAP state machine.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
len	Pointer to variable that will be set to number of bytes in the key

Returns: Pointer to the EAP keying data or NULL on failure

Fetch EAP keying material (MSK, eapKeyData) from the EAP state machine. The key is available only after a successful authentication. EAP state machine continues to manage the key data and the caller must not change or free the returned data.

struct wpabuf* eap_get_eapRespData ( struct eap_sm * sm )

Get EAP response data.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Returns: Pointer to the EAP response (eapRespData) or NULL on failure

Fetch EAP response (eapRespData) from the EAP state machine. This data is available when EAP state machine has processed an incoming EAP request. The EAP state machine does not maintain a reference to the response after this function is called and the caller is responsible for freeing the data.

const u8* eap_get_eapSessionId	(	struct eap_sm *	sm,
		size_t *	len
	)

Get Session-Id from EAP state machine.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_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

Fetch EAP Session-Id from the EAP state machine. The Session-Id is available only after a successful authentication. EAP state machine continues to manage the Session-Id and the caller must not change or free the returned data.

u32 eap_get_phase2_type	(	const char *	name,
		int *	vendor
	)

Get EAP type for the given EAP phase 2 method name.

Parameters

name	EAP method name, e.g., MD5
vendor	Buffer for returning EAP Vendor-Id

Returns: EAP method type or EAP_TYPE_NONE if not found

This function maps EAP type names into EAP type numbers that are allowed for Phase 2, i.e., for tunneled authentication. Phase 2 is used, e.g., with EAP-PEAP, EAP-TTLS, and EAP-FAST.

struct eap_method_type* eap_get_phase2_types	(	struct eap_peer_config *	config,
		size_t *	count
	)

Get list of allowed EAP phase 2 types.

Parameters

config	Pointer to a network configuration
count	Pointer to a variable to be filled with number of returned EAP types

Returns: Pointer to allocated type list or NULL on failure

This function generates an array of allowed EAP phase 2 (tunneled) types for the given network configuration.

void eap_invalidate_cached_session ( struct eap_sm * sm )

Mark cached session data invalid.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

int eap_key_available ( struct eap_sm * sm )

Get key availability (eapKeyAvailable variable)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Returns: 1 if EAP keying material is available, 0 if not

void eap_notify_lower_layer_success ( struct eap_sm * sm )

Notification of lower layer success.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

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

void eap_notify_pending ( struct eap_sm * sm )

Notify that EAP method is ready to re-process a request.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

An EAP method can perform a pending operation (e.g., to get a response from an external process). Once the response is available, this function can be used to request EAPOL state machine to retry delivering the previously received (and still unanswered) EAP request to EAP state machine.

void eap_notify_success ( struct eap_sm * sm )

Notify EAP state machine about external success trigger.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

This function is called when external event, e.g., successful completion of WPA-PSK key handshake, is indicating that EAP state machine should move to success state. This is mainly used with security modes that do not use EAP state machine (e.g., WPA-PSK).

void eap_peer_sm_deinit ( struct eap_sm * sm )

Deinitialize and free an EAP peer state machine.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

This function deinitializes EAP state machine and frees all allocated resources.

struct eap_sm* eap_peer_sm_init	(	void *	eapol_ctx,
		const struct eapol_callbacks *	eapol_cb,
		void *	msg_ctx,
		struct eap_config *	conf
	)

Allocate and initialize EAP peer state machine.

Parameters

eapol_ctx	Context data to be used with eapol_cb calls
eapol_cb	Pointer to EAPOL callback functions
msg_ctx	Context data for wpa_msg() calls
conf	EAP configuration

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

This function allocates and initializes an EAP state machine. In addition, this initializes TLS library for the new EAP state machine. eapol_cb pointer will be in use until eap_peer_sm_deinit() is used to deinitialize this EAP state machine. Consequently, the caller must make sure that this data structure remains alive while the EAP state machine is active.

int eap_peer_sm_step ( struct eap_sm * sm )

Step EAP peer state machine.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Returns: 1 if EAP state was changed or 0 if not

This function advances EAP state machine to a new state to match with the current variables. This should be called whenever variables used by the EAP state machine have changed.

void eap_register_scard_ctx	(	struct eap_sm *	sm,
		void *	ctx
	)

Notification of smart card context.

Parameters

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

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

void eap_set_anon_id	(	struct eap_sm *	sm,
		const u8 *	id,
		size_t	len
	)

Set or add anonymous identity.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
id	Anonymous identity (e.g., EAP-SIM pseudonym) or NULL to clear
len	Length of anonymous identity in octets

void eap_set_config_blob	(	struct eap_sm *	sm,
		struct wpa_config_blob *	blob
	)

Set or add a named configuration blob.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
blob	New value for the blob

Adds a new configuration blob or replaces the current value of an existing blob.

void eap_set_external_sim	(	struct eap_sm *	sm,
		int	external_sim
	)

Set external_sim flag.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
external_sim	Whether external SIM/USIM processing is used

void eap_set_fast_reauth	(	struct eap_sm *	sm,
		int	enabled
	)

Update fast_reauth setting.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
enabled	1 = Fast reauthentication is enabled, 0 = Disabled

void eap_set_force_disabled	(	struct eap_sm *	sm,
		int	disabled
	)

Set force_disabled flag.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
disabled	1 = EAP disabled, 0 = EAP enabled

This function is used to force EAP state machine to be disabled when it is not in use (e.g., with WPA-PSK or plaintext connections).

void eap_set_workaround	(	struct eap_sm *	sm,
		unsigned int	workaround
	)

Update EAP workarounds setting.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
workaround	1 = Enable EAP workarounds, 0 = Disable EAP workarounds

void eap_sm_abort ( struct eap_sm * sm )

Abort EAP authentication.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

Release system resources that have been allocated for the authentication session without fully deinitializing the EAP state machine.

struct wpabuf* eap_sm_buildIdentity	(	struct eap_sm *	sm,
		int	id,
		int	encrypted
	)

Build EAP-Identity/Response for the current network.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
id	EAP identifier for the packet
encrypted	Whether the packet is for encrypted tunnel (EAP phase 2)

Returns: Pointer to the allocated EAP-Identity/Response packet or NULL on failure

This function allocates and builds an EAP-Identity/Response packet for the current network. The caller is responsible for freeing the returned data.

int eap_sm_get_status	(	struct eap_sm *	sm,
		char *	buf,
		size_t	buflen,
		int	verbose
	)

Get EAP state machine status.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_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 EAP 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.

void eap_sm_notify_ctrl_attached ( struct eap_sm * sm )

Notification of attached monitor.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

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

void eap_sm_request_identity ( struct eap_sm * sm )

Request identity from user (ctrl_iface)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

EAP methods can call this function to request identity information for the current network. This is normally called when the identity is not included in the network configuration. The request will be sent to monitor programs through the control interface.

void eap_sm_request_new_password ( struct eap_sm * sm )

Request new password from user (ctrl_iface)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

EAP methods can call this function to request new password information for the current network. This is normally called when the EAP method indicates that the current password has expired and password change is required. The request will be sent to monitor programs through the control interface.

void eap_sm_request_otp	(	struct eap_sm *	sm,
		const char *	msg,
		size_t	msg_len
	)

Request one time password from user (ctrl_iface)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
msg	Message to be displayed to the user when asking for OTP
msg_len	Length of the user displayable message

EAP methods can call this function to request open time password (OTP) for the current network. The request will be sent to monitor programs through the control interface.

void eap_sm_request_passphrase ( struct eap_sm * sm )

Request passphrase from user (ctrl_iface)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

EAP methods can call this function to request passphrase for a private key for the current network. This is normally called when the passphrase is not included in the network configuration. The request will be sent to monitor programs through the control interface.

void eap_sm_request_password ( struct eap_sm * sm )

Request password from user (ctrl_iface)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

EAP methods can call this function to request password information for the current network. This is normally called when the password is not included in the network configuration. The request will be sent to monitor programs through the control interface.

void eap_sm_request_pin ( struct eap_sm * sm )

Request SIM or smart card PIN from user (ctrl_iface)

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()

EAP methods can call this function to request SIM or smart card PIN information for the current network. This is normally called when the PIN is not included in the network configuration. The request will be sent to monitor programs through the control interface.

void eap_sm_request_sim	(	struct eap_sm *	sm,
		const char *	req
	)

Request external SIM processing.

Parameters

sm	Pointer to EAP state machine allocated with eap_peer_sm_init()
req	EAP method specific request

Macros

Functions

Detailed Description

Function Documentation