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