eap.h revision 252726
1252396Sray/* 2252396Sray * EAP peer state machine functions (RFC 4137) 3252396Sray * Copyright (c) 2004-2012, Jouni Malinen <j@w1.fi> 4252396Sray * 5252396Sray * This software may be distributed under the terms of the BSD license. 6252396Sray * See README for more details. 7252396Sray */ 8252396Sray 9252396Sray#ifndef EAP_H 10252396Sray#define EAP_H 11252396Sray 12252396Sray#include "common/defs.h" 13252396Sray#include "eap_common/eap_defs.h" 14252396Sray#include "eap_peer/eap_methods.h" 15252396Sray 16252396Sraystruct eap_sm; 17252396Sraystruct wpa_config_blob; 18252396Sraystruct wpabuf; 19252396Sray 20252396Sraystruct eap_method_type { 21252396Sray int vendor; 22252396Sray u32 method; 23252396Sray}; 24252396Sray 25252396Sray#ifdef IEEE8021X_EAPOL 26252396Sray 27263245Simp/** 28252396Sray * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine 29252396Sray * 30263301Simp * These variables are used in the interface between EAP peer state machine and 31263301Simp * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 32263301Simp * expected to maintain these variables and register a callback functions for 33263301Simp * EAP state machine to get and set the variables. 34263245Simp */ 35263245Simpenum eapol_bool_var { 36263301Simp /** 37263301Simp * EAPOL_eapSuccess - EAP SUCCESS state reached 38263301Simp * 39263301Simp * EAP state machine reads and writes this value. 40263301Simp */ 41263301Simp EAPOL_eapSuccess, 42263301Simp 43263301Simp /** 44263301Simp * EAPOL_eapRestart - Lower layer request to restart authentication 45263301Simp * 46263301Simp * Set to TRUE in lower layer, FALSE in EAP state machine. 47263301Simp */ 48263301Simp EAPOL_eapRestart, 49263301Simp 50263301Simp /** 51263301Simp * EAPOL_eapFail - EAP FAILURE state reached 52263301Simp * 53263301Simp * EAP state machine writes this value. 54263301Simp */ 55263245Simp EAPOL_eapFail, 56252396Sray 57252396Sray /** 58263245Simp * EAPOL_eapResp - Response to send 59263301Simp * 60263245Simp * Set to TRUE in EAP state machine, FALSE in lower layer. 61263301Simp */ 62263301Simp EAPOL_eapResp, 63263301Simp 64263301Simp /** 65263245Simp * EAPOL_eapNoResp - Request has been process; no response to send 66263245Simp * 67263301Simp * Set to TRUE in EAP state machine, FALSE in lower layer. 68252396Sray */ 69252396Sray EAPOL_eapNoResp, 70263301Simp 71263301Simp /** 72263301Simp * EAPOL_eapReq - EAP request available from lower layer 73252396Sray * 74252396Sray * Set to TRUE in lower layer, FALSE in EAP state machine. 75263245Simp */ 76252396Sray EAPOL_eapReq, 77252396Sray 78252396Sray /** 79252396Sray * EAPOL_portEnabled - Lower layer is ready for communication 80252396Sray * 81252396Sray * EAP state machines reads this value. 82252396Sray */ 83252396Sray EAPOL_portEnabled, 84252396Sray 85252396Sray /** 86263301Simp * EAPOL_altAccept - Alternate indication of success (RFC3748) 87252396Sray * 88252396Sray * EAP state machines reads this value. 89252396Sray */ 90252396Sray EAPOL_altAccept, 91252396Sray 92252396Sray /** 93252396Sray * EAPOL_altReject - Alternate indication of failure (RFC3748) 94252396Sray * 95252396Sray * EAP state machines reads this value. 96252396Sray */ 97252396Sray EAPOL_altReject 98252396Sray}; 99261572Sian 100252396Sray/** 101263301Simp * enum eapol_int_var - EAPOL integer state variables for EAP state machine 102252396Sray * 103252396Sray * These variables are used in the interface between EAP peer state machine and 104252396Sray * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 105252396Sray * expected to maintain these variables and register a callback functions for 106252396Sray * EAP state machine to get and set the variables. 107252396Sray */ 108252396Srayenum eapol_int_var { 109252396Sray /** 110252396Sray * EAPOL_idleWhile - Outside time for EAP peer timeout 111252396Sray * 112252396Sray * This integer variable is used to provide an outside timer that the 113252396Sray * external (to EAP state machine) code must decrement by one every 114252396Sray * second until the value reaches zero. This is used in the same way as 115252396Sray * EAPOL state machine timers. EAP state machine reads and writes this 116252396Sray * value. 117252396Sray */ 118252396Sray EAPOL_idleWhile 119252396Sray}; 120252396Sray 121252396Sray/** 122252396Sray * struct eapol_callbacks - Callback functions from EAP to lower layer 123252396Sray * 124252396Sray * This structure defines the callback functions that EAP state machine 125252396Sray * requires from the lower layer (usually EAPOL state machine) for updating 126252396Sray * state variables and requesting information. eapol_ctx from 127252396Sray * eap_peer_sm_init() call will be used as the ctx parameter for these 128252396Sray * callback functions. 129252396Sray */ 130252396Sraystruct eapol_callbacks { 131252396Sray /** 132252396Sray * get_config - Get pointer to the current network configuration 133252396Sray * @ctx: eapol_ctx from eap_peer_sm_init() call 134252396Sray */ 135252396Sray struct eap_peer_config * (*get_config)(void *ctx); 136252396Sray 137263301Simp /** 138263301Simp * get_bool - Get a boolean EAPOL state variable 139252396Sray * @variable: EAPOL boolean variable to get 140 * Returns: Value of the EAPOL variable 141 */ 142 Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable); 143 144 /** 145 * set_bool - Set a boolean EAPOL state variable 146 * @ctx: eapol_ctx from eap_peer_sm_init() call 147 * @variable: EAPOL boolean variable to set 148 * @value: Value for the EAPOL variable 149 */ 150 void (*set_bool)(void *ctx, enum eapol_bool_var variable, 151 Boolean value); 152 153 /** 154 * get_int - Get an integer EAPOL state variable 155 * @ctx: eapol_ctx from eap_peer_sm_init() call 156 * @variable: EAPOL integer variable to get 157 * Returns: Value of the EAPOL variable 158 */ 159 unsigned int (*get_int)(void *ctx, enum eapol_int_var variable); 160 161 /** 162 * set_int - Set an integer EAPOL state variable 163 * @ctx: eapol_ctx from eap_peer_sm_init() call 164 * @variable: EAPOL integer variable to set 165 * @value: Value for the EAPOL variable 166 */ 167 void (*set_int)(void *ctx, enum eapol_int_var variable, 168 unsigned int value); 169 170 /** 171 * get_eapReqData - Get EAP-Request data 172 * @ctx: eapol_ctx from eap_peer_sm_init() call 173 * @len: Pointer to variable that will be set to eapReqDataLen 174 * Returns: Reference to eapReqData (EAP state machine will not free 175 * this) or %NULL if eapReqData not available. 176 */ 177 struct wpabuf * (*get_eapReqData)(void *ctx); 178 179 /** 180 * set_config_blob - Set named configuration blob 181 * @ctx: eapol_ctx from eap_peer_sm_init() call 182 * @blob: New value for the blob 183 * 184 * Adds a new configuration blob or replaces the current value of an 185 * existing blob. 186 */ 187 void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob); 188 189 /** 190 * get_config_blob - Get a named configuration blob 191 * @ctx: eapol_ctx from eap_peer_sm_init() call 192 * @name: Name of the blob 193 * Returns: Pointer to blob data or %NULL if not found 194 */ 195 const struct wpa_config_blob * (*get_config_blob)(void *ctx, 196 const char *name); 197 198 /** 199 * notify_pending - Notify that a pending request can be retried 200 * @ctx: eapol_ctx from eap_peer_sm_init() call 201 * 202 * An EAP method can perform a pending operation (e.g., to get a 203 * response from an external process). Once the response is available, 204 * this callback function can be used to request EAPOL state machine to 205 * retry delivering the previously received (and still unanswered) EAP 206 * request to EAP state machine. 207 */ 208 void (*notify_pending)(void *ctx); 209 210 /** 211 * eap_param_needed - Notify that EAP parameter is needed 212 * @ctx: eapol_ctx from eap_peer_sm_init() call 213 * @field: Field indicator (e.g., WPA_CTRL_REQ_EAP_IDENTITY) 214 * @txt: User readable text describing the required parameter 215 */ 216 void (*eap_param_needed)(void *ctx, enum wpa_ctrl_req_type field, 217 const char *txt); 218 219 /** 220 * notify_cert - Notification of a peer certificate 221 * @ctx: eapol_ctx from eap_peer_sm_init() call 222 * @depth: Depth in certificate chain (0 = server) 223 * @subject: Subject of the peer certificate 224 * @cert_hash: SHA-256 hash of the certificate 225 * @cert: Peer certificate 226 */ 227 void (*notify_cert)(void *ctx, int depth, const char *subject, 228 const char *cert_hash, const struct wpabuf *cert); 229 230 /** 231 * notify_status - Notification of the current EAP state 232 * @ctx: eapol_ctx from eap_peer_sm_init() call 233 * @status: Step in the process of EAP authentication 234 * @parameter: Step-specific parameter, e.g., EAP method name 235 */ 236 void (*notify_status)(void *ctx, const char *status, 237 const char *parameter); 238 239 /** 240 * set_anon_id - Set or add anonymous identity 241 * @ctx: eapol_ctx from eap_peer_sm_init() call 242 * @id: Anonymous identity (e.g., EAP-SIM pseudonym) or %NULL to clear 243 * @len: Length of anonymous identity in octets 244 */ 245 void (*set_anon_id)(void *ctx, const u8 *id, size_t len); 246}; 247 248/** 249 * struct eap_config - Configuration for EAP state machine 250 */ 251struct eap_config { 252 /** 253 * opensc_engine_path - OpenSC engine for OpenSSL engine support 254 * 255 * Usually, path to engine_opensc.so. 256 */ 257 const char *opensc_engine_path; 258 /** 259 * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support 260 * 261 * Usually, path to engine_pkcs11.so. 262 */ 263 const char *pkcs11_engine_path; 264 /** 265 * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine 266 * 267 * Usually, path to opensc-pkcs11.so. 268 */ 269 const char *pkcs11_module_path; 270 /** 271 * wps - WPS context data 272 * 273 * This is only used by EAP-WSC and can be left %NULL if not available. 274 */ 275 struct wps_context *wps; 276 277 /** 278 * cert_in_cb - Include server certificates in callback 279 */ 280 int cert_in_cb; 281}; 282 283struct eap_sm * eap_peer_sm_init(void *eapol_ctx, 284 struct eapol_callbacks *eapol_cb, 285 void *msg_ctx, struct eap_config *conf); 286void eap_peer_sm_deinit(struct eap_sm *sm); 287int eap_peer_sm_step(struct eap_sm *sm); 288void eap_sm_abort(struct eap_sm *sm); 289int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen, 290 int verbose); 291const char * eap_sm_get_method_name(struct eap_sm *sm); 292struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted); 293void eap_sm_request_identity(struct eap_sm *sm); 294void eap_sm_request_password(struct eap_sm *sm); 295void eap_sm_request_new_password(struct eap_sm *sm); 296void eap_sm_request_pin(struct eap_sm *sm); 297void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len); 298void eap_sm_request_passphrase(struct eap_sm *sm); 299void eap_sm_notify_ctrl_attached(struct eap_sm *sm); 300u32 eap_get_phase2_type(const char *name, int *vendor); 301struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config, 302 size_t *count); 303void eap_set_fast_reauth(struct eap_sm *sm, int enabled); 304void eap_set_workaround(struct eap_sm *sm, unsigned int workaround); 305void eap_set_force_disabled(struct eap_sm *sm, int disabled); 306int eap_key_available(struct eap_sm *sm); 307void eap_notify_success(struct eap_sm *sm); 308void eap_notify_lower_layer_success(struct eap_sm *sm); 309const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len); 310struct wpabuf * eap_get_eapRespData(struct eap_sm *sm); 311void eap_register_scard_ctx(struct eap_sm *sm, void *ctx); 312void eap_invalidate_cached_session(struct eap_sm *sm); 313 314int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf); 315int eap_is_wps_pin_enrollee(struct eap_peer_config *conf); 316 317struct ext_password_data; 318void eap_sm_set_ext_pw_ctx(struct eap_sm *sm, struct ext_password_data *ext); 319void eap_set_anon_id(struct eap_sm *sm, const u8 *id, size_t len); 320 321#endif /* IEEE8021X_EAPOL */ 322 323#endif /* EAP_H */ 324