eap.c File Reference

WPA Supplicant / EAP state machines (RFC 4137). More...

#include <stdlib.h>
#include <stdio.h>
#include <string.h>
#include <ctype.h>
#include "common.h"
#include "eap_i.h"
#include "wpa_supplicant.h"
#include "config_ssid.h"
#include "tls.h"
#include "crypto.h"
#include "pcsc_funcs.h"
#include "wpa_ctrl.h"

Include dependency graph for eap.c:

Go to the source code of this file.

Defines
#define	EAP_MAX_AUTH_ROUNDS   50
#define	NUM_EAP_METHODS   (sizeof(eap_methods) / sizeof(eap_methods[0]))
#define	SM_STATE(machine, state)
#define	SM_ENTRY(machine, state)
#define	SM_ENTER(machine, state)   sm_ ## machine ## _ ## state ## _Enter(sm, 0)
#define	SM_ENTER_GLOBAL(machine, state)   sm_ ## machine ## _ ## state ## _Enter(sm, 1)
#define	SM_STEP(machine)   static void sm_ ## machine ## _Step(struct eap_sm *sm)
#define	SM_STEP_RUN(machine)   sm_ ## machine ## _Step(sm)
Enumerations
enum	eap_ctrl_req_type {   TYPE_IDENTITY, TYPE_PASSWORD, TYPE_OTP, TYPE_PIN,   TYPE_NEW_PASSWORD, TYPE_PASSPHRASE }
Functions
const struct eap_method *	eap_sm_get_eap_methods (int method)
	Get EAP method based on type number.
	SM_STATE (EAP, INITIALIZE)
	SM_STATE (EAP, DISABLED)
	SM_STATE (EAP, IDLE)
	SM_STATE (EAP, RECEIVED)
	SM_STATE (EAP, GET_METHOD)
	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)
u8 *	eap_sm_buildIdentity (struct eap_sm *sm, int id, size_t *len, int encrypted)
	Build EAP-Identity/Response for the current network.
eap_sm *	eap_sm_init (void *eapol_ctx, struct eapol_callbacks *eapol_cb, void *msg_ctx, struct eap_config *conf)
	Allocate and initialize EAP state machine.
void	eap_sm_deinit (struct eap_sm *sm)
	Deinitialize and free an EAP state machine.
int	eap_sm_step (struct eap_sm *sm)
	Step EAP state machine.
void	eap_sm_abort (struct eap_sm *sm)
	Abort EAP authentication.
int	eap_sm_get_status (struct eap_sm *sm, char *buf, size_t buflen, int verbose)
	Get EAP state machine status.
void	eap_sm_request_identity (struct eap_sm *sm, struct wpa_ssid *config)
	Request identity from user (ctrl_iface).
void	eap_sm_request_password (struct eap_sm *sm, struct wpa_ssid *config)
	Request password from user (ctrl_iface).
void	eap_sm_request_new_password (struct eap_sm *sm, struct wpa_ssid *config)
	Request new password from user (ctrl_iface).
void	eap_sm_request_pin (struct eap_sm *sm, struct wpa_ssid *config)
	Request SIM or smart card PIN from user (ctrl_iface).
void	eap_sm_request_otp (struct eap_sm *sm, struct wpa_ssid *config, const char *msg, size_t msg_len)
	Request one time password from user (ctrl_iface).
void	eap_sm_request_passphrase (struct eap_sm *sm, struct wpa_ssid *config)
	Request passphrase from user (ctrl_iface).
void	eap_sm_notify_ctrl_attached (struct eap_sm *sm)
	Notification of attached monitor.
u8	eap_get_type (const char *name)
	Get EAP type for the given EAP method name.
const char *	eap_get_name (EapType type)
	Get EAP method name for the given EAP type.
size_t	eap_get_names (char *buf, size_t buflen)
	Get space separated list of names for supported EAP methods.
u8	eap_get_phase2_type (const char *name)
	Get EAP type for the given EAP phase 2 method name.
u8 *	eap_get_phase2_types (struct wpa_ssid *config, size_t *count)
	Get list of allowed EAP phase 2 types.
void	eap_set_fast_reauth (struct eap_sm *sm, int enabled)
	Update fast_reauth setting.
void	eap_set_workaround (struct eap_sm *sm, unsigned int workaround)
	Update EAP workarounds setting.
wpa_ssid *	eap_get_config (struct eap_sm *sm)
	Get current network configuration.
int	eap_key_available (struct eap_sm *sm)
	Get key availability (eapKeyAvailable variable).
void	eap_notify_success (struct eap_sm *sm)
	Notify EAP state machine about external success trigger.
void	eap_notify_lower_layer_success (struct eap_sm *sm)
	Notification of lower layer success.
const u8 *	eap_get_eapKeyData (struct eap_sm *sm, size_t *len)
	Get master session key (MSK) from EAP state machine.
u8 *	eap_get_eapRespData (struct eap_sm *sm, size_t *len)
	Get EAP response data.
void	eap_register_scard_ctx (struct eap_sm *sm, void *ctx)
	Notification of smart card context.
const u8 *	eap_hdr_validate (EapType eap_type, const u8 *msg, size_t msglen, size_t *plen)
	Validate EAP header.
void	eap_set_config_blob (struct eap_sm *sm, struct wpa_config_blob *blob)
	Set or add a named configuration blob.
const struct wpa_config_blob *	eap_get_config_blob (struct eap_sm *sm, const char *name)
	Get a named configuration blob.
void	eap_set_force_disabled (struct eap_sm *sm, int disabled)
	Set force_disabled flag.

---

Detailed Description

WPA Supplicant / EAP state machines (RFC 4137).

Copyright

Copyright (c) 2004-2005, Jouni Malinen <[email protected]>

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License version 2 as published by the Free Software Foundation.

Alternatively, this software may be distributed under the terms of BSD license.

See README and COPYING for more details.

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

Definition in file eap.c.

---

Define Documentation

#define SM_ENTRY (  machine, state   )

Value: if (!global || sm->machine ## _state != machine ## _ ## state) { \ sm->changed = TRUE; \ wpa_printf(MSG_DEBUG, "EAP: " #machine " entering state " #state); \ } \ sm->machine ## _state = machine ## _ ## state; Definition at line 161 of file eap.c.

#define SM_STATE (  machine, state   )

Value: static void sm_ ## machine ## _ ## state ## _Enter(struct eap_sm *sm, \ int global) Definition at line 157 of file eap.c.

---

Function Documentation

struct wpa_ssid* eap_get_config (  struct eap_sm *  sm  )

Get current network configuration. Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() Returns: Pointer to the current network configuration or NULL if not found Definition at line 1741 of file eap.c.

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_sm_init() name  Name of the blob Returns: Pointer to blob data or NULL if not found Definition at line 1934 of file eap.c.

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_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. Definition at line 1818 of file eap.c.

u8* eap_get_eapRespData (  struct eap_sm *  sm, size_t *  len )

Get EAP response data. Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() len  Pointer to variable that will be set to the length of the response 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. Definition at line 1842 of file eap.c.

const char* eap_get_name (  EapType  type  )

Get EAP method name for the given EAP type. Parameters: type  EAP method type Returns: EAP method name, e.g., TLS, or NULL if not found This function maps EAP type numbers into EAP type names based on the list of EAP methods included in the build. Definition at line 1614 of file eap.c.

size_t eap_get_names (  char *  buf, size_t  buflen )

Get space separated list of names for supported EAP methods. Parameters: buf  Buffer for names buflen  Buffer length Returns: Number of characters written into buf (not including nul termination) Definition at line 1633 of file eap.c.

u8 eap_get_phase2_type (  const char *  name  )

Get EAP type for the given EAP phase 2 method name. Parameters: name  EAP method name, e.g., MD5 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. Definition at line 1667 of file eap.c. Here is the call graph for this function:

u8* eap_get_phase2_types (  struct wpa_ssid *  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. Definition at line 1686 of file eap.c.

u8 eap_get_type (  const char *  name  )

Get EAP type for the given EAP method name. Parameters: name  EAP method name, e.g., TLS Returns: EAP method type or EAP_TYPE_NONE if not found This function maps EAP type names into EAP type numbers based on the list of EAP methods included in the build. Definition at line 1594 of file eap.c.

const u8* eap_hdr_validate (  EapType  eap_type, const u8 *  msg, size_t  msglen, size_t *  plen )

Validate EAP header. Parameters: eap_type  Expected EAP type number msg  EAP frame (starting with EAP header) msglen  Length of msg plen  Pointer to variable to contain the returned payload length Returns: Pointer to EAP payload (after type field), or NULL on failure This is a helper function for EAP method implementations. This is usually called in the beginning of struct eap_method::process() function to verify that the received EAP request packet has a valid header. Definition at line 1889 of file eap.c. Here is the call graph for this function:

int eap_key_available (  struct eap_sm *  sm  )

Get key availability (eapKeyAvailable variable). Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() Returns: 1 if EAP keying material is available, 0 if not Definition at line 1753 of file eap.c.

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_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. Definition at line 1786 of file eap.c.

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_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). Definition at line 1769 of file eap.c.

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_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. Definition at line 1869 of file eap.c.

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_sm_init() blob  New value for the blob Adds a new configuration blob or replaces the current value of an existing blob. Definition at line 1921 of file eap.c.

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_sm_init() enabled  1 = Fast reauthentication is enabled, 0 = Disabled Definition at line 1717 of file eap.c.

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_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). Definition at line 1950 of file eap.c.

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_sm_init() workaround  1 = Enable EAP workarounds, 0 = Disable EAP workarounds Definition at line 1729 of file eap.c.

void eap_sm_abort (  struct eap_sm *  sm  )

Abort EAP authentication. Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() Release system resources that have been allocated for the authentication session without fully deinitializing the EAP state machine. Definition at line 1219 of file eap.c.

u8* eap_sm_buildIdentity (  struct eap_sm *  sm, int  id, size_t *  len, int  encrypted )

Build EAP-Identity/Response for the current network. Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() id  EAP identifier for the packet len  Pointer to a variable that will be set to the length of the response 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. Definition at line 940 of file eap.c. Here is the call graph for this function:

void eap_sm_deinit (  struct eap_sm *  sm  )

Deinitialize and free an EAP state machine. Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() This function deinitializes EAP state machine and frees all allocated resources. Definition at line 1177 of file eap.c. Here is the call graph for this function:

const struct eap_method* eap_sm_get_eap_methods (  int  method  )

Get EAP method based on type number. Parameters: method  EAP type number Returns: Pointer to EAP method of NULL if not found Definition at line 134 of file eap.c.

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_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. Definition at line 1313 of file eap.c. Here is the call graph for this function:

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

Allocate and initialize EAP 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_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. Definition at line 1138 of file eap.c. Here is the call graph for this function:

void eap_sm_notify_ctrl_attached (  struct eap_sm *  sm  )

Notification of attached monitor. Parameters: sm  Pointer to EAP state machine allocated with eap_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. Definition at line 1559 of file eap.c. Here is the call graph for this function:

void eap_sm_request_identity (  struct eap_sm *  sm, struct wpa_ssid *  config )

Request identity from user (ctrl_iface). Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() config  Pointer to the current network configuration 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. Definition at line 1458 of file eap.c.

void eap_sm_request_new_password (  struct eap_sm *  sm, struct wpa_ssid *  config )

Request new password from user (ctrl_iface). Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() config  Pointer to the current network configuration 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. Definition at line 1492 of file eap.c.

void eap_sm_request_otp (  struct eap_sm *  sm, struct wpa_ssid *  config, 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_sm_init() config  Pointer to the current network configuration 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. Definition at line 1527 of file eap.c.

void eap_sm_request_passphrase (  struct eap_sm *  sm, struct wpa_ssid *  config )

Request passphrase from user (ctrl_iface). Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() config  Pointer to the current network configuration 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. Definition at line 1545 of file eap.c.

void eap_sm_request_password (  struct eap_sm *  sm, struct wpa_ssid *  config )

Request password from user (ctrl_iface). Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() config  Pointer to the current network configuration 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. Definition at line 1475 of file eap.c.

void eap_sm_request_pin (  struct eap_sm *  sm, struct wpa_ssid *  config )

Request SIM or smart card PIN from user (ctrl_iface). Parameters: sm  Pointer to EAP state machine allocated with eap_sm_init() config  Pointer to the current network configuration 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. Definition at line 1509 of file eap.c.

int eap_sm_step (  struct eap_sm *  sm  )

Step EAP state machine. Parameters: sm  Pointer to EAP state machine allocated with eap_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. Definition at line 1198 of file eap.c.

---