1/*
2 * Copyright (c) 2002-2013 Apple Inc. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24#ifndef _EAP8021X_EAPOLCONTROL_H
25#define _EAP8021X_EAPOLCONTROL_H
26#include <CoreFoundation/CFDictionary.h>
27#include <CoreFoundation/CFString.h>
28#include <TargetConditionals.h>
29#include <EAP8021X/EAPOLControlTypes.h>
30#if ! TARGET_OS_EMBEDDED
31#include <EAP8021X/EAPOLClientConfiguration.h>
32#endif /* ! TARGET_OS_EMBEDDED */
33
34/*
35 * Function: EAPOLControlKeyCreate
36 * Returns:
37 *   The DynamicStore key to use to retrieve information for the given
38 *   interface, and/or use for notification for a specific interface.
39 */
40CFStringRef
41EAPOLControlKeyCreate(const char * interface_name);
42
43/*
44 * Function: EAPOLControlAnyInterfaceKeyCreate
45 * Returns:
46 *   The DynamicStore key to use to register for notifications on
47 *   any interface's EAPOL information changing.
48 */
49CFStringRef
50EAPOLControlAnyInterfaceKeyCreate(void);
51
52/*
53 * Function: EAPOLControlKeyCopyInterface
54 * Returns:
55 *   The interface associated with the given EAPOL interface key,
56 *   NULL if the key is invalid.
57 */
58CFStringRef
59EAPOLControlKeyCopyInterface(CFStringRef key);
60
61
62/*
63 * Function: EAPOLControlStart
64 *
65 * Purpose:
66 *   Start an authentication session on the specified interface.
67 *
68 *   The config dictionary has the following format:
69 *     kEAPOLControlEAPClientConfiguration  authentication properties
70 *     kEAPOLControlUniqueIdentifier	    unique string for session (optional)
71 *     kEAPOLControlLogLevel		    log level (optional)
72 *
73 *   See also <EAP8021X/EAPOLControlTypes.h>.
74 *
75 * Returns:
76 *   0 if successful, non-zero errno value otherwise.
77 * Note:
78 *   On the Mac, EAPOLControlStartWithClientItemID() is the preferred way to
79 *   start the authentication session.   This function remains for
80 *   backwards compatibility.
81 */
82int
83EAPOLControlStart(const char * interface_name, CFDictionaryRef config);
84
85#if ! TARGET_OS_EMBEDDED
86/*
87 * Function: EAPOLControlStartWithClientItemID
88 *
89 * Purpose:
90 *   Start an authentication session over the specified interface using
91 *   the specified EAPOLClientItemIDRef.
92 *
93 *   The 'auth_info' dictionary may be NULL.   If it is not NULL, it may
94 *   contain any of the following properties:
95 *     kEAPClientPropUserName
96 *     kEAPClientPropUserPassword
97 *     kEAPClientPropTLSIdentityHandle
98 *     kEAPClientPropSaveCredentialsOnSuccessfulAuthentication
99 *   If properties not in this list are specified in 'auth_info", EINVAL
100 *   is returned.
101 *
102 * Returns:
103 *   0 if successful, non-zero errno value otherwise.
104 */
105int
106EAPOLControlStartWithClientItemID(const char * if_name,
107				  EAPOLClientItemIDRef itemID,
108				  CFDictionaryRef auth_info);
109#endif /* ! TARGET_OS_EMBEDDED */
110
111/*
112 * Function: EAPOLControlUpdate
113 *
114 * Purpose:
115 *   Update the configuration used by the authentication session on
116 *   the specified interface.
117 *
118 * Returns:
119 *   0 if successful, non-zero errno value otherwise.
120 */
121int
122EAPOLControlUpdate(const char * interface_name, CFDictionaryRef config);
123
124/*
125 * Function: EAPOLControlStop
126 *
127 * Purpose:
128 *    Terminate the authentication session over the specified interface.
129 * Returns:
130 *   0 if successful, non-zero errno value otherwise.
131 */
132int
133EAPOLControlStop(const char * interface_name);
134
135/*
136 * Function: EAPOLControlRetry
137 *
138 * Purpose:
139 *    Forces the authentication client to send an EAPOL Start
140 *    packet which usually has the effect of triggering a re-authentication
141 *
142 * Returns:
143 *   0 if successful, non-zero errno value otherwise.
144 *
145 * Note:
146 *   This function should not be called by production code, it's there for
147 *   testing/debugging.
148 */
149int
150EAPOLControlRetry(const char * interface_name);
151
152/*
153 * Function: EAPOLControlProvideUserInput
154 *
155 * Purpose:
156 *   Tell the EAP client that the user has provided input and/or changed
157 *   something in the environment that would allow the authentication to
158 *   continue e.g. modified trust settings.
159 *
160 * Arguments:
161 *   interface_name	name of the BSD interface
162 *   user_input		If ! NULL, contains keys/values
163 *			corresponding to the additional user input.
164 *                      The keys/values are merged into the
165 *                      client configuration dictionary.
166 *
167 *                      If NULL, simply means that the user has changed
168 *       		something in the environment, and the EAP client
169 *			should try to continue the authentication.
170 */
171int
172EAPOLControlProvideUserInput(const char * interface_name,
173			     CFDictionaryRef user_input);
174
175/*
176 * Function: EAPOLControlCopyStateAndStatus
177 *
178 * Purpose:
179 *   Return the current EAPOLControl state (Idle, Starting, Running, Stopping)
180 *   and the current authentication status.
181 *
182 * Returns:
183 *   0 if successful, *status_dict_p may be non-NULL,
184 *   non-zero errno value otherwise.
185 */
186int
187EAPOLControlCopyStateAndStatus(const char * interface_name,
188			       EAPOLControlState * state,
189			       CFDictionaryRef * status_dict_p);
190
191/*
192 * Function: EAPOLControlSetLogLevel
193 * Purpose:
194 *   Deprecated.
195 */
196int
197EAPOLControlSetLogLevel(const char * interface_name, int32_t level);
198
199#if ! TARGET_OS_EMBEDDED
200/*
201 * Function: EAPOLControlDidUserCancel
202 *
203 * Purpose:
204 *    Returns whether the user cancelled the last authentication session.
205 *    This helps to avoid bothering the user with multiple dialogues
206 *    when they've already been informed and are aware of what's happenened.
207 *    EAPOLMonitor uses it to avoid prompting the user again if the user
208 *    cancels the authentication over Ethernet.
209 */
210boolean_t
211EAPOLControlDidUserCancel(const char * if_name);
212
213/*
214 * Function: EAPOLControlStartSystem
215 * Purpose:
216 *   If a System Mode configuration exists on the given interface, start it.
217 *   This function is used to resume a System mode authentication session
218 *   after calling EAPOLControlStop() when System mode was active on the
219 *   interace.
220 *
221 * Note:
222 *   Currently the 'options' parameter is not used, pass NULL.
223 */
224int
225EAPOLControlStartSystem(const char * interface_name, CFDictionaryRef options);
226
227/*
228 * Function: EAPOLControlStartSystemWithClientItemID
229 * Purpose:
230 *   Start an authentication session running in System Mode over the
231 *   specified interface using the specified EAPOLClientItemIDRef.
232 *
233 * Returns:
234 *   0 if successful, non-zero errno value otherwise.
235 */
236int
237EAPOLControlStartSystemWithClientItemID(const char * interface_name,
238					EAPOLClientItemIDRef itemID);
239
240/*
241 * Function: EAPOLControlCopyLoginWindowConfiguration
242 * Purpose:
243 *   If LoginWindow mode is activated during this login session, returns the
244 *   configuration that was used.  This value is cleared when the user logs out.
245 *
246 * Returns:
247 *   0 and non-NULL CFDictionaryRef value in *config_p on success,
248 *   non-zero on failure
249 */
250int
251EAPOLControlCopyLoginWindowConfiguration(const char * interface_name,
252					 CFDictionaryRef * config_p);
253/*
254 * Function: EAPOLControlCopyLoginWindowClientItemID
255 *
256 * Purpose:
257 *   If LoginWindow mode is activated during this login session, returns the
258 *   EAPOLClientItemIDRef corresponding to the profile that was used.  The
259 *   information is cleared when the user logs out.
260 *
261 * Returns:
262 *   0 and non-NULL EAPOLClientItemIDRef on success,
263 *   non-zero errno on failure.
264 */
265int
266EAPOLControlCopyLoginWindowClientItemID(const char * if_name,
267					EAPOLClientItemIDRef * itemID_p);
268
269/*
270 * Function: EAPOLControlSetUserAutoConnectEnabled
271 * Purpose:
272 *    Enable/disable connecting automatically to 802.1X ethernet networks
273 *    for the logged-in user.
274 *
275 *    If "enable" is TRUE, connection attempts will be made automatically.
276 *    If "enable" is FALSE, no connection attempts will be made automatically.
277 */
278void
279EAPOLControlSetUserAutoConnectEnabled(Boolean enable);
280
281/*
282 * Function: EAPOLControlIsUserAutoConnectEnabled
283 * Purpose:
284 *   Return whether the system will auto-connect to 802.1X to ethernet
285 *   networks for the logged-in user.
286 *
287 * Returns:
288 *   TRUE if auto-connect is enabled, FALSE otherwise.
289 */
290Boolean
291EAPOLControlIsUserAutoConnectEnabled(void);
292
293#endif /* ! TARGET_OS_EMBEDDED */
294
295#endif /* _EAP8021X_EAPOLCONTROL_H */
296