1 /* 2 * EAP peer state machine functions (RFC 4137) 3 * Copyright (c) 2004-2012, 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_H 10 #define EAP_H 11 12 #include "common/defs.h" 13 #include "eap_common/eap_defs.h" 14 #include "eap_peer/eap_methods.h" 15 16 struct eap_sm; 17 struct wpa_config_blob; 18 struct wpabuf; 19 struct tls_cert_data; 20 21 struct eap_method_type { 22 int vendor; 23 u32 method; 24 }; 25 26 #ifdef IEEE8021X_EAPOL 27 28 /** 29 * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine 30 * 31 * These variables are used in the interface between EAP peer state machine and 32 * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 33 * expected to maintain these variables and register a callback functions for 34 * EAP state machine to get and set the variables. 35 */ 36 enum eapol_bool_var { 37 /** 38 * EAPOL_eapSuccess - EAP SUCCESS state reached 39 * 40 * EAP state machine reads and writes this value. 41 */ 42 EAPOL_eapSuccess, 43 44 /** 45 * EAPOL_eapRestart - Lower layer request to restart authentication 46 * 47 * Set to TRUE in lower layer, FALSE in EAP state machine. 48 */ 49 EAPOL_eapRestart, 50 51 /** 52 * EAPOL_eapFail - EAP FAILURE state reached 53 * 54 * EAP state machine writes this value. 55 */ 56 EAPOL_eapFail, 57 58 /** 59 * EAPOL_eapResp - Response to send 60 * 61 * Set to TRUE in EAP state machine, FALSE in lower layer. 62 */ 63 EAPOL_eapResp, 64 65 /** 66 * EAPOL_eapNoResp - Request has been process; no response to send 67 * 68 * Set to TRUE in EAP state machine, FALSE in lower layer. 69 */ 70 EAPOL_eapNoResp, 71 72 /** 73 * EAPOL_eapReq - EAP request available from lower layer 74 * 75 * Set to TRUE in lower layer, FALSE in EAP state machine. 76 */ 77 EAPOL_eapReq, 78 79 /** 80 * EAPOL_portEnabled - Lower layer is ready for communication 81 * 82 * EAP state machines reads this value. 83 */ 84 EAPOL_portEnabled, 85 86 /** 87 * EAPOL_altAccept - Alternate indication of success (RFC3748) 88 * 89 * EAP state machines reads this value. 90 */ 91 EAPOL_altAccept, 92 93 /** 94 * EAPOL_altReject - Alternate indication of failure (RFC3748) 95 * 96 * EAP state machines reads this value. 97 */ 98 EAPOL_altReject, 99 100 /** 101 * EAPOL_eapTriggerStart - EAP-based trigger to send EAPOL-Start 102 * 103 * EAP state machine writes this value. 104 */ 105 EAPOL_eapTriggerStart 106 }; 107 108 /** 109 * enum eapol_int_var - EAPOL integer state variables for EAP state machine 110 * 111 * These variables are used in the interface between EAP peer state machine and 112 * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 113 * expected to maintain these variables and register a callback functions for 114 * EAP state machine to get and set the variables. 115 */ 116 enum eapol_int_var { 117 /** 118 * EAPOL_idleWhile - Outside time for EAP peer timeout 119 * 120 * This integer variable is used to provide an outside timer that the 121 * external (to EAP state machine) code must decrement by one every 122 * second until the value reaches zero. This is used in the same way as 123 * EAPOL state machine timers. EAP state machine reads and writes this 124 * value. 125 */ 126 EAPOL_idleWhile 127 }; 128 129 /** 130 * struct eapol_callbacks - Callback functions from EAP to lower layer 131 * 132 * This structure defines the callback functions that EAP state machine 133 * requires from the lower layer (usually EAPOL state machine) for updating 134 * state variables and requesting information. eapol_ctx from 135 * eap_peer_sm_init() call will be used as the ctx parameter for these 136 * callback functions. 137 */ 138 struct eapol_callbacks { 139 /** 140 * get_config - Get pointer to the current network configuration 141 * @ctx: eapol_ctx from eap_peer_sm_init() call 142 */ 143 struct eap_peer_config * (*get_config)(void *ctx); 144 145 /** 146 * get_bool - Get a boolean EAPOL state variable 147 * @variable: EAPOL boolean variable to get 148 * Returns: Value of the EAPOL variable 149 */ 150 Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable); 151 152 /** 153 * set_bool - Set a boolean EAPOL state variable 154 * @ctx: eapol_ctx from eap_peer_sm_init() call 155 * @variable: EAPOL boolean variable to set 156 * @value: Value for the EAPOL variable 157 */ 158 void (*set_bool)(void *ctx, enum eapol_bool_var variable, 159 Boolean value); 160 161 /** 162 * get_int - Get an integer EAPOL state variable 163 * @ctx: eapol_ctx from eap_peer_sm_init() call 164 * @variable: EAPOL integer variable to get 165 * Returns: Value of the EAPOL variable 166 */ 167 unsigned int (*get_int)(void *ctx, enum eapol_int_var variable); 168 169 /** 170 * set_int - Set an integer EAPOL state variable 171 * @ctx: eapol_ctx from eap_peer_sm_init() call 172 * @variable: EAPOL integer variable to set 173 * @value: Value for the EAPOL variable 174 */ 175 void (*set_int)(void *ctx, enum eapol_int_var variable, 176 unsigned int value); 177 178 /** 179 * get_eapReqData - Get EAP-Request data 180 * @ctx: eapol_ctx from eap_peer_sm_init() call 181 * @len: Pointer to variable that will be set to eapReqDataLen 182 * Returns: Reference to eapReqData (EAP state machine will not free 183 * this) or %NULL if eapReqData not available. 184 */ 185 struct wpabuf * (*get_eapReqData)(void *ctx); 186 187 /** 188 * set_config_blob - Set named configuration blob 189 * @ctx: eapol_ctx from eap_peer_sm_init() call 190 * @blob: New value for the blob 191 * 192 * Adds a new configuration blob or replaces the current value of an 193 * existing blob. 194 */ 195 void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob); 196 197 /** 198 * get_config_blob - Get a named configuration blob 199 * @ctx: eapol_ctx from eap_peer_sm_init() call 200 * @name: Name of the blob 201 * Returns: Pointer to blob data or %NULL if not found 202 */ 203 const struct wpa_config_blob * (*get_config_blob)(void *ctx, 204 const char *name); 205 206 /** 207 * notify_pending - Notify that a pending request can be retried 208 * @ctx: eapol_ctx from eap_peer_sm_init() call 209 * 210 * An EAP method can perform a pending operation (e.g., to get a 211 * response from an external process). Once the response is available, 212 * this callback function can be used to request EAPOL state machine to 213 * retry delivering the previously received (and still unanswered) EAP 214 * request to EAP state machine. 215 */ 216 void (*notify_pending)(void *ctx); 217 218 /** 219 * eap_param_needed - Notify that EAP parameter is needed 220 * @ctx: eapol_ctx from eap_peer_sm_init() call 221 * @field: Field indicator (e.g., WPA_CTRL_REQ_EAP_IDENTITY) 222 * @txt: User readable text describing the required parameter 223 */ 224 void (*eap_param_needed)(void *ctx, enum wpa_ctrl_req_type field, 225 const char *txt); 226 227 /** 228 * notify_cert - Notification of a peer certificate 229 * @ctx: eapol_ctx from eap_peer_sm_init() call 230 * @cert: Certificate information 231 * @cert_hash: SHA-256 hash of the certificate 232 */ 233 void (*notify_cert)(void *ctx, struct tls_cert_data *cert, 234 const char *cert_hash); 235 236 /** 237 * notify_status - Notification of the current EAP state 238 * @ctx: eapol_ctx from eap_peer_sm_init() call 239 * @status: Step in the process of EAP authentication 240 * @parameter: Step-specific parameter, e.g., EAP method name 241 */ 242 void (*notify_status)(void *ctx, const char *status, 243 const char *parameter); 244 245 /** 246 * notify_eap_error - Report EAP method error code 247 * @ctx: eapol_ctx from eap_peer_sm_init() call 248 * @error_code: Error code from the used EAP method 249 */ 250 void (*notify_eap_error)(void *ctx, int error_code); 251 252 #ifdef CONFIG_EAP_PROXY 253 /** 254 * eap_proxy_cb - Callback signifying any updates from eap_proxy 255 * @ctx: eapol_ctx from eap_peer_sm_init() call 256 */ 257 void (*eap_proxy_cb)(void *ctx); 258 259 /** 260 * eap_proxy_notify_sim_status - Notification of SIM status change 261 * @ctx: eapol_ctx from eap_peer_sm_init() call 262 * @sim_state: One of enum value from sim_state 263 */ 264 void (*eap_proxy_notify_sim_status)(void *ctx, 265 enum eap_proxy_sim_state sim_state); 266 267 /** 268 * get_imsi - Get the IMSI value from eap_proxy 269 * @ctx: eapol_ctx from eap_peer_sm_init() call 270 * @sim_num: SIM/USIM number to get the IMSI value for 271 * @imsi: Buffer for IMSI value 272 * @len: Buffer for returning IMSI length in octets 273 * Returns: MNC length (2 or 3) or -1 on error 274 */ 275 int (*get_imsi)(void *ctx, int sim_num, char *imsi, size_t *len); 276 #endif /* CONFIG_EAP_PROXY */ 277 278 /** 279 * set_anon_id - Set or add anonymous identity 280 * @ctx: eapol_ctx from eap_peer_sm_init() call 281 * @id: Anonymous identity (e.g., EAP-SIM pseudonym) or %NULL to clear 282 * @len: Length of anonymous identity in octets 283 */ 284 void (*set_anon_id)(void *ctx, const u8 *id, size_t len); 285 }; 286 287 /** 288 * struct eap_config - Configuration for EAP state machine 289 */ 290 struct eap_config { 291 /** 292 * opensc_engine_path - OpenSC engine for OpenSSL engine support 293 * 294 * Usually, path to engine_opensc.so. 295 */ 296 const char *opensc_engine_path; 297 /** 298 * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support 299 * 300 * Usually, path to engine_pkcs11.so. 301 */ 302 const char *pkcs11_engine_path; 303 /** 304 * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine 305 * 306 * Usually, path to opensc-pkcs11.so. 307 */ 308 const char *pkcs11_module_path; 309 /** 310 * openssl_ciphers - OpenSSL cipher string 311 * 312 * This is an OpenSSL specific configuration option for configuring the 313 * default ciphers. If not set, "DEFAULT:!EXP:!LOW" is used as the 314 * default. 315 */ 316 const char *openssl_ciphers; 317 /** 318 * wps - WPS context data 319 * 320 * This is only used by EAP-WSC and can be left %NULL if not available. 321 */ 322 struct wps_context *wps; 323 324 /** 325 * cert_in_cb - Include server certificates in callback 326 */ 327 int cert_in_cb; 328 }; 329 330 struct eap_sm * eap_peer_sm_init(void *eapol_ctx, 331 const struct eapol_callbacks *eapol_cb, 332 void *msg_ctx, struct eap_config *conf); 333 void eap_peer_sm_deinit(struct eap_sm *sm); 334 int eap_peer_sm_step(struct eap_sm *sm); 335 void eap_sm_abort(struct eap_sm *sm); 336 int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen, 337 int verbose); 338 const char * eap_sm_get_method_name(struct eap_sm *sm); 339 struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted); 340 void eap_sm_request_identity(struct eap_sm *sm); 341 void eap_sm_request_password(struct eap_sm *sm); 342 void eap_sm_request_new_password(struct eap_sm *sm); 343 void eap_sm_request_pin(struct eap_sm *sm); 344 void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len); 345 void eap_sm_request_passphrase(struct eap_sm *sm); 346 void eap_sm_request_sim(struct eap_sm *sm, const char *req); 347 void eap_sm_notify_ctrl_attached(struct eap_sm *sm); 348 u32 eap_get_phase2_type(const char *name, int *vendor); 349 struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config, 350 size_t *count); 351 void eap_set_fast_reauth(struct eap_sm *sm, int enabled); 352 void eap_set_workaround(struct eap_sm *sm, unsigned int workaround); 353 void eap_set_force_disabled(struct eap_sm *sm, int disabled); 354 void eap_set_external_sim(struct eap_sm *sm, int external_sim); 355 int eap_key_available(struct eap_sm *sm); 356 void eap_notify_success(struct eap_sm *sm); 357 void eap_notify_lower_layer_success(struct eap_sm *sm); 358 const u8 * eap_get_eapSessionId(struct eap_sm *sm, size_t *len); 359 const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len); 360 struct wpabuf * eap_get_eapRespData(struct eap_sm *sm); 361 void eap_register_scard_ctx(struct eap_sm *sm, void *ctx); 362 void eap_invalidate_cached_session(struct eap_sm *sm); 363 364 int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf); 365 int eap_is_wps_pin_enrollee(struct eap_peer_config *conf); 366 367 struct ext_password_data; 368 void eap_sm_set_ext_pw_ctx(struct eap_sm *sm, struct ext_password_data *ext); 369 void eap_set_anon_id(struct eap_sm *sm, const u8 *id, size_t len); 370 int eap_peer_was_failure_expected(struct eap_sm *sm); 371 void eap_peer_erp_free_keys(struct eap_sm *sm); 372 struct wpabuf * eap_peer_build_erp_reauth_start(struct eap_sm *sm, u8 eap_id); 373 void eap_peer_finish(struct eap_sm *sm, const struct eap_hdr *hdr, size_t len); 374 int eap_peer_get_erp_info(struct eap_sm *sm, struct eap_peer_config *config, 375 const u8 **username, size_t *username_len, 376 const u8 **realm, size_t *realm_len, u16 *erp_seq_num, 377 const u8 **rrk, size_t *rrk_len); 378 int eap_peer_update_erp_next_seq_num(struct eap_sm *sm, u16 seq_num); 379 void eap_peer_erp_init(struct eap_sm *sm, u8 *ext_session_id, 380 size_t ext_session_id_len, u8 *ext_emsk, 381 size_t ext_emsk_len); 382 383 #endif /* IEEE8021X_EAPOL */ 384 385 #endif /* EAP_H */ 386