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