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