1189251Ssam/* 2189251Ssam * EAP peer state machine functions (RFC 4137) 3252726Srpaulo * Copyright (c) 2004-2012, Jouni Malinen <j@w1.fi> 4189251Ssam * 5252726Srpaulo * This software may be distributed under the terms of the BSD license. 6252726Srpaulo * See README for more details. 7189251Ssam */ 8189251Ssam 9189251Ssam#ifndef EAP_H 10189251Ssam#define EAP_H 11189251Ssam 12214734Srpaulo#include "common/defs.h" 13189251Ssam#include "eap_common/eap_defs.h" 14189251Ssam#include "eap_peer/eap_methods.h" 15189251Ssam 16189251Ssamstruct eap_sm; 17189251Ssamstruct wpa_config_blob; 18189251Ssamstruct wpabuf; 19189251Ssam 20189251Ssamstruct eap_method_type { 21189251Ssam int vendor; 22189251Ssam u32 method; 23189251Ssam}; 24189251Ssam 25189251Ssam#ifdef IEEE8021X_EAPOL 26189251Ssam 27189251Ssam/** 28189251Ssam * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine 29189251Ssam * 30189251Ssam * These variables are used in the interface between EAP peer state machine and 31189251Ssam * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 32189251Ssam * expected to maintain these variables and register a callback functions for 33189251Ssam * EAP state machine to get and set the variables. 34189251Ssam */ 35189251Ssamenum eapol_bool_var { 36189251Ssam /** 37189251Ssam * EAPOL_eapSuccess - EAP SUCCESS state reached 38189251Ssam * 39189251Ssam * EAP state machine reads and writes this value. 40189251Ssam */ 41189251Ssam EAPOL_eapSuccess, 42189251Ssam 43189251Ssam /** 44189251Ssam * EAPOL_eapRestart - Lower layer request to restart authentication 45189251Ssam * 46189251Ssam * Set to TRUE in lower layer, FALSE in EAP state machine. 47189251Ssam */ 48189251Ssam EAPOL_eapRestart, 49189251Ssam 50189251Ssam /** 51189251Ssam * EAPOL_eapFail - EAP FAILURE state reached 52189251Ssam * 53189251Ssam * EAP state machine writes this value. 54189251Ssam */ 55189251Ssam EAPOL_eapFail, 56189251Ssam 57189251Ssam /** 58189251Ssam * EAPOL_eapResp - Response to send 59189251Ssam * 60189251Ssam * Set to TRUE in EAP state machine, FALSE in lower layer. 61189251Ssam */ 62189251Ssam EAPOL_eapResp, 63189251Ssam 64189251Ssam /** 65189251Ssam * EAPOL_eapNoResp - Request has been process; no response to send 66189251Ssam * 67189251Ssam * Set to TRUE in EAP state machine, FALSE in lower layer. 68189251Ssam */ 69189251Ssam EAPOL_eapNoResp, 70189251Ssam 71189251Ssam /** 72189251Ssam * EAPOL_eapReq - EAP request available from lower layer 73189251Ssam * 74189251Ssam * Set to TRUE in lower layer, FALSE in EAP state machine. 75189251Ssam */ 76189251Ssam EAPOL_eapReq, 77189251Ssam 78189251Ssam /** 79189251Ssam * EAPOL_portEnabled - Lower layer is ready for communication 80189251Ssam * 81189251Ssam * EAP state machines reads this value. 82189251Ssam */ 83189251Ssam EAPOL_portEnabled, 84189251Ssam 85189251Ssam /** 86189251Ssam * EAPOL_altAccept - Alternate indication of success (RFC3748) 87189251Ssam * 88189251Ssam * EAP state machines reads this value. 89189251Ssam */ 90189251Ssam EAPOL_altAccept, 91189251Ssam 92189251Ssam /** 93189251Ssam * EAPOL_altReject - Alternate indication of failure (RFC3748) 94189251Ssam * 95189251Ssam * EAP state machines reads this value. 96189251Ssam */ 97189251Ssam EAPOL_altReject 98189251Ssam}; 99189251Ssam 100189251Ssam/** 101189251Ssam * enum eapol_int_var - EAPOL integer state variables for EAP state machine 102189251Ssam * 103189251Ssam * These variables are used in the interface between EAP peer state machine and 104189251Ssam * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 105189251Ssam * expected to maintain these variables and register a callback functions for 106189251Ssam * EAP state machine to get and set the variables. 107189251Ssam */ 108189251Ssamenum eapol_int_var { 109189251Ssam /** 110189251Ssam * EAPOL_idleWhile - Outside time for EAP peer timeout 111189251Ssam * 112189251Ssam * This integer variable is used to provide an outside timer that the 113189251Ssam * external (to EAP state machine) code must decrement by one every 114189251Ssam * second until the value reaches zero. This is used in the same way as 115189251Ssam * EAPOL state machine timers. EAP state machine reads and writes this 116189251Ssam * value. 117189251Ssam */ 118189251Ssam EAPOL_idleWhile 119189251Ssam}; 120189251Ssam 121189251Ssam/** 122189251Ssam * struct eapol_callbacks - Callback functions from EAP to lower layer 123189251Ssam * 124189251Ssam * This structure defines the callback functions that EAP state machine 125189251Ssam * requires from the lower layer (usually EAPOL state machine) for updating 126189251Ssam * state variables and requesting information. eapol_ctx from 127189251Ssam * eap_peer_sm_init() call will be used as the ctx parameter for these 128189251Ssam * callback functions. 129189251Ssam */ 130189251Ssamstruct eapol_callbacks { 131189251Ssam /** 132189251Ssam * get_config - Get pointer to the current network configuration 133189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 134189251Ssam */ 135189251Ssam struct eap_peer_config * (*get_config)(void *ctx); 136189251Ssam 137189251Ssam /** 138189251Ssam * get_bool - Get a boolean EAPOL state variable 139189251Ssam * @variable: EAPOL boolean variable to get 140189251Ssam * Returns: Value of the EAPOL variable 141189251Ssam */ 142189251Ssam Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable); 143189251Ssam 144189251Ssam /** 145189251Ssam * set_bool - Set a boolean EAPOL state variable 146189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 147189251Ssam * @variable: EAPOL boolean variable to set 148189251Ssam * @value: Value for the EAPOL variable 149189251Ssam */ 150189251Ssam void (*set_bool)(void *ctx, enum eapol_bool_var variable, 151189251Ssam Boolean value); 152189251Ssam 153189251Ssam /** 154189251Ssam * get_int - Get an integer EAPOL state variable 155189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 156189251Ssam * @variable: EAPOL integer variable to get 157189251Ssam * Returns: Value of the EAPOL variable 158189251Ssam */ 159189251Ssam unsigned int (*get_int)(void *ctx, enum eapol_int_var variable); 160189251Ssam 161189251Ssam /** 162189251Ssam * set_int - Set an integer EAPOL state variable 163189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 164189251Ssam * @variable: EAPOL integer variable to set 165189251Ssam * @value: Value for the EAPOL variable 166189251Ssam */ 167189251Ssam void (*set_int)(void *ctx, enum eapol_int_var variable, 168189251Ssam unsigned int value); 169189251Ssam 170189251Ssam /** 171189251Ssam * get_eapReqData - Get EAP-Request data 172189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 173189251Ssam * @len: Pointer to variable that will be set to eapReqDataLen 174189251Ssam * Returns: Reference to eapReqData (EAP state machine will not free 175189251Ssam * this) or %NULL if eapReqData not available. 176189251Ssam */ 177189251Ssam struct wpabuf * (*get_eapReqData)(void *ctx); 178189251Ssam 179189251Ssam /** 180189251Ssam * set_config_blob - Set named configuration blob 181189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 182189251Ssam * @blob: New value for the blob 183189251Ssam * 184189251Ssam * Adds a new configuration blob or replaces the current value of an 185189251Ssam * existing blob. 186189251Ssam */ 187189251Ssam void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob); 188189251Ssam 189189251Ssam /** 190189251Ssam * get_config_blob - Get a named configuration blob 191189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 192189251Ssam * @name: Name of the blob 193189251Ssam * Returns: Pointer to blob data or %NULL if not found 194189251Ssam */ 195189251Ssam const struct wpa_config_blob * (*get_config_blob)(void *ctx, 196189251Ssam const char *name); 197189251Ssam 198189251Ssam /** 199189251Ssam * notify_pending - Notify that a pending request can be retried 200189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 201189251Ssam * 202189251Ssam * An EAP method can perform a pending operation (e.g., to get a 203189251Ssam * response from an external process). Once the response is available, 204189251Ssam * this callback function can be used to request EAPOL state machine to 205189251Ssam * retry delivering the previously received (and still unanswered) EAP 206189251Ssam * request to EAP state machine. 207189251Ssam */ 208189251Ssam void (*notify_pending)(void *ctx); 209189251Ssam 210189251Ssam /** 211189251Ssam * eap_param_needed - Notify that EAP parameter is needed 212189251Ssam * @ctx: eapol_ctx from eap_peer_sm_init() call 213252726Srpaulo * @field: Field indicator (e.g., WPA_CTRL_REQ_EAP_IDENTITY) 214189251Ssam * @txt: User readable text describing the required parameter 215189251Ssam */ 216252726Srpaulo void (*eap_param_needed)(void *ctx, enum wpa_ctrl_req_type field, 217189251Ssam const char *txt); 218252726Srpaulo 219252726Srpaulo /** 220252726Srpaulo * notify_cert - Notification of a peer certificate 221252726Srpaulo * @ctx: eapol_ctx from eap_peer_sm_init() call 222252726Srpaulo * @depth: Depth in certificate chain (0 = server) 223252726Srpaulo * @subject: Subject of the peer certificate 224252726Srpaulo * @cert_hash: SHA-256 hash of the certificate 225252726Srpaulo * @cert: Peer certificate 226252726Srpaulo */ 227252726Srpaulo void (*notify_cert)(void *ctx, int depth, const char *subject, 228252726Srpaulo const char *cert_hash, const struct wpabuf *cert); 229252726Srpaulo 230252726Srpaulo /** 231252726Srpaulo * notify_status - Notification of the current EAP state 232252726Srpaulo * @ctx: eapol_ctx from eap_peer_sm_init() call 233252726Srpaulo * @status: Step in the process of EAP authentication 234252726Srpaulo * @parameter: Step-specific parameter, e.g., EAP method name 235252726Srpaulo */ 236252726Srpaulo void (*notify_status)(void *ctx, const char *status, 237252726Srpaulo const char *parameter); 238252726Srpaulo 239252726Srpaulo /** 240252726Srpaulo * set_anon_id - Set or add anonymous identity 241252726Srpaulo * @ctx: eapol_ctx from eap_peer_sm_init() call 242252726Srpaulo * @id: Anonymous identity (e.g., EAP-SIM pseudonym) or %NULL to clear 243252726Srpaulo * @len: Length of anonymous identity in octets 244252726Srpaulo */ 245252726Srpaulo void (*set_anon_id)(void *ctx, const u8 *id, size_t len); 246189251Ssam}; 247189251Ssam 248189251Ssam/** 249189251Ssam * struct eap_config - Configuration for EAP state machine 250189251Ssam */ 251189251Ssamstruct eap_config { 252189251Ssam /** 253189251Ssam * opensc_engine_path - OpenSC engine for OpenSSL engine support 254189251Ssam * 255189251Ssam * Usually, path to engine_opensc.so. 256189251Ssam */ 257189251Ssam const char *opensc_engine_path; 258189251Ssam /** 259189251Ssam * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support 260189251Ssam * 261189251Ssam * Usually, path to engine_pkcs11.so. 262189251Ssam */ 263189251Ssam const char *pkcs11_engine_path; 264189251Ssam /** 265189251Ssam * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine 266189251Ssam * 267189251Ssam * Usually, path to opensc-pkcs11.so. 268189251Ssam */ 269189251Ssam const char *pkcs11_module_path; 270189251Ssam /** 271189251Ssam * wps - WPS context data 272189251Ssam * 273189251Ssam * This is only used by EAP-WSC and can be left %NULL if not available. 274189251Ssam */ 275189251Ssam struct wps_context *wps; 276252726Srpaulo 277252726Srpaulo /** 278252726Srpaulo * cert_in_cb - Include server certificates in callback 279252726Srpaulo */ 280252726Srpaulo int cert_in_cb; 281189251Ssam}; 282189251Ssam 283189251Ssamstruct eap_sm * eap_peer_sm_init(void *eapol_ctx, 284189251Ssam struct eapol_callbacks *eapol_cb, 285189251Ssam void *msg_ctx, struct eap_config *conf); 286189251Ssamvoid eap_peer_sm_deinit(struct eap_sm *sm); 287189251Ssamint eap_peer_sm_step(struct eap_sm *sm); 288189251Ssamvoid eap_sm_abort(struct eap_sm *sm); 289189251Ssamint eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen, 290189251Ssam int verbose); 291252726Srpauloconst char * eap_sm_get_method_name(struct eap_sm *sm); 292189251Ssamstruct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted); 293189251Ssamvoid eap_sm_request_identity(struct eap_sm *sm); 294189251Ssamvoid eap_sm_request_password(struct eap_sm *sm); 295189251Ssamvoid eap_sm_request_new_password(struct eap_sm *sm); 296189251Ssamvoid eap_sm_request_pin(struct eap_sm *sm); 297189251Ssamvoid eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len); 298189251Ssamvoid eap_sm_request_passphrase(struct eap_sm *sm); 299189251Ssamvoid eap_sm_notify_ctrl_attached(struct eap_sm *sm); 300189251Ssamu32 eap_get_phase2_type(const char *name, int *vendor); 301189251Ssamstruct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config, 302189251Ssam size_t *count); 303189251Ssamvoid eap_set_fast_reauth(struct eap_sm *sm, int enabled); 304189251Ssamvoid eap_set_workaround(struct eap_sm *sm, unsigned int workaround); 305189251Ssamvoid eap_set_force_disabled(struct eap_sm *sm, int disabled); 306189251Ssamint eap_key_available(struct eap_sm *sm); 307189251Ssamvoid eap_notify_success(struct eap_sm *sm); 308189251Ssamvoid eap_notify_lower_layer_success(struct eap_sm *sm); 309189251Ssamconst u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len); 310189251Ssamstruct wpabuf * eap_get_eapRespData(struct eap_sm *sm); 311189251Ssamvoid eap_register_scard_ctx(struct eap_sm *sm, void *ctx); 312189251Ssamvoid eap_invalidate_cached_session(struct eap_sm *sm); 313189251Ssam 314189251Ssamint eap_is_wps_pbc_enrollee(struct eap_peer_config *conf); 315189251Ssamint eap_is_wps_pin_enrollee(struct eap_peer_config *conf); 316189251Ssam 317252726Srpaulostruct ext_password_data; 318252726Srpaulovoid eap_sm_set_ext_pw_ctx(struct eap_sm *sm, struct ext_password_data *ext); 319252726Srpaulovoid eap_set_anon_id(struct eap_sm *sm, const u8 *id, size_t len); 320252726Srpaulo 321189251Ssam#endif /* IEEE8021X_EAPOL */ 322189251Ssam 323189251Ssam#endif /* EAP_H */ 324