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