blob: b98e87815ad8903115aada41f5098272fffc39d2 [file] [log] [blame]
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -07001/*
2 * EAP peer state machine functions (RFC 4137)
Dmitry Shmidt4530cfd2012-09-09 15:20:40 -07003 * Copyright (c) 2004-2012, Jouni Malinen <j@w1.fi>
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -07004 *
Dmitry Shmidtc5ec7f52012-03-06 16:33:24 -08005 * This software may be distributed under the terms of the BSD license.
6 * See README for more details.
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -07007 */
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;
Hai Shalom81f62d82019-07-22 12:10:00 -070019struct tls_cert_data;
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -070020
21struct eap_method_type {
22 int vendor;
23 u32 method;
24};
25
26#ifdef IEEE8021X_EAPOL
27
28/**
29 * enum eapol_bool_var - EAPOL boolean state variables for EAP state machine
30 *
31 * These variables are used in the interface between EAP peer state machine and
32 * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
33 * expected to maintain these variables and register a callback functions for
34 * EAP state machine to get and set the variables.
35 */
36enum eapol_bool_var {
37 /**
38 * EAPOL_eapSuccess - EAP SUCCESS state reached
39 *
40 * EAP state machine reads and writes this value.
41 */
42 EAPOL_eapSuccess,
43
44 /**
45 * EAPOL_eapRestart - Lower layer request to restart authentication
46 *
Hai Shalome21d4e82020-04-29 16:34:06 -070047 * Set to true in lower layer, false in EAP state machine.
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -070048 */
49 EAPOL_eapRestart,
50
51 /**
52 * EAPOL_eapFail - EAP FAILURE state reached
53 *
54 * EAP state machine writes this value.
55 */
56 EAPOL_eapFail,
57
58 /**
59 * EAPOL_eapResp - Response to send
60 *
Hai Shalome21d4e82020-04-29 16:34:06 -070061 * Set to true in EAP state machine, false in lower layer.
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -070062 */
63 EAPOL_eapResp,
64
65 /**
66 * EAPOL_eapNoResp - Request has been process; no response to send
67 *
Hai Shalome21d4e82020-04-29 16:34:06 -070068 * Set to true in EAP state machine, false in lower layer.
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -070069 */
70 EAPOL_eapNoResp,
71
72 /**
73 * EAPOL_eapReq - EAP request available from lower layer
74 *
Hai Shalome21d4e82020-04-29 16:34:06 -070075 * Set to true in lower layer, false in EAP state machine.
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -070076 */
77 EAPOL_eapReq,
78
79 /**
80 * EAPOL_portEnabled - Lower layer is ready for communication
81 *
82 * EAP state machines reads this value.
83 */
84 EAPOL_portEnabled,
85
86 /**
87 * EAPOL_altAccept - Alternate indication of success (RFC3748)
88 *
89 * EAP state machines reads this value.
90 */
91 EAPOL_altAccept,
92
93 /**
94 * EAPOL_altReject - Alternate indication of failure (RFC3748)
95 *
96 * EAP state machines reads this value.
97 */
Dmitry Shmidt6c0da2b2015-01-05 13:08:17 -080098 EAPOL_altReject,
99
100 /**
101 * EAPOL_eapTriggerStart - EAP-based trigger to send EAPOL-Start
102 *
103 * EAP state machine writes this value.
104 */
105 EAPOL_eapTriggerStart
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700106};
107
108/**
109 * enum eapol_int_var - EAPOL integer state variables for EAP state machine
110 *
111 * These variables are used in the interface between EAP peer state machine and
112 * lower layer. These are defined in RFC 4137, Sect. 4.1. Lower layer code is
113 * expected to maintain these variables and register a callback functions for
114 * EAP state machine to get and set the variables.
115 */
116enum eapol_int_var {
117 /**
118 * EAPOL_idleWhile - Outside time for EAP peer timeout
119 *
120 * This integer variable is used to provide an outside timer that the
121 * external (to EAP state machine) code must decrement by one every
122 * second until the value reaches zero. This is used in the same way as
123 * EAPOL state machine timers. EAP state machine reads and writes this
124 * value.
125 */
126 EAPOL_idleWhile
127};
128
129/**
130 * struct eapol_callbacks - Callback functions from EAP to lower layer
131 *
132 * This structure defines the callback functions that EAP state machine
133 * requires from the lower layer (usually EAPOL state machine) for updating
134 * state variables and requesting information. eapol_ctx from
135 * eap_peer_sm_init() call will be used as the ctx parameter for these
136 * callback functions.
137 */
138struct eapol_callbacks {
139 /**
140 * get_config - Get pointer to the current network configuration
141 * @ctx: eapol_ctx from eap_peer_sm_init() call
142 */
143 struct eap_peer_config * (*get_config)(void *ctx);
144
145 /**
146 * get_bool - Get a boolean EAPOL state variable
147 * @variable: EAPOL boolean variable to get
148 * Returns: Value of the EAPOL variable
149 */
Hai Shalome21d4e82020-04-29 16:34:06 -0700150 bool (*get_bool)(void *ctx, enum eapol_bool_var variable);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700151
152 /**
153 * set_bool - Set a boolean EAPOL state variable
154 * @ctx: eapol_ctx from eap_peer_sm_init() call
155 * @variable: EAPOL boolean variable to set
156 * @value: Value for the EAPOL variable
157 */
Hai Shalome21d4e82020-04-29 16:34:06 -0700158 void (*set_bool)(void *ctx, enum eapol_bool_var variable, bool value);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700159
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
Dmitry Shmidt1f69aa52012-01-24 16:10:04 -0800220 * @field: Field indicator (e.g., WPA_CTRL_REQ_EAP_IDENTITY)
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700221 * @txt: User readable text describing the required parameter
222 */
Dmitry Shmidt1f69aa52012-01-24 16:10:04 -0800223 void (*eap_param_needed)(void *ctx, enum wpa_ctrl_req_type field,
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700224 const char *txt);
Dmitry Shmidtc55524a2011-07-07 11:18:38 -0700225
226 /**
227 * notify_cert - Notification of a peer certificate
228 * @ctx: eapol_ctx from eap_peer_sm_init() call
Hai Shalom81f62d82019-07-22 12:10:00 -0700229 * @cert: Certificate information
Dmitry Shmidtc55524a2011-07-07 11:18:38 -0700230 * @cert_hash: SHA-256 hash of the certificate
Dmitry Shmidtc55524a2011-07-07 11:18:38 -0700231 */
Hai Shalom81f62d82019-07-22 12:10:00 -0700232 void (*notify_cert)(void *ctx, struct tls_cert_data *cert,
233 const char *cert_hash);
Dmitry Shmidt04949592012-07-19 12:16:46 -0700234
235 /**
Steven Liu850c2e02022-11-28 17:26:39 +0000236 * notify_permanent_id_req_denied - Notify that the
237 * AT_PERMANENT_ID_REQ from the server was denied. This
238 * notification happens when the peer is in strict
239 * conservative mode.
240 * @ctx: eapol_ctx from eap_peer_sm_init() call
241 */
242 void (*notify_permanent_id_req_denied)(void* ctx);
243
244 /**
Dmitry Shmidt04949592012-07-19 12:16:46 -0700245 * notify_status - Notification of the current EAP state
246 * @ctx: eapol_ctx from eap_peer_sm_init() call
247 * @status: Step in the process of EAP authentication
248 * @parameter: Step-specific parameter, e.g., EAP method name
249 */
250 void (*notify_status)(void *ctx, const char *status,
251 const char *parameter);
Dmitry Shmidt4530cfd2012-09-09 15:20:40 -0700252
Ahmed ElArabawy9c86a7f2018-03-15 09:00:10 -0700253 /**
254 * notify_eap_error - Report EAP method error code
255 * @ctx: eapol_ctx from eap_peer_sm_init() call
256 * @error_code: Error code from the used EAP method
257 */
258 void (*notify_eap_error)(void *ctx, int error_code);
259
Dmitry Shmidt203eadb2015-03-05 14:16:04 -0800260#ifdef CONFIG_EAP_PROXY
261 /**
262 * eap_proxy_cb - Callback signifying any updates from eap_proxy
263 * @ctx: eapol_ctx from eap_peer_sm_init() call
264 */
265 void (*eap_proxy_cb)(void *ctx);
Dmitry Shmidt29333592017-01-09 12:27:11 -0800266
267 /**
268 * eap_proxy_notify_sim_status - Notification of SIM status change
269 * @ctx: eapol_ctx from eap_peer_sm_init() call
270 * @sim_state: One of enum value from sim_state
271 */
272 void (*eap_proxy_notify_sim_status)(void *ctx,
273 enum eap_proxy_sim_state sim_state);
Dmitry Shmidtd2986c22017-10-23 14:22:09 -0700274
275 /**
276 * get_imsi - Get the IMSI value from eap_proxy
277 * @ctx: eapol_ctx from eap_peer_sm_init() call
278 * @sim_num: SIM/USIM number to get the IMSI value for
279 * @imsi: Buffer for IMSI value
280 * @len: Buffer for returning IMSI length in octets
281 * Returns: MNC length (2 or 3) or -1 on error
282 */
283 int (*get_imsi)(void *ctx, int sim_num, char *imsi, size_t *len);
Dmitry Shmidt203eadb2015-03-05 14:16:04 -0800284#endif /* CONFIG_EAP_PROXY */
285
Dmitry Shmidt4530cfd2012-09-09 15:20:40 -0700286 /**
287 * set_anon_id - Set or add anonymous identity
288 * @ctx: eapol_ctx from eap_peer_sm_init() call
289 * @id: Anonymous identity (e.g., EAP-SIM pseudonym) or %NULL to clear
290 * @len: Length of anonymous identity in octets
291 */
292 void (*set_anon_id)(void *ctx, const u8 *id, size_t len);
Gabriel Biren3a2ec2c2022-03-07 17:59:41 +0000293
294 /**
295 * notify_eap_method_selected - Report that the EAP method was selected
296 * @ctx: eapol_ctx from eap_peer_sm_init() call
297 * @reason_string: Information to log about the event
298 */
299 void (*notify_eap_method_selected)(void *ctx, const char* reason_string);
300
301 /**
302 * notify_open_ssl_failure - Report that an OpenSSL failure occurred
303 * @ctx: eapol_ctx from eap_peer_sm_init() call
304 * @reason_string: Information to log about the event
305 */
306 void (*notify_open_ssl_failure)(void *ctx, const char* reason_string);
Gabriel Biren93398232022-12-15 19:18:28 +0000307
308 /**
309 * get_certificate - Retrieve a certificate from the certificate store
310 * @ctx: eapol_ctx from eap_peer_sm_init() call
311 * @alias: key into the certificate key-value store
312 * @value: pointer reference - pointer to the retrieved certificate will
313 * be stored here on success
314 * Returns: size of the retrieved certificate or -1 on error
315 */
316 ssize_t (*get_certificate)(void* ctx, const char* alias, uint8_t** value);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700317};
318
319/**
320 * struct eap_config - Configuration for EAP state machine
321 */
322struct eap_config {
323 /**
324 * opensc_engine_path - OpenSC engine for OpenSSL engine support
325 *
326 * Usually, path to engine_opensc.so.
327 */
328 const char *opensc_engine_path;
329 /**
330 * pkcs11_engine_path - PKCS#11 engine for OpenSSL engine support
331 *
332 * Usually, path to engine_pkcs11.so.
333 */
334 const char *pkcs11_engine_path;
335 /**
336 * pkcs11_module_path - OpenSC PKCS#11 module for OpenSSL engine
337 *
338 * Usually, path to opensc-pkcs11.so.
339 */
340 const char *pkcs11_module_path;
341 /**
Dmitry Shmidt6c0da2b2015-01-05 13:08:17 -0800342 * openssl_ciphers - OpenSSL cipher string
343 *
344 * This is an OpenSSL specific configuration option for configuring the
345 * default ciphers. If not set, "DEFAULT:!EXP:!LOW" is used as the
346 * default.
347 */
348 const char *openssl_ciphers;
349 /**
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700350 * wps - WPS context data
351 *
352 * This is only used by EAP-WSC and can be left %NULL if not available.
353 */
354 struct wps_context *wps;
Dmitry Shmidt1f69aa52012-01-24 16:10:04 -0800355
356 /**
357 * cert_in_cb - Include server certificates in callback
358 */
359 int cert_in_cb;
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700360};
361
362struct eap_sm * eap_peer_sm_init(void *eapol_ctx,
Dmitry Shmidt1d755d02015-04-28 10:34:29 -0700363 const struct eapol_callbacks *eapol_cb,
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700364 void *msg_ctx, struct eap_config *conf);
365void eap_peer_sm_deinit(struct eap_sm *sm);
366int eap_peer_sm_step(struct eap_sm *sm);
367void eap_sm_abort(struct eap_sm *sm);
368int eap_sm_get_status(struct eap_sm *sm, char *buf, size_t buflen,
369 int verbose);
370const char * eap_sm_get_method_name(struct eap_sm *sm);
371struct wpabuf * eap_sm_buildIdentity(struct eap_sm *sm, int id, int encrypted);
372void eap_sm_request_identity(struct eap_sm *sm);
373void eap_sm_request_password(struct eap_sm *sm);
374void eap_sm_request_new_password(struct eap_sm *sm);
375void eap_sm_request_pin(struct eap_sm *sm);
376void eap_sm_request_otp(struct eap_sm *sm, const char *msg, size_t msg_len);
377void eap_sm_request_passphrase(struct eap_sm *sm);
Dmitry Shmidt051af732013-10-22 13:52:46 -0700378void eap_sm_request_sim(struct eap_sm *sm, const char *req);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700379void eap_sm_notify_ctrl_attached(struct eap_sm *sm);
380u32 eap_get_phase2_type(const char *name, int *vendor);
381struct eap_method_type * eap_get_phase2_types(struct eap_peer_config *config,
382 size_t *count);
383void eap_set_fast_reauth(struct eap_sm *sm, int enabled);
384void eap_set_workaround(struct eap_sm *sm, unsigned int workaround);
385void eap_set_force_disabled(struct eap_sm *sm, int disabled);
Dmitry Shmidt051af732013-10-22 13:52:46 -0700386void eap_set_external_sim(struct eap_sm *sm, int external_sim);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700387int eap_key_available(struct eap_sm *sm);
Steven Liu850c2e02022-11-28 17:26:39 +0000388void eap_notify_permanent_id_req_denied(struct eap_sm *sm);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700389void eap_notify_success(struct eap_sm *sm);
390void eap_notify_lower_layer_success(struct eap_sm *sm);
Dmitry Shmidtf8623282013-02-20 14:34:59 -0800391const u8 * eap_get_eapSessionId(struct eap_sm *sm, size_t *len);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700392const u8 * eap_get_eapKeyData(struct eap_sm *sm, size_t *len);
393struct wpabuf * eap_get_eapRespData(struct eap_sm *sm);
Steven Liu9138d432022-11-23 22:29:05 +0000394int eap_get_config_strict_conservative_peer_mode(struct eap_sm *sm);
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700395void eap_register_scard_ctx(struct eap_sm *sm, void *ctx);
396void eap_invalidate_cached_session(struct eap_sm *sm);
397
398int eap_is_wps_pbc_enrollee(struct eap_peer_config *conf);
399int eap_is_wps_pin_enrollee(struct eap_peer_config *conf);
400
Dmitry Shmidt61d9df32012-08-29 16:22:06 -0700401struct ext_password_data;
402void eap_sm_set_ext_pw_ctx(struct eap_sm *sm, struct ext_password_data *ext);
Dmitry Shmidt4530cfd2012-09-09 15:20:40 -0700403void eap_set_anon_id(struct eap_sm *sm, const u8 *id, size_t len);
Dmitry Shmidt344abd32014-01-14 13:17:00 -0800404int eap_peer_was_failure_expected(struct eap_sm *sm);
Dmitry Shmidt6c0da2b2015-01-05 13:08:17 -0800405void eap_peer_erp_free_keys(struct eap_sm *sm);
Dmitry Shmidt9839ecd2016-11-07 11:05:47 -0800406struct wpabuf * eap_peer_build_erp_reauth_start(struct eap_sm *sm, u8 eap_id);
407void eap_peer_finish(struct eap_sm *sm, const struct eap_hdr *hdr, size_t len);
Dmitry Shmidtd2986c22017-10-23 14:22:09 -0700408int eap_peer_get_erp_info(struct eap_sm *sm, struct eap_peer_config *config,
409 const u8 **username, size_t *username_len,
410 const u8 **realm, size_t *realm_len, u16 *erp_seq_num,
411 const u8 **rrk, size_t *rrk_len);
412int eap_peer_update_erp_next_seq_num(struct eap_sm *sm, u16 seq_num);
413void eap_peer_erp_init(struct eap_sm *sm, u8 *ext_session_id,
414 size_t ext_session_id_len, u8 *ext_emsk,
415 size_t ext_emsk_len);
Dmitry Shmidt61d9df32012-08-29 16:22:06 -0700416
Dmitry Shmidt8d520ff2011-05-09 14:06:53 -0700417#endif /* IEEE8021X_EAPOL */
418
419#endif /* EAP_H */