wpa_supplicant / hostapd  2.5
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Pages
Data Structures | Enumerations | Functions
eap.h File Reference

EAP peer state machine functions (RFC 4137) More...

#include "common/defs.h"
#include "eap_common/eap_defs.h"
#include "eap_peer/eap_methods.h"

Go to the source code of this file.

Data Structures

struct  eap_method_type
 
struct  eapol_callbacks
 Callback functions from EAP to lower layer. More...
 
struct  eap_config
 Configuration for EAP state machine. More...
 

Enumerations

enum  eapol_bool_var {
  EAPOL_eapSuccess, EAPOL_eapRestart, EAPOL_eapFail, EAPOL_eapResp,
  EAPOL_eapNoResp, EAPOL_eapReq, EAPOL_portEnabled, EAPOL_altAccept,
  EAPOL_altReject, EAPOL_eapTriggerStart
}
 EAPOL boolean state variables for EAP state machine. More...
 
enum  eapol_int_var { EAPOL_idleWhile }
 EAPOL integer state variables for EAP state machine. More...
 

Functions

struct eap_smeap_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)
 
struct wpabufeap_sm_buildIdentity (struct eap_sm *sm, int id, int encrypted)
 Build EAP-Identity/Response for the current network. More...
 
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_typeeap_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...
 
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...
 
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 wpabufeap_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_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)
 
void eap_peer_erp_free_keys (struct eap_sm *sm)
 

Detailed Description

EAP peer state machine functions (RFC 4137)

Enumeration Type Documentation

EAPOL boolean state variables for EAP state machine.

These variables are used in the interface between EAP peer state machine and lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is expected to maintain these variables and register a callback functions for EAP state machine to get and set the variables.

Enumerator
EAPOL_eapSuccess 

EAP SUCCESS state reached.

EAP state machine reads and writes this value.

EAPOL_eapRestart 

Lower layer request to restart authentication.

Set to TRUE in lower layer, FALSE in EAP state machine.

EAPOL_eapFail 

EAP FAILURE state reached.

EAP state machine writes this value.

EAPOL_eapResp 

Response to send.

Set to TRUE in EAP state machine, FALSE in lower layer.

EAPOL_eapNoResp 

Request has been process; no response to send.

Set to TRUE in EAP state machine, FALSE in lower layer.

EAPOL_eapReq 

EAP request available from lower layer.

Set to TRUE in lower layer, FALSE in EAP state machine.

EAPOL_portEnabled 

Lower layer is ready for communication.

EAP state machines reads this value.

EAPOL_altAccept 

Alternate indication of success (RFC3748)

EAP state machines reads this value.

EAPOL_altReject 

Alternate indication of failure (RFC3748)

EAP state machines reads this value.

EAPOL_eapTriggerStart 

EAP-based trigger to send EAPOL-Start.

EAP state machine writes this value.

EAPOL integer state variables for EAP state machine.

These variables are used in the interface between EAP peer state machine and lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is expected to maintain these variables and register a callback functions for EAP state machine to get and set the variables.

Enumerator
EAPOL_idleWhile 

Outside time for EAP peer timeout.

This integer variable is used to provide an outside timer that the external (to EAP state machine) code must decrement by one every second until the value reaches zero. This is used in the same way as EAPOL state machine timers. EAP state machine reads and writes this value.

Function Documentation

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

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

Parameters
smPointer to EAP state machine allocated with eap_peer_sm_init()
lenPointer 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
smPointer 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
lenPointer 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
nameEAP method name, e.g., MD5
vendorBuffer 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
configPointer to a network configuration
countPointer 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
int eap_key_available ( struct eap_sm sm)

Get key availability (eapKeyAvailable variable)

Parameters
smPointer 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
smPointer 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_success ( struct eap_sm sm)

Notify EAP state machine about external success trigger.

Parameters
smPointer 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
smPointer 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_ctxContext data to be used with eapol_cb calls
eapol_cbPointer to EAPOL callback functions
msg_ctxContext data for wpa_msg() calls
confEAP 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
smPointer 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
ctxContext 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
idAnonymous identity (e.g., EAP-SIM pseudonym) or NULL to clear
lenLength of anonymous identity in octets
void eap_set_external_sim ( struct eap_sm sm,
int  external_sim 
)

Set external_sim flag.

Parameters
smPointer to EAP state machine allocated with eap_peer_sm_init()
external_simWhether external SIM/USIM processing is used
void eap_set_fast_reauth ( struct eap_sm sm,
int  enabled 
)

Update fast_reauth setting.

Parameters
smPointer to EAP state machine allocated with eap_peer_sm_init()
enabled1 = Fast reauthentication is enabled, 0 = Disabled
void eap_set_force_disabled ( struct eap_sm sm,
int  disabled 
)

Set force_disabled flag.

Parameters
smPointer to EAP state machine allocated with eap_peer_sm_init()
disabled1 = 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
workaround1 = Enable EAP workarounds, 0 = Disable EAP workarounds
void eap_sm_abort ( struct eap_sm sm)

Abort EAP authentication.

Parameters
smPointer 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
idEAP identifier for the packet
encryptedWhether 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
bufBuffer for status information
buflenMaximum buffer length
verboseWhether 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
smPointer 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
smPointer 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
smPointer 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
msgMessage to be displayed to the user when asking for OTP
msg_lenLength 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
smPointer 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
smPointer 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
smPointer 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
smPointer to EAP state machine allocated with eap_peer_sm_init()
reqEAP method specific request