xref: /freebsd/contrib/wpa/src/eap_server/eap_i.h (revision 9bc300465e48e19d794d88d0c158a2adb92c7197)
1 /*
2  * hostapd / EAP Authenticator state machine internal structures (RFC 4137)
3  * Copyright (c) 2004-2007, 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_I_H
10 #define EAP_I_H
11 
12 #include "wpabuf.h"
13 #include "eap_server/eap.h"
14 #include "eap_common/eap_common.h"
15 
16 /* RFC 4137 - EAP Standalone Authenticator */
17 
18 /**
19  * struct eap_method - EAP method interface
20  * This structure defines the EAP method interface. Each method will need to
21  * register its own EAP type, EAP name, and set of function pointers for method
22  * specific operations. This interface is based on section 5.4 of RFC 4137.
23  */
24 struct eap_method {
25 	int vendor;
26 	enum eap_type method;
27 	const char *name;
28 
29 	void * (*init)(struct eap_sm *sm);
30 	void * (*initPickUp)(struct eap_sm *sm);
31 	void (*reset)(struct eap_sm *sm, void *priv);
32 
33 	struct wpabuf * (*buildReq)(struct eap_sm *sm, void *priv, u8 id);
34 	int (*getTimeout)(struct eap_sm *sm, void *priv);
35 	bool (*check)(struct eap_sm *sm, void *priv, struct wpabuf *respData);
36 	void (*process)(struct eap_sm *sm, void *priv,
37 			struct wpabuf *respData);
38 	bool (*isDone)(struct eap_sm *sm, void *priv);
39 	u8 * (*getKey)(struct eap_sm *sm, void *priv, size_t *len);
40 	/* isSuccess is not specified in draft-ietf-eap-statemachine-05.txt,
41 	 * but it is useful in implementing Policy.getDecision() */
42 	bool (*isSuccess)(struct eap_sm *sm, void *priv);
43 
44 	/**
45 	 * free - Free EAP method data
46 	 * @method: Pointer to the method data registered with
47 	 * eap_server_method_register().
48 	 *
49 	 * This function will be called when the EAP method is being
50 	 * unregistered. If the EAP method allocated resources during
51 	 * registration (e.g., allocated struct eap_method), they should be
52 	 * freed in this function. No other method functions will be called
53 	 * after this call. If this function is not defined (i.e., function
54 	 * pointer is %NULL), a default handler is used to release the method
55 	 * data with free(method). This is suitable for most cases.
56 	 */
57 	void (*free)(struct eap_method *method);
58 
59 #define EAP_SERVER_METHOD_INTERFACE_VERSION 1
60 	/**
61 	 * version - Version of the EAP server method interface
62 	 *
63 	 * The EAP server method implementation should set this variable to
64 	 * EAP_SERVER_METHOD_INTERFACE_VERSION. This is used to verify that the
65 	 * EAP method is using supported API version when using dynamically
66 	 * loadable EAP methods.
67 	 */
68 	int version;
69 
70 	/**
71 	 * next - Pointer to the next EAP method
72 	 *
73 	 * This variable is used internally in the EAP method registration code
74 	 * to create a linked list of registered EAP methods.
75 	 */
76 	struct eap_method *next;
77 
78 	/**
79 	 * get_emsk - Get EAP method specific keying extended material (EMSK)
80 	 * @sm: Pointer to EAP state machine allocated with eap_sm_init()
81 	 * @priv: Pointer to private EAP method data from eap_method::init()
82 	 * @len: Pointer to a variable to store EMSK length
83 	 * Returns: EMSK or %NULL if not available
84 	 *
85 	 * This function can be used to get the extended keying material from
86 	 * the EAP method. The key may already be stored in the method-specific
87 	 * private data or this function may derive the key.
88 	 */
89 	u8 * (*get_emsk)(struct eap_sm *sm, void *priv, size_t *len);
90 
91 	/**
92 	 * getSessionId - Get EAP method specific Session-Id
93 	 * @sm: Pointer to EAP state machine allocated with eap_server_sm_init()
94 	 * @priv: Pointer to private EAP method data from eap_method::init()
95 	 * @len: Pointer to a variable to store Session-Id length
96 	 * Returns: Session-Id or %NULL if not available
97 	 *
98 	 * This function can be used to get the Session-Id from the EAP method.
99 	 * The Session-Id may already be stored in the method-specific private
100 	 * data or this function may derive the Session-Id.
101 	 */
102 	u8 * (*getSessionId)(struct eap_sm *sm, void *priv, size_t *len);
103 };
104 
105 /**
106  * struct eap_sm - EAP server state machine data
107  */
108 struct eap_sm {
109 	enum {
110 		EAP_DISABLED, EAP_INITIALIZE, EAP_IDLE, EAP_RECEIVED,
111 		EAP_INTEGRITY_CHECK, EAP_METHOD_RESPONSE, EAP_METHOD_REQUEST,
112 		EAP_PROPOSE_METHOD, EAP_SELECT_ACTION, EAP_SEND_REQUEST,
113 		EAP_DISCARD, EAP_NAK, EAP_RETRANSMIT, EAP_SUCCESS, EAP_FAILURE,
114 		EAP_TIMEOUT_FAILURE, EAP_PICK_UP_METHOD,
115 		EAP_INITIALIZE_PASSTHROUGH, EAP_IDLE2, EAP_RETRANSMIT2,
116 		EAP_RECEIVED2, EAP_DISCARD2, EAP_SEND_REQUEST2,
117 		EAP_AAA_REQUEST, EAP_AAA_RESPONSE, EAP_AAA_IDLE,
118 		EAP_TIMEOUT_FAILURE2, EAP_FAILURE2, EAP_SUCCESS2,
119 		EAP_INITIATE_REAUTH_START, EAP_INITIATE_RECEIVED
120 	} EAP_state;
121 
122 	/* Constants */
123 	int MaxRetrans;
124 
125 	struct eap_eapol_interface eap_if;
126 
127 	/* Full authenticator state machine local variables */
128 
129 	/* Long-term (maintained between packets) */
130 	enum eap_type currentMethod;
131 	int currentId;
132 	enum {
133 		METHOD_PROPOSED, METHOD_CONTINUE, METHOD_END
134 	} methodState;
135 	int retransCount;
136 	struct wpabuf *lastReqData;
137 	int methodTimeout;
138 
139 	/* Short-term (not maintained between packets) */
140 	bool rxResp;
141 	bool rxInitiate;
142 	int respId;
143 	enum eap_type respMethod;
144 	int respVendor;
145 	u32 respVendorMethod;
146 	bool ignore;
147 	enum {
148 		DECISION_SUCCESS, DECISION_FAILURE, DECISION_CONTINUE,
149 		DECISION_PASSTHROUGH, DECISION_INITIATE_REAUTH_START
150 	} decision;
151 
152 	/* Miscellaneous variables */
153 	const struct eap_method *m; /* selected EAP method */
154 	/* not defined in RFC 4137 */
155 	bool changed;
156 	void *eapol_ctx;
157 	const struct eapol_callbacks *eapol_cb;
158 	void *eap_method_priv;
159 	u8 *identity;
160 	size_t identity_len;
161 	char *serial_num;
162 	char imsi[20];
163 	char sim_aka_permanent[20];
164 	/* Whether Phase 2 method should validate identity match */
165 	int require_identity_match;
166 	int lastId; /* Identifier used in the last EAP-Packet */
167 	struct eap_user *user;
168 	int user_eap_method_index;
169 	int init_phase2;
170 	const struct eap_config *cfg;
171 	struct eap_config cfg_buf;
172 	bool update_user;
173 
174 	unsigned int num_rounds;
175 	unsigned int num_rounds_short;
176 	enum {
177 		METHOD_PENDING_NONE, METHOD_PENDING_WAIT, METHOD_PENDING_CONT
178 	} method_pending;
179 
180 	/* Optional challenges generated in Phase 1 (EAP-FAST) */
181 	u8 *auth_challenge;
182 	u8 *peer_challenge;
183 
184 	/* Whether to use the EAP-FAST-MSCHAPv2 instantiation of EAP-MSCHAPv2.
185 	 * That variant is otherwise identical, but it generates the MSK using
186 	 * MS-MPPE keys in reverse order. */
187 	bool eap_fast_mschapv2;
188 
189 	struct wpabuf *assoc_wps_ie;
190 	struct wpabuf *assoc_p2p_ie;
191 
192 	bool start_reauth;
193 
194 	u8 peer_addr[ETH_ALEN];
195 
196 	bool initiate_reauth_start_sent;
197 	bool try_initiate_reauth;
198 
199 #ifdef CONFIG_TESTING_OPTIONS
200 	u32 tls_test_flags;
201 #endif /* CONFIG_TESTING_OPTIONS */
202 };
203 
204 int eap_user_get(struct eap_sm *sm, const u8 *identity, size_t identity_len,
205 		 int phase2);
206 void eap_log_msg(struct eap_sm *sm, const char *fmt, ...)
207 PRINTF_FORMAT(2, 3);
208 void eap_sm_process_nak(struct eap_sm *sm, const u8 *nak_list, size_t len);
209 
210 #endif /* EAP_I_H */
211