• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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 #ifdef CONFIG_EAP_PROXY
250 	/**
251 	 * eap_proxy_cb - Callback signifying any updates from eap_proxy
252 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
253 	 */
254 	void (*eap_proxy_cb)(void *ctx);
255 
256 	/**
257 	 * eap_proxy_notify_sim_status - Notification of SIM status change
258 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
259 	 * @sim_state: One of enum value from sim_state
260 	 */
261 	void (*eap_proxy_notify_sim_status)(void *ctx,
262 					    enum eap_proxy_sim_state sim_state);
263 #endif /* CONFIG_EAP_PROXY */
264 
265 	/**
266 	 * set_anon_id - Set or add anonymous identity
267 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
268 	 * @id: Anonymous identity (e.g., EAP-SIM pseudonym) or %NULL to clear
269 	 * @len: Length of anonymous identity in octets
270 	 */
271 	void (*set_anon_id)(void *ctx, const u8 *id, size_t len);
272 };
273 
274 /**
275  * struct eap_config - Configuration for EAP state machine
276  */
277 struct eap_config {
278 	/**
279 	 * opensc_engine_path - OpenSC engine for OpenSSL engine support
280 	 *
281 	 * Usually, path to engine_opensc.so.
282 	 */
283 	const char *opensc_engine_path;
284 	/**
285 	 * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support
286 	 *
287 	 * Usually, path to engine_pkcs11.so.
288 	 */
289 	const char *pkcs11_engine_path;
290 	/**
291 	 * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine
292 	 *
293 	 * Usually, path to opensc-pkcs11.so.
294 	 */
295 	const char *pkcs11_module_path;
296 	/**
297 	 * openssl_ciphers - OpenSSL cipher string
298 	 *
299 	 * This is an OpenSSL specific configuration option for configuring the
300 	 * default ciphers. If not set, "DEFAULT:!EXP:!LOW" is used as the
301 	 * default.
302 	 */
303 	const char *openssl_ciphers;
304 	/**
305 	 * wps - WPS context data
306 	 *
307 	 * This is only used by EAP-WSC and can be left %NULL if not available.
308 	 */
309 	struct wps_context *wps;
310 
311 	/**
312 	 * cert_in_cb - Include server certificates in callback
313 	 */
314 	int cert_in_cb;
315 };
316 
317 struct eap_sm * eap_peer_sm_init(void *eapol_ctx,
318 				 const struct eapol_callbacks *eapol_cb,
319 				 void *msg_ctx, struct eap_config *conf);
320 void eap_peer_sm_deinit(struct eap_sm *sm);
321 int eap_peer_sm_step(struct eap_sm *sm);
322 void eap_sm_abort(struct eap_sm *sm);
323 int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen,
324 		      int verbose);
325 const char * eap_sm_get_method_name(struct eap_sm *sm);
326 struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted);
327 void eap_sm_request_identity(struct eap_sm *sm);
328 void eap_sm_request_password(struct eap_sm *sm);
329 void eap_sm_request_new_password(struct eap_sm *sm);
330 void eap_sm_request_pin(struct eap_sm *sm);
331 void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len);
332 void eap_sm_request_passphrase(struct eap_sm *sm);
333 void eap_sm_request_sim(struct eap_sm *sm, const char *req);
334 void eap_sm_notify_ctrl_attached(struct eap_sm *sm);
335 u32 eap_get_phase2_type(const char *name, int *vendor);
336 struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config,
337 					      size_t *count);
338 void eap_set_fast_reauth(struct eap_sm *sm, int enabled);
339 void eap_set_workaround(struct eap_sm *sm, unsigned int workaround);
340 void eap_set_force_disabled(struct eap_sm *sm, int disabled);
341 void eap_set_external_sim(struct eap_sm *sm, int external_sim);
342 int eap_key_available(struct eap_sm *sm);
343 void eap_notify_success(struct eap_sm *sm);
344 void eap_notify_lower_layer_success(struct eap_sm *sm);
345 const u8 * eap_get_eapSessionId(struct eap_sm *sm, size_t *len);
346 const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len);
347 struct wpabuf * eap_get_eapRespData(struct eap_sm *sm);
348 void eap_register_scard_ctx(struct eap_sm *sm, void *ctx);
349 void eap_invalidate_cached_session(struct eap_sm *sm);
350 
351 int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf);
352 int eap_is_wps_pin_enrollee(struct eap_peer_config *conf);
353 
354 struct ext_password_data;
355 void eap_sm_set_ext_pw_ctx(struct eap_sm *sm, struct ext_password_data *ext);
356 void eap_set_anon_id(struct eap_sm *sm, const u8 *id, size_t len);
357 int eap_peer_was_failure_expected(struct eap_sm *sm);
358 void eap_peer_erp_free_keys(struct eap_sm *sm);
359 struct wpabuf * eap_peer_build_erp_reauth_start(struct eap_sm *sm, u8 eap_id);
360 void eap_peer_finish(struct eap_sm *sm, const struct eap_hdr *hdr, size_t len);
361 
362 #endif /* IEEE8021X_EAPOL */
363 
364 #endif /* EAP_H */
365