xref: /freebsd/contrib/wpa/src/eap_peer/eap.h (revision 39beb93c3f8bdbf72a61fda42300b5ebed7390c8)
1 /*
2  * EAP peer state machine functions (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_H
16 #define EAP_H
17 
18 #include "defs.h"
19 #include "eap_common/eap_defs.h"
20 #include "eap_peer/eap_methods.h"
21 
22 struct eap_sm;
23 struct wpa_config_blob;
24 struct wpabuf;
25 
26 struct eap_method_type {
27 	int vendor;
28 	u32 method;
29 };
30 
31 #ifdef IEEE8021X_EAPOL
32 
33 /**
34  * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine
35  *
36  * These variables are used in the interface between EAP peer state machine and
37  * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
38  * expected to maintain these variables and register a callback functions for
39  * EAP state machine to get and set the variables.
40  */
41 enum eapol_bool_var {
42 	/**
43 	 * EAPOL_eapSuccess - EAP SUCCESS state reached
44 	 *
45 	 * EAP state machine reads and writes this value.
46 	 */
47 	EAPOL_eapSuccess,
48 
49 	/**
50 	 * EAPOL_eapRestart - Lower layer request to restart authentication
51 	 *
52 	 * Set to TRUE in lower layer, FALSE in EAP state machine.
53 	 */
54 	EAPOL_eapRestart,
55 
56 	/**
57 	 * EAPOL_eapFail - EAP FAILURE state reached
58 	 *
59 	 * EAP state machine writes this value.
60 	 */
61 	EAPOL_eapFail,
62 
63 	/**
64 	 * EAPOL_eapResp - Response to send
65 	 *
66 	 * Set to TRUE in EAP state machine, FALSE in lower layer.
67 	 */
68 	EAPOL_eapResp,
69 
70 	/**
71 	 * EAPOL_eapNoResp - Request has been process; no response to send
72 	 *
73 	 * Set to TRUE in EAP state machine, FALSE in lower layer.
74 	 */
75 	EAPOL_eapNoResp,
76 
77 	/**
78 	 * EAPOL_eapReq - EAP request available from lower layer
79 	 *
80 	 * Set to TRUE in lower layer, FALSE in EAP state machine.
81 	 */
82 	EAPOL_eapReq,
83 
84 	/**
85 	 * EAPOL_portEnabled - Lower layer is ready for communication
86 	 *
87 	 * EAP state machines reads this value.
88 	 */
89 	EAPOL_portEnabled,
90 
91 	/**
92 	 * EAPOL_altAccept - Alternate indication of success (RFC3748)
93 	 *
94 	 * EAP state machines reads this value.
95 	 */
96 	EAPOL_altAccept,
97 
98 	/**
99 	 * EAPOL_altReject - Alternate indication of failure (RFC3748)
100 	 *
101 	 * EAP state machines reads this value.
102 	 */
103 	EAPOL_altReject
104 };
105 
106 /**
107  * enum eapol_int_var - EAPOL integer state variables for EAP state machine
108  *
109  * These variables are used in the interface between EAP peer state machine and
110  * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
111  * expected to maintain these variables and register a callback functions for
112  * EAP state machine to get and set the variables.
113  */
114 enum eapol_int_var {
115 	/**
116 	 * EAPOL_idleWhile - Outside time for EAP peer timeout
117 	 *
118 	 * This integer variable is used to provide an outside timer that the
119 	 * external (to EAP state machine) code must decrement by one every
120 	 * second until the value reaches zero. This is used in the same way as
121 	 * EAPOL state machine timers. EAP state machine reads and writes this
122 	 * value.
123 	 */
124 	EAPOL_idleWhile
125 };
126 
127 /**
128  * struct eapol_callbacks - Callback functions from EAP to lower layer
129  *
130  * This structure defines the callback functions that EAP state machine
131  * requires from the lower layer (usually EAPOL state machine) for updating
132  * state variables and requesting information. eapol_ctx from
133  * eap_peer_sm_init() call will be used as the ctx parameter for these
134  * callback functions.
135  */
136 struct eapol_callbacks {
137 	/**
138 	 * get_config - Get pointer to the current network configuration
139 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
140 	 */
141 	struct eap_peer_config * (*get_config)(void *ctx);
142 
143 	/**
144 	 * get_bool - Get a boolean EAPOL state variable
145 	 * @variable: EAPOL boolean variable to get
146 	 * Returns: Value of the EAPOL variable
147 	 */
148 	Boolean (*get_bool)(void *ctx, enum eapol_bool_var variable);
149 
150 	/**
151 	 * set_bool - Set a boolean EAPOL state variable
152 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
153 	 * @variable: EAPOL boolean variable to set
154 	 * @value: Value for the EAPOL variable
155 	 */
156 	void (*set_bool)(void *ctx, enum eapol_bool_var variable,
157 			 Boolean value);
158 
159 	/**
160 	 * get_int - Get an integer EAPOL state variable
161 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
162 	 * @variable: EAPOL integer variable to get
163 	 * Returns: Value of the EAPOL variable
164 	 */
165 	unsigned int (*get_int)(void *ctx, enum eapol_int_var variable);
166 
167 	/**
168 	 * set_int - Set an integer EAPOL state variable
169 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
170 	 * @variable: EAPOL integer variable to set
171 	 * @value: Value for the EAPOL variable
172 	 */
173 	void (*set_int)(void *ctx, enum eapol_int_var variable,
174 			unsigned int value);
175 
176 	/**
177 	 * get_eapReqData - Get EAP-Request data
178 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
179 	 * @len: Pointer to variable that will be set to eapReqDataLen
180 	 * Returns: Reference to eapReqData (EAP state machine will not free
181 	 * this) or %NULL if eapReqData not available.
182 	 */
183 	struct wpabuf * (*get_eapReqData)(void *ctx);
184 
185 	/**
186 	 * set_config_blob - Set named configuration blob
187 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
188 	 * @blob: New value for the blob
189 	 *
190 	 * Adds a new configuration blob or replaces the current value of an
191 	 * existing blob.
192 	 */
193 	void (*set_config_blob)(void *ctx, struct wpa_config_blob *blob);
194 
195 	/**
196 	 * get_config_blob - Get a named configuration blob
197 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
198 	 * @name: Name of the blob
199 	 * Returns: Pointer to blob data or %NULL if not found
200 	 */
201 	const struct wpa_config_blob * (*get_config_blob)(void *ctx,
202 							  const char *name);
203 
204 	/**
205 	 * notify_pending - Notify that a pending request can be retried
206 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
207 	 *
208 	 * An EAP method can perform a pending operation (e.g., to get a
209 	 * response from an external process). Once the response is available,
210 	 * this callback function can be used to request EAPOL state machine to
211 	 * retry delivering the previously received (and still unanswered) EAP
212 	 * request to EAP state machine.
213 	 */
214 	void (*notify_pending)(void *ctx);
215 
216 	/**
217 	 * eap_param_needed - Notify that EAP parameter is needed
218 	 * @ctx: eapol_ctx from eap_peer_sm_init() call
219 	 * @field: Field name (e.g., "IDENTITY")
220 	 * @txt: User readable text describing the required parameter
221 	 */
222 	void (*eap_param_needed)(void *ctx, const char *field,
223 				 const char *txt);
224 };
225 
226 /**
227  * struct eap_config - Configuration for EAP state machine
228  */
229 struct eap_config {
230 	/**
231 	 * opensc_engine_path - OpenSC engine for OpenSSL engine support
232 	 *
233 	 * Usually, path to engine_opensc.so.
234 	 */
235 	const char *opensc_engine_path;
236 	/**
237 	 * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support
238 	 *
239 	 * Usually, path to engine_pkcs11.so.
240 	 */
241 	const char *pkcs11_engine_path;
242 	/**
243 	 * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine
244 	 *
245 	 * Usually, path to opensc-pkcs11.so.
246 	 */
247 	const char *pkcs11_module_path;
248 	/**
249 	 * wps - WPS context data
250 	 *
251 	 * This is only used by EAP-WSC and can be left %NULL if not available.
252 	 */
253 	struct wps_context *wps;
254 };
255 
256 struct eap_sm * eap_peer_sm_init(void *eapol_ctx,
257 				 struct eapol_callbacks *eapol_cb,
258 				 void *msg_ctx, struct eap_config *conf);
259 void eap_peer_sm_deinit(struct eap_sm *sm);
260 int eap_peer_sm_step(struct eap_sm *sm);
261 void eap_sm_abort(struct eap_sm *sm);
262 int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen,
263 		      int verbose);
264 struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted);
265 void eap_sm_request_identity(struct eap_sm *sm);
266 void eap_sm_request_password(struct eap_sm *sm);
267 void eap_sm_request_new_password(struct eap_sm *sm);
268 void eap_sm_request_pin(struct eap_sm *sm);
269 void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len);
270 void eap_sm_request_passphrase(struct eap_sm *sm);
271 void eap_sm_notify_ctrl_attached(struct eap_sm *sm);
272 u32 eap_get_phase2_type(const char *name, int *vendor);
273 struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config,
274 					      size_t *count);
275 void eap_set_fast_reauth(struct eap_sm *sm, int enabled);
276 void eap_set_workaround(struct eap_sm *sm, unsigned int workaround);
277 void eap_set_force_disabled(struct eap_sm *sm, int disabled);
278 int eap_key_available(struct eap_sm *sm);
279 void eap_notify_success(struct eap_sm *sm);
280 void eap_notify_lower_layer_success(struct eap_sm *sm);
281 const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len);
282 struct wpabuf * eap_get_eapRespData(struct eap_sm *sm);
283 void eap_register_scard_ctx(struct eap_sm *sm, void *ctx);
284 void eap_invalidate_cached_session(struct eap_sm *sm);
285 
286 int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf);
287 int eap_is_wps_pin_enrollee(struct eap_peer_config *conf);
288 
289 #endif /* IEEE8021X_EAPOL */
290 
291 #endif /* EAP_H */
292