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