1 /* 2 * EAP peer state machines internal structures (RFC 4137) 3 * Copyright (c) 2004-2007, Jouni Malinen <j@w1.fi> 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License version 2 as 7 * published by the Free Software Foundation. 8 * 9 * Alternatively, this software may be distributed under the terms of BSD 10 * license. 11 * 12 * See README and COPYING for more details. 13 */ 14 15 #ifndef EAP_I_H 16 #define EAP_I_H 17 18 #include "wpabuf.h" 19 #include "eap_peer/eap.h" 20 #include "eap_common/eap_common.h" 21 22 /* RFC 4137 - EAP Peer state machine */ 23 24 typedef enum { 25 DECISION_FAIL, DECISION_COND_SUCC, DECISION_UNCOND_SUCC 26 } EapDecision; 27 28 typedef enum { 29 METHOD_NONE, METHOD_INIT, METHOD_CONT, METHOD_MAY_CONT, METHOD_DONE 30 } EapMethodState; 31 32 /** 33 * struct eap_method_ret - EAP return values from struct eap_method::process() 34 * 35 * These structure contains OUT variables for the interface between peer state 36 * machine and methods (RFC 4137, Sect. 4.2). eapRespData will be returned as 37 * the return value of struct eap_method::process() so it is not included in 38 * this structure. 39 */ 40 struct eap_method_ret { 41 /** 42 * ignore - Whether method decided to drop the current packed (OUT) 43 */ 44 Boolean ignore; 45 46 /** 47 * methodState - Method-specific state (IN/OUT) 48 */ 49 EapMethodState methodState; 50 51 /** 52 * decision - Authentication decision (OUT) 53 */ 54 EapDecision decision; 55 56 /** 57 * allowNotifications - Whether method allows notifications (OUT) 58 */ 59 Boolean allowNotifications; 60 }; 61 62 63 /** 64 * struct eap_method - EAP method interface 65 * This structure defines the EAP method interface. Each method will need to 66 * register its own EAP type, EAP name, and set of function pointers for method 67 * specific operations. This interface is based on section 4.4 of RFC 4137. 68 */ 69 struct eap_method { 70 /** 71 * vendor - EAP Vendor-ID (EAP_VENDOR_*) (0 = IETF) 72 */ 73 int vendor; 74 75 /** 76 * method - EAP type number (EAP_TYPE_*) 77 */ 78 EapType method; 79 80 /** 81 * name - Name of the method (e.g., "TLS") 82 */ 83 const char *name; 84 85 /** 86 * init - Initialize an EAP method 87 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 88 * Returns: Pointer to allocated private data, or %NULL on failure 89 * 90 * This function is used to initialize the EAP method explicitly 91 * instead of using METHOD_INIT state as specific in RFC 4137. The 92 * method is expected to initialize it method-specific state and return 93 * a pointer that will be used as the priv argument to other calls. 94 */ 95 void * (*init)(struct eap_sm *sm); 96 97 /** 98 * deinit - Deinitialize an EAP method 99 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 100 * @priv: Pointer to private EAP method data from eap_method::init() 101 * 102 * Deinitialize the EAP method and free any allocated private data. 103 */ 104 void (*deinit)(struct eap_sm *sm, void *priv); 105 106 /** 107 * process - Process an EAP request 108 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 109 * @priv: Pointer to private EAP method data from eap_method::init() 110 * @ret: Return values from EAP request validation and processing 111 * @reqData: EAP request to be processed (eapReqData) 112 * Returns: Pointer to allocated EAP response packet (eapRespData) 113 * 114 * This function is a combination of m.check(), m.process(), and 115 * m.buildResp() procedures defined in section 4.4 of RFC 4137 In other 116 * words, this function validates the incoming request, processes it, 117 * and build a response packet. m.check() and m.process() return values 118 * are returned through struct eap_method_ret *ret variable. Caller is 119 * responsible for freeing the returned EAP response packet. 120 */ 121 struct wpabuf * (*process)(struct eap_sm *sm, void *priv, 122 struct eap_method_ret *ret, 123 const struct wpabuf *reqData); 124 125 /** 126 * isKeyAvailable - Find out whether EAP method has keying material 127 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 128 * @priv: Pointer to private EAP method data from eap_method::init() 129 * Returns: %TRUE if key material (eapKeyData) is available 130 */ 131 Boolean (*isKeyAvailable)(struct eap_sm *sm, void *priv); 132 133 /** 134 * getKey - Get EAP method specific keying material (eapKeyData) 135 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 136 * @priv: Pointer to private EAP method data from eap_method::init() 137 * @len: Pointer to variable to store key length (eapKeyDataLen) 138 * Returns: Keying material (eapKeyData) or %NULL if not available 139 * 140 * This function can be used to get the keying material from the EAP 141 * method. The key may already be stored in the method-specific private 142 * data or this function may derive the key. 143 */ 144 u8 * (*getKey)(struct eap_sm *sm, void *priv, size_t *len); 145 146 /** 147 * get_status - Get EAP method status 148 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 149 * @priv: Pointer to private EAP method data from eap_method::init() 150 * @buf: Buffer for status information 151 * @buflen: Maximum buffer length 152 * @verbose: Whether to include verbose status information 153 * Returns: Number of bytes written to buf 154 * 155 * Query EAP method for status information. This function fills in a 156 * text area with current status information from the EAP method. If 157 * the buffer (buf) is not large enough, status information will be 158 * truncated to fit the buffer. 159 */ 160 int (*get_status)(struct eap_sm *sm, void *priv, char *buf, 161 size_t buflen, int verbose); 162 163 /** 164 * has_reauth_data - Whether method is ready for fast reauthentication 165 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 166 * @priv: Pointer to private EAP method data from eap_method::init() 167 * Returns: %TRUE or %FALSE based on whether fast reauthentication is 168 * possible 169 * 170 * This function is an optional handler that only EAP methods 171 * supporting fast re-authentication need to implement. 172 */ 173 Boolean (*has_reauth_data)(struct eap_sm *sm, void *priv); 174 175 /** 176 * deinit_for_reauth - Release data that is not needed for fast re-auth 177 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 178 * @priv: Pointer to private EAP method data from eap_method::init() 179 * 180 * This function is an optional handler that only EAP methods 181 * supporting fast re-authentication need to implement. This is called 182 * when authentication has been completed and EAP state machine is 183 * requesting that enough state information is maintained for fast 184 * re-authentication 185 */ 186 void (*deinit_for_reauth)(struct eap_sm *sm, void *priv); 187 188 /** 189 * init_for_reauth - Prepare for start of fast re-authentication 190 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 191 * @priv: Pointer to private EAP method data from eap_method::init() 192 * 193 * This function is an optional handler that only EAP methods 194 * supporting fast re-authentication need to implement. This is called 195 * when EAP authentication is started and EAP state machine is 196 * requesting fast re-authentication to be used. 197 */ 198 void * (*init_for_reauth)(struct eap_sm *sm, void *priv); 199 200 /** 201 * get_identity - Get method specific identity for re-authentication 202 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 203 * @priv: Pointer to private EAP method data from eap_method::init() 204 * @len: Length of the returned identity 205 * Returns: Pointer to the method specific identity or %NULL if default 206 * identity is to be used 207 * 208 * This function is an optional handler that only EAP methods 209 * that use method specific identity need to implement. 210 */ 211 const u8 * (*get_identity)(struct eap_sm *sm, void *priv, size_t *len); 212 213 /** 214 * free - Free EAP method data 215 * @method: Pointer to the method data registered with 216 * eap_peer_method_register(). 217 * 218 * This function will be called when the EAP method is being 219 * unregistered. If the EAP method allocated resources during 220 * registration (e.g., allocated struct eap_method), they should be 221 * freed in this function. No other method functions will be called 222 * after this call. If this function is not defined (i.e., function 223 * pointer is %NULL), a default handler is used to release the method 224 * data with free(method). This is suitable for most cases. 225 */ 226 void (*free)(struct eap_method *method); 227 228 #define EAP_PEER_METHOD_INTERFACE_VERSION 1 229 /** 230 * version - Version of the EAP peer method interface 231 * 232 * The EAP peer method implementation should set this variable to 233 * EAP_PEER_METHOD_INTERFACE_VERSION. This is used to verify that the 234 * EAP method is using supported API version when using dynamically 235 * loadable EAP methods. 236 */ 237 int version; 238 239 /** 240 * next - Pointer to the next EAP method 241 * 242 * This variable is used internally in the EAP method registration code 243 * to create a linked list of registered EAP methods. 244 */ 245 struct eap_method *next; 246 247 #ifdef CONFIG_DYNAMIC_EAP_METHODS 248 /** 249 * dl_handle - Handle for the dynamic library 250 * 251 * This variable is used internally in the EAP method registration code 252 * to store a handle for the dynamic library. If the method is linked 253 * in statically, this is %NULL. 254 */ 255 void *dl_handle; 256 #endif /* CONFIG_DYNAMIC_EAP_METHODS */ 257 258 /** 259 * get_emsk - Get EAP method specific keying extended material (EMSK) 260 * @sm: Pointer to EAP state machine allocated with eap_peer_sm_init() 261 * @priv: Pointer to private EAP method data from eap_method::init() 262 * @len: Pointer to a variable to store EMSK length 263 * Returns: EMSK or %NULL if not available 264 * 265 * This function can be used to get the extended keying material from 266 * the EAP method. The key may already be stored in the method-specific 267 * private data or this function may derive the key. 268 */ 269 u8 * (*get_emsk)(struct eap_sm *sm, void *priv, size_t *len); 270 }; 271 272 273 /** 274 * struct eap_sm - EAP state machine data 275 */ 276 struct eap_sm { 277 enum { 278 EAP_INITIALIZE, EAP_DISABLED, EAP_IDLE, EAP_RECEIVED, 279 EAP_GET_METHOD, EAP_METHOD, EAP_SEND_RESPONSE, EAP_DISCARD, 280 EAP_IDENTITY, EAP_NOTIFICATION, EAP_RETRANSMIT, EAP_SUCCESS, 281 EAP_FAILURE 282 } EAP_state; 283 /* Long-term local variables */ 284 EapType selectedMethod; 285 EapMethodState methodState; 286 int lastId; 287 struct wpabuf *lastRespData; 288 EapDecision decision; 289 /* Short-term local variables */ 290 Boolean rxReq; 291 Boolean rxSuccess; 292 Boolean rxFailure; 293 int reqId; 294 EapType reqMethod; 295 int reqVendor; 296 u32 reqVendorMethod; 297 Boolean ignore; 298 /* Constants */ 299 int ClientTimeout; 300 301 /* Miscellaneous variables */ 302 Boolean allowNotifications; /* peer state machine <-> methods */ 303 struct wpabuf *eapRespData; /* peer to lower layer */ 304 Boolean eapKeyAvailable; /* peer to lower layer */ 305 u8 *eapKeyData; /* peer to lower layer */ 306 size_t eapKeyDataLen; /* peer to lower layer */ 307 const struct eap_method *m; /* selected EAP method */ 308 /* not defined in RFC 4137 */ 309 Boolean changed; 310 void *eapol_ctx; 311 struct eapol_callbacks *eapol_cb; 312 void *eap_method_priv; 313 int init_phase2; 314 int fast_reauth; 315 316 Boolean rxResp /* LEAP only */; 317 Boolean leap_done; 318 Boolean peap_done; 319 u8 req_md5[16]; /* MD5() of the current EAP packet */ 320 u8 last_md5[16]; /* MD5() of the previously received EAP packet; used 321 * in duplicate request detection. */ 322 323 void *msg_ctx; 324 void *scard_ctx; 325 void *ssl_ctx; 326 327 unsigned int workaround; 328 329 /* Optional challenges generated in Phase 1 (EAP-FAST) */ 330 u8 *peer_challenge, *auth_challenge; 331 332 int num_rounds; 333 int force_disabled; 334 335 struct wps_context *wps; 336 337 int prev_failure; 338 }; 339 340 const u8 * eap_get_config_identity(struct eap_sm *sm, size_t *len); 341 const u8 * eap_get_config_password(struct eap_sm *sm, size_t *len); 342 const u8 * eap_get_config_password2(struct eap_sm *sm, size_t *len, int *hash); 343 const u8 * eap_get_config_new_password(struct eap_sm *sm, size_t *len); 344 const u8 * eap_get_config_otp(struct eap_sm *sm, size_t *len); 345 void eap_clear_config_otp(struct eap_sm *sm); 346 const char * eap_get_config_phase1(struct eap_sm *sm); 347 const char * eap_get_config_phase2(struct eap_sm *sm); 348 struct eap_peer_config * eap_get_config(struct eap_sm *sm); 349 void eap_set_config_blob(struct eap_sm *sm, struct wpa_config_blob *blob); 350 const struct wpa_config_blob * 351 eap_get_config_blob(struct eap_sm *sm, const char *name); 352 void eap_notify_pending(struct eap_sm *sm); 353 int eap_allowed_method(struct eap_sm *sm, int vendor, u32 method); 354 355 #endif /* EAP_I_H */ 356