1 /* 2 * EAP peer state machine functions (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_H 16 #define EAP_H 17 18 #include "common/defs.h" 19 #include "eap_common/eap_defs.h" 20 #include "eap_peer/eap_methods.h" 21 22 struct eap_sm; 23 struct wpa_config_blob; 24 struct wpabuf; 25 26 struct eap_method_type { 27 int vendor; 28 u32 method; 29 }; 30 31 #ifdef IEEE8021X_EAPOL 32 33 /** 34 * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine 35 * 36 * These variables are used in the interface between EAP peer state machine and 37 * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 38 * expected to maintain these variables and register a callback functions for 39 * EAP state machine to get and set the variables. 40 */ 41 enum eapol_bool_var { 42 /** 43 * EAPOL_eapSuccess - EAP SUCCESS state reached 44 * 45 * EAP state machine reads and writes this value. 46 */ 47 EAPOL_eapSuccess, 48 49 /** 50 * EAPOL_eapRestart - Lower layer request to restart authentication 51 * 52 * Set to TRUE in lower layer, FALSE in EAP state machine. 53 */ 54 EAPOL_eapRestart, 55 56 /** 57 * EAPOL_eapFail - EAP FAILURE state reached 58 * 59 * EAP state machine writes this value. 60 */ 61 EAPOL_eapFail, 62 63 /** 64 * EAPOL_eapResp - Response to send 65 * 66 * Set to TRUE in EAP state machine, FALSE in lower layer. 67 */ 68 EAPOL_eapResp, 69 70 /** 71 * EAPOL_eapNoResp - Request has been process; no response to send 72 * 73 * Set to TRUE in EAP state machine, FALSE in lower layer. 74 */ 75 EAPOL_eapNoResp, 76 77 /** 78 * EAPOL_eapReq - EAP request available from lower layer 79 * 80 * Set to TRUE in lower layer, FALSE in EAP state machine. 81 */ 82 EAPOL_eapReq, 83 84 /** 85 * EAPOL_portEnabled - Lower layer is ready for communication 86 * 87 * EAP state machines reads this value. 88 */ 89 EAPOL_portEnabled, 90 91 /** 92 * EAPOL_altAccept - Alternate indication of success (RFC3748) 93 * 94 * EAP state machines reads this value. 95 */ 96 EAPOL_altAccept, 97 98 /** 99 * EAPOL_altReject - Alternate indication of failure (RFC3748) 100 * 101 * EAP state machines reads this value. 102 */ 103 EAPOL_altReject 104 }; 105 106 /** 107 * enum eapol_int_var - EAPOL integer state variables for EAP state machine 108 * 109 * These variables are used in the interface between EAP peer state machine and 110 * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is 111 * expected to maintain these variables and register a callback functions for 112 * EAP state machine to get and set the variables. 113 */ 114 enum eapol_int_var { 115 /** 116 * EAPOL_idleWhile - Outside time for EAP peer timeout 117 * 118 * This integer variable is used to provide an outside timer that the 119 * external (to EAP state machine) code must decrement by one every 120 * second until the value reaches zero. This is used in the same way as 121 * EAPOL state machine timers. EAP state machine reads and writes this 122 * value. 123 */ 124 EAPOL_idleWhile 125 }; 126 127 /** 128 * struct eapol_callbacks - Callback functions from EAP to lower layer 129 * 130 * This structure defines the callback functions that EAP state machine 131 * requires from the lower layer (usually EAPOL state machine) for updating 132 * state variables and requesting information. eapol_ctx from 133 * eap_peer_sm_init() call will be used as the ctx parameter for these 134 * callback functions. 135 */ 136 struct eapol_callbacks { 137 /** 138 * get_config - Get pointer to the current network configuration 139 * @ctx: eapol_ctx from eap_peer_sm_init() call 140 */ 141 struct eap_peer_config * (*get_config)(void *ctx); 142 143 /** 144 * get_bool - Get a boolean EAPOL state variable 145 * @variable: EAPOL boolean variable to get 146 * Returns: Value of the EAPOL variable 147 */ 148 Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable); 149 150 /** 151 * set_bool - Set a boolean EAPOL state variable 152 * @ctx: eapol_ctx from eap_peer_sm_init() call 153 * @variable: EAPOL boolean variable to set 154 * @value: Value for the EAPOL variable 155 */ 156 void (*set_bool)(void *ctx, enum eapol_bool_var variable, 157 Boolean value); 158 159 /** 160 * get_int - Get an integer EAPOL state variable 161 * @ctx: eapol_ctx from eap_peer_sm_init() call 162 * @variable: EAPOL integer variable to get 163 * Returns: Value of the EAPOL variable 164 */ 165 unsigned int (*get_int)(void *ctx, enum eapol_int_var variable); 166 167 /** 168 * set_int - Set an integer EAPOL state variable 169 * @ctx: eapol_ctx from eap_peer_sm_init() call 170 * @variable: EAPOL integer variable to set 171 * @value: Value for the EAPOL variable 172 */ 173 void (*set_int)(void *ctx, enum eapol_int_var variable, 174 unsigned int value); 175 176 /** 177 * get_eapReqData - Get EAP-Request data 178 * @ctx: eapol_ctx from eap_peer_sm_init() call 179 * @len: Pointer to variable that will be set to eapReqDataLen 180 * Returns: Reference to eapReqData (EAP state machine will not free 181 * this) or %NULL if eapReqData not available. 182 */ 183 struct wpabuf * (*get_eapReqData)(void *ctx); 184 185 /** 186 * set_config_blob - Set named configuration blob 187 * @ctx: eapol_ctx from eap_peer_sm_init() call 188 * @blob: New value for the blob 189 * 190 * Adds a new configuration blob or replaces the current value of an 191 * existing blob. 192 */ 193 void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob); 194 195 /** 196 * get_config_blob - Get a named configuration blob 197 * @ctx: eapol_ctx from eap_peer_sm_init() call 198 * @name: Name of the blob 199 * Returns: Pointer to blob data or %NULL if not found 200 */ 201 const struct wpa_config_blob * (*get_config_blob)(void *ctx, 202 const char *name); 203 204 /** 205 * notify_pending - Notify that a pending request can be retried 206 * @ctx: eapol_ctx from eap_peer_sm_init() call 207 * 208 * An EAP method can perform a pending operation (e.g., to get a 209 * response from an external process). Once the response is available, 210 * this callback function can be used to request EAPOL state machine to 211 * retry delivering the previously received (and still unanswered) EAP 212 * request to EAP state machine. 213 */ 214 void (*notify_pending)(void *ctx); 215 216 /** 217 * eap_param_needed - Notify that EAP parameter is needed 218 * @ctx: eapol_ctx from eap_peer_sm_init() call 219 * @field: Field indicator (e.g., WPA_CTRL_REQ_EAP_IDENTITY) 220 * @txt: User readable text describing the required parameter 221 */ 222 void (*eap_param_needed)(void *ctx, enum wpa_ctrl_req_type field, 223 const char *txt); 224 225 /** 226 * notify_cert - Notification of a peer certificate 227 * @ctx: eapol_ctx from eap_peer_sm_init() call 228 * @depth: Depth in certificate chain (0 = server) 229 * @subject: Subject of the peer certificate 230 * @cert_hash: SHA-256 hash of the certificate 231 * @cert: Peer certificate 232 */ 233 void (*notify_cert)(void *ctx, int depth, const char *subject, 234 const char *cert_hash, const struct wpabuf *cert); 235 }; 236 237 /** 238 * struct eap_config - Configuration for EAP state machine 239 */ 240 struct eap_config { 241 /** 242 * opensc_engine_path - OpenSC engine for OpenSSL engine support 243 * 244 * Usually, path to engine_opensc.so. 245 */ 246 const char *opensc_engine_path; 247 /** 248 * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support 249 * 250 * Usually, path to engine_pkcs11.so. 251 */ 252 const char *pkcs11_engine_path; 253 /** 254 * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine 255 * 256 * Usually, path to opensc-pkcs11.so. 257 */ 258 const char *pkcs11_module_path; 259 /** 260 * wps - WPS context data 261 * 262 * This is only used by EAP-WSC and can be left %NULL if not available. 263 */ 264 struct wps_context *wps; 265 266 /** 267 * cert_in_cb - Include server certificates in callback 268 */ 269 int cert_in_cb; 270 }; 271 272 struct eap_sm * eap_peer_sm_init(void *eapol_ctx, 273 struct eapol_callbacks *eapol_cb, 274 void *msg_ctx, struct eap_config *conf); 275 void eap_peer_sm_deinit(struct eap_sm *sm); 276 int eap_peer_sm_step(struct eap_sm *sm); 277 void eap_sm_abort(struct eap_sm *sm); 278 int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen, 279 int verbose); 280 const char * eap_sm_get_method_name(struct eap_sm *sm); 281 struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted); 282 void eap_sm_request_identity(struct eap_sm *sm); 283 void eap_sm_request_password(struct eap_sm *sm); 284 void eap_sm_request_new_password(struct eap_sm *sm); 285 void eap_sm_request_pin(struct eap_sm *sm); 286 void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len); 287 void eap_sm_request_passphrase(struct eap_sm *sm); 288 void eap_sm_notify_ctrl_attached(struct eap_sm *sm); 289 u32 eap_get_phase2_type(const char *name, int *vendor); 290 struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config, 291 size_t *count); 292 void eap_set_fast_reauth(struct eap_sm *sm, int enabled); 293 void eap_set_workaround(struct eap_sm *sm, unsigned int workaround); 294 void eap_set_force_disabled(struct eap_sm *sm, int disabled); 295 int eap_key_available(struct eap_sm *sm); 296 void eap_notify_success(struct eap_sm *sm); 297 void eap_notify_lower_layer_success(struct eap_sm *sm); 298 const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len); 299 struct wpabuf * eap_get_eapRespData(struct eap_sm *sm); 300 void eap_register_scard_ctx(struct eap_sm *sm, void *ctx); 301 void eap_invalidate_cached_session(struct eap_sm *sm); 302 303 int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf); 304 int eap_is_wps_pin_enrollee(struct eap_peer_config *conf); 305 306 #endif /* IEEE8021X_EAPOL */ 307 308 #endif /* EAP_H */ 309