2 * WPA Supplicant / EAP state machines internal structures (RFC 4137)
3 * Copyright (c) 2004-2005, Jouni Malinen <jkmaline@cc.hut.fi>
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.
9 * Alternatively, this software may be distributed under the terms of BSD
12 * See README and COPYING for more details.
20 /* RFC 4137 - EAP Peer state machine */
23 DECISION_FAIL
, DECISION_COND_SUCC
, DECISION_UNCOND_SUCC
27 METHOD_NONE
, METHOD_INIT
, METHOD_CONT
, METHOD_MAY_CONT
, METHOD_DONE
31 * struct eap_method_ret - EAP return values from struct eap_method::process()
33 * These structure contains OUT variables for the interface between peer state
34 * machine and methods (RFC 4137, Sect. 4.2). eapRespData will be returned as
35 * the return value of struct eap_method::process() so it is not included in
38 struct eap_method_ret
{
40 * ignore - Whether method decided to drop the current packed (OUT)
45 * methodState - Method-specific state (IN/OUT)
47 EapMethodState methodState
;
50 * decision - Authentication decision (OUT)
55 * allowNotifications - Whether method allows notifications (OUT)
57 Boolean allowNotifications
;
62 * struct eap_method - EAP method interface
63 * This structure defines the EAP method interface. Each method will need to
64 * register its own EAP type, EAP name, and set of function pointers for method
65 * specific operations. This interface is based on section 4.4 of RFC 4137.
69 * method - EAP type number (EAP_TYPE_*)
74 * name - Name of the method (e.g., "TLS")
79 * init - Initialize an EAP method
80 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
81 * Returns: Pointer to allocated private data, or %NULL on failure
83 * This function is used to initialize the EAP method explicitly
84 * instead of using METHOD_INIT state as specific in RFC 4137. The
85 * method is expected to initialize it method-specific state and return
86 * a pointer that will be used as the priv argument to other calls.
88 void * (*init
)(struct eap_sm
*sm
);
91 * deinit - Deinitialize an EAP method
92 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
93 * @priv: Pointer to private EAP method data from eap_method::init()
95 * Deinitialize the EAP method and free any allocated private data.
97 void (*deinit
)(struct eap_sm
*sm
, void *priv
);
100 * process - Process an EAP request
101 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
102 * @priv: Pointer to private EAP method data from eap_method::init()
103 * @ret: Return values from EAP request validation and processing
104 * @reqData: EAP request to be processed (eapReqData)
105 * @reqDataLen: Length of the EAP request
106 * @respDataLen: Length of the returned EAP response
107 * Returns: Pointer to allocated EAP response packet (eapRespData)
109 * This function is a combination of m.check(), m.process(), and
110 * m.buildResp() procedures defined in section 4.4 of RFC 4137 In other
111 * words, this function validates the incoming request, processes it,
112 * and build a response packet. m.check() and m.process() return values
113 * are returned through struct eap_method_ret *ret variable. Caller is
114 * responsible for freeing the returned EAP response packet.
116 u8
* (*process
)(struct eap_sm
*sm
, void *priv
,
117 struct eap_method_ret
*ret
,
118 const u8
*reqData
, size_t reqDataLen
,
119 size_t *respDataLen
);
122 * isKeyAvailable - Find out whether EAP method has keying material
123 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
124 * @priv: Pointer to private EAP method data from eap_method::init()
125 * Returns: %TRUE if key material (eapKeyData) is available
127 Boolean (*isKeyAvailable
)(struct eap_sm
*sm
, void *priv
);
130 * getKey - Get EAP method specific keying material (eapKeyData)
131 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
132 * @priv: Pointer to private EAP method data from eap_method::init()
133 * @len: Pointer to variable to store key length (eapKeyDataLen)
134 * Returns: Keying material (eapKeyData) or %NULL if not available
136 * This function can be used to get the keying material from the EAP
137 * method. The key may already be stored in the method-specific private
138 * data or this function may derive the key.
140 u8
* (*getKey
)(struct eap_sm
*sm
, void *priv
, size_t *len
);
143 * get_status - Get EAP method status
144 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
145 * @priv: Pointer to private EAP method data from eap_method::init()
146 * @buf: Buffer for status information
147 * @buflen: Maximum buffer length
148 * @verbose: Whether to include verbose status information
149 * Returns: Number of bytes written to buf
151 * Query EAP method for status information. This function fills in a
152 * text area with current status information from the EAP method. If
153 * the buffer (buf) is not large enough, status information will be
154 * truncated to fit the buffer.
156 int (*get_status
)(struct eap_sm
*sm
, void *priv
, char *buf
,
157 size_t buflen
, int verbose
);
160 * has_reauth_data - Whether method is ready for fast reauthentication
161 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
162 * @priv: Pointer to private EAP method data from eap_method::init()
163 * Returns: %TRUE or %FALSE based on whether fast reauthentication is
166 * This function is an optional handler that only EAP methods
167 * supporting fast re-authentication need to implement.
169 Boolean (*has_reauth_data
)(struct eap_sm
*sm
, void *priv
);
172 * deinit_for_reauth - Release data that is not needed for fast re-auth
173 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
174 * @priv: Pointer to private EAP method data from eap_method::init()
176 * This function is an optional handler that only EAP methods
177 * supporting fast re-authentication need to implement. This is called
178 * when authentication has been completed and EAP state machine is
179 * requesting that enough state information is maintained for fast
182 void (*deinit_for_reauth
)(struct eap_sm
*sm
, void *priv
);
185 * init_for_reauth - Prepare for start of fast re-authentication
186 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
187 * @priv: Pointer to private EAP method data from eap_method::init()
189 * This function is an optional handler that only EAP methods
190 * supporting fast re-authentication need to implement. This is called
191 * when EAP authentication is started and EAP state machine is
192 * requesting fast re-authentication to be used.
194 void * (*init_for_reauth
)(struct eap_sm
*sm
, void *priv
);
197 * get_identity - Get method specific identity for re-authentication
198 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
199 * @priv: Pointer to private EAP method data from eap_method::init()
200 * @len: Length of the returned identity
201 * Returns: Pointer to the method specific identity or %NULL if default
202 * identity is to be used
204 * This function is an optional handler that only EAP methods
205 * that use method specific identity need to implement.
207 const u8
* (*get_identity
)(struct eap_sm
*sm
, void *priv
, size_t *len
);
212 * struct eap_sm - EAP state machine data
216 EAP_INITIALIZE
, EAP_DISABLED
, EAP_IDLE
, EAP_RECEIVED
,
217 EAP_GET_METHOD
, EAP_METHOD
, EAP_SEND_RESPONSE
, EAP_DISCARD
,
218 EAP_IDENTITY
, EAP_NOTIFICATION
, EAP_RETRANSMIT
, EAP_SUCCESS
,
221 /* Long-term local variables */
222 EapType selectedMethod
;
223 EapMethodState methodState
;
226 size_t lastRespDataLen
;
227 EapDecision decision
;
228 /* Short-term local variables */
238 /* Miscellaneous variables */
239 Boolean allowNotifications
; /* peer state machine <-> methods */
240 u8
*eapRespData
; /* peer to lower layer */
241 size_t eapRespDataLen
; /* peer to lower layer */
242 Boolean eapKeyAvailable
; /* peer to lower layer */
243 u8
*eapKeyData
; /* peer to lower layer */
244 size_t eapKeyDataLen
; /* peer to lower layer */
245 const struct eap_method
*m
; /* selected EAP method */
246 /* not defined in RFC 4137 */
249 struct eapol_callbacks
*eapol_cb
;
250 void *eap_method_priv
;
254 Boolean rxResp
/* LEAP only */;
257 u8 req_md5
[16]; /* MD5() of the current EAP packet */
258 u8 last_md5
[16]; /* MD5() of the previously received EAP packet; used
259 * in duplicate request detection. */
265 unsigned int workaround
;
267 /* Optional challenges generated in Phase 1 (EAP-FAST) */
268 u8
*peer_challenge
, *auth_challenge
;
274 const u8
* eap_hdr_validate(EapType eap_type
, const u8
*msg
, size_t msglen
,
276 void eap_set_config_blob(struct eap_sm
*sm
, struct wpa_config_blob
*blob
);
277 const struct wpa_config_blob
*
278 eap_get_config_blob(struct eap_sm
*sm
, const char *name
);