• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 	unsigned int ext_cert_check:1;
370 	unsigned int waiting_ext_cert_check:1;
371 
372 	struct dl_list erp_keys; /* struct eap_erp_key */
373 };
374 
375 const u8 * eap_get_config_identity(struct eap_sm *sm, size_t *len);
376 const u8 * eap_get_config_password(struct eap_sm *sm, size_t *len);
377 const u8 * eap_get_config_password2(struct eap_sm *sm, size_t *len, int *hash);
378 const u8 * eap_get_config_new_password(struct eap_sm *sm, size_t *len);
379 const u8 * eap_get_config_otp(struct eap_sm *sm, size_t *len);
380 void eap_clear_config_otp(struct eap_sm *sm);
381 const char * eap_get_config_phase1(struct eap_sm *sm);
382 const char * eap_get_config_phase2(struct eap_sm *sm);
383 int eap_get_config_fragment_size(struct eap_sm *sm);
384 struct eap_peer_config * eap_get_config(struct eap_sm *sm);
385 void eap_set_config_blob(struct eap_sm *sm, struct wpa_config_blob *blob);
386 const struct wpa_config_blob *
387 eap_get_config_blob(struct eap_sm *sm, const char *name);
388 void eap_notify_pending(struct eap_sm *sm);
389 int eap_allowed_method(struct eap_sm *sm, int vendor, u32 method);
390 
391 #endif /* EAP_I_H */
392