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