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