eap.c File Reference

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

#include "includes.h"
#include "common.h"
#include "eap_i.h"
#include "config_ssid.h"
#include "tls.h"
#include "crypto.h"
#include "pcsc_funcs.h"
#include "wpa_ctrl.h"
#include "state_machine.h"

Include dependency graph for eap.c:

Go to the source code of this file.

Defines

#define STATE_MACHINE_DATA   struct eap_sm
#define STATE_MACHINE_DEBUG_PREFIX   "EAP"
#define EAP_MAX_AUTH_ROUNDS   50

Enumerations

enum  eap_ctrl_req_type {
  TYPE_IDENTITY, TYPE_PASSWORD, TYPE_OTP, TYPE_PIN,
  TYPE_NEW_PASSWORD, TYPE_PASSPHRASE
}

Functions

 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_smeap_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)
 Request identity from user (ctrl_iface).
void eap_sm_request_password (struct eap_sm *sm)
 Request password from user (ctrl_iface).
void eap_sm_request_new_password (struct eap_sm *sm)
 Request new password from user (ctrl_iface).
void eap_sm_request_pin (struct eap_sm *sm)
 Request SIM or smart card PIN from user (ctrl_iface).
void eap_sm_request_otp (struct eap_sm *sm, const char *msg, size_t msg_len)
 Request one time password from user (ctrl_iface).
void eap_sm_request_passphrase (struct eap_sm *sm)
 Request passphrase from user (ctrl_iface).
void eap_sm_notify_ctrl_attached (struct eap_sm *sm)
 Notification of attached monitor.
u32 eap_get_phase2_type (const char *name, int *vendor)
 Get EAP type for the given EAP phase 2 method name.
eap_method_type * 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_ssideap_get_config (struct eap_sm *sm)
 Get current network configuration.
const u8 * eap_get_config_identity (struct eap_sm *sm, size_t *len)
 Get identity from the network configuration.
const u8 * eap_get_config_password (struct eap_sm *sm, size_t *len)
 Get password from the network configuration.
const u8 * eap_get_config_new_password (struct eap_sm *sm, size_t *len)
 Get new password from network configuration.
const u8 * eap_get_config_otp (struct eap_sm *sm, size_t *len)
 Get one-time password from the network configuration.
void eap_clear_config_otp (struct eap_sm *sm)
 Clear used one-time password.
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 (int vendor, 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_blobeap_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.
eap_hdr * eap_msg_alloc (int vendor, EapType type, size_t *len, size_t payload_len, u8 code, u8 identifier, u8 **payload)
 Allocate a buffer for an EAP message.
void eap_notify_pending (struct eap_sm *sm)
 Notify that EAP method is ready to re-process a request.
void eap_invalidate_cached_session (struct eap_sm *sm)
 Mark cached session data invalid.


Detailed Description

EAP peer state machines (RFC 4137).

Copyright
Copyright (c) 2004-2006, 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.


Function Documentation

void eap_clear_config_otp struct eap_sm sm  ) 
 

Clear used one-time password.

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

Definition at line 1824 of file eap.c.

Here is the call graph for this function:

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

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 2059 of file eap.c.

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_sm_init()
len Buffer for the length of the identity
Returns:
Pointer to the identity or NULL if not found

Definition at line 1754 of file eap.c.

Here is the call graph for this function:

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_sm_init()
len Buffer for the length of the new password
Returns:
Pointer to the new password or NULL if not found

Definition at line 1788 of file eap.c.

Here is the call graph for this function:

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_sm_init()
len Buffer for the length of the one-time password
Returns:
Pointer to the one-time password or NULL if not found

Definition at line 1805 of file eap.c.

Here is the call graph for this function:

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_sm_init()
len Buffer for the length of the password
Returns:
Pointer to the password or NULL if not found

Definition at line 1771 of file eap.c.

Here is the call graph for this function:

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 1907 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 1931 of file eap.c.

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.

Definition at line 1648 of file eap.c.

Here is the call graph for this function:

struct eap_method_type* 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 1671 of file eap.c.

Here is the call graph for this function:

const u8* eap_hdr_validate int  vendor,
EapType  eap_type,
const u8 *  msg,
size_t  msglen,
size_t *  plen
 

Validate EAP header.

Parameters:
vendor Expected EAP Vendor-Id (0 = IETF)
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. This function is able to process both legacy and expanded EAP headers and in most cases, the caller can just use the returned payload pointer (into *plen) for processing the payload regardless of whether the packet used the expanded EAP header or not.

Definition at line 1983 of file eap.c.

Here is the call graph for this function:

void eap_invalidate_cached_session struct eap_sm sm  ) 
 

Mark cached session data invalid.

Parameters:
sm Pointer to EAP state machine allocated with eap_sm_init()

Definition at line 2153 of file eap.c.

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 1842 of file eap.c.

struct eap_hdr* eap_msg_alloc int  vendor,
EapType  type,
size_t *  len,
size_t  payload_len,
u8  code,
u8  identifier,
u8 **  payload
 

Allocate a buffer for an EAP message.

Parameters:
vendor Vendor-Id (0 = IETF)
type EAP type
len Buffer for returning message length
payload_len Payload length in bytes (data after Type)
code Message Code (EAP_CODE_*)
identifier Identifier
payload Pointer to payload pointer that will be set to point to the beginning of the payload or NULL if payload pointer is not needed
Returns:
Pointer to the allocated message buffer or NULL on error
This function can be used to allocate a buffer for an EAP message and fill in the EAP header. This function is automatically using expanded EAP header if the selected Vendor-Id is not IETF. In other words, most EAP methods do not need to separately select which header type to use when using this function to allocate the message buffers.

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

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

Definition at line 2142 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 1858 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 1958 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 2046 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 1712 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 2075 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 1724 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 1235 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 932 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 1193 of file eap.c.

Here is the call graph for this function:

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 1340 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 1155 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 1602 of file eap.c.

Here is the call graph for this function:

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

Definition at line 1507 of file eap.c.

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

Definition at line 1539 of file eap.c.

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

Definition at line 1572 of file eap.c.

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

Definition at line 1588 of file eap.c.

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

Definition at line 1523 of file eap.c.

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

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


Generated on Sun Dec 31 13:51:09 2006 for wpa_supplicant by  doxygen 1.4.2