![]() |
AnyConnect Secure Mobility Client 5.1.9.113
|
00001 /************************************************************************** 00002 * Copyright (c) 2006, 2022-2023 Cisco Systems, Inc. 00003 * All Rights Reserved. Cisco Highly Confidential. 00004 *************************************************************************** 00005 * 00006 * File: ClientIfc.h 00007 * Date: 11/2006 00008 * 00009 *************************************************************************** 00010 * Client Interface class implementation for the Client API. 00011 ***************************************************************************/ 00012 00013 #ifndef _CLIENTIFC_ 00014 #define _CLIENTIFC_ 00015 00016 00017 /** 00018 * This is the main interface class for applications that implement the 00019 * Cisco AnyConnect Secure Mobility VPN API. A program wishing to use the API must create a 00020 * class that extends the ClientIfc class. This new class is required to 00021 * provide implementations for the pure virtual methods found in the protected 00022 * section (for example, StatsCB). 00023 * 00024 * Finally, the public section contains methods that are available for 00025 * managing the API. These include methods like attach and connect. 00026 * 00027 * A client must implement the CB (abstract) methods found in the protected 00028 * section of this interface. 00029 * 00030 */ 00031 00032 #include "ClientIfcCommon.h" 00033 #include "api.h" 00034 #include "ClientIfcBase.h" 00035 #include "VPNStats.h" 00036 #include "ConnectPromptInfo.h" 00037 #include "Preference.h" 00038 #include "PreferenceInfo.h" 00039 00040 class ClientIfcData; 00041 00042 class VPN_VPNAPI ClientIfc : 00043 protected ClientIfcBase 00044 { 00045 friend class ClientIfcData; 00046 00047 protected: 00048 00049 ClientIfc(); 00050 00051 virtual ~ClientIfc(); 00052 00053 /** 00054 * Callback Declarations inherited from ClientIfcBase. 00055 * 00056 * Virtual Abstract Callback Method Declarations: 00057 * StatsCB 00058 * StateCB 00059 * BannerCB 00060 * NoticeCB 00061 * CertBannerCB 00062 * ServiceReadyCB 00063 * UserPromptCB 00064 * CertBlockedCB 00065 * CertWarningCB (2 signatures) 00066 * ClientCertificateCB 00067 * 00068 * Virtual Callback Method Declarations: 00069 * PreConnectReminderCB 00070 * ExitNoticeCB 00071 * WMHintCB 00072 * deliverWebLaunchHostCB 00073 * EventAvailable 00074 * ImportPKCS12ResultCB 00075 * AgentDetachedCB 00076 */ 00077 00078 public: 00079 00080 /** 00081 * After the ClientIfc class has been created, the client implementation 00082 * must invoke this method prior to attempting connections, 00083 * retrieving statistics, etc. If successful, this method returns 00084 * true. If not successful, it returns false and returns a notice error 00085 * message to the user. 00086 * 00087 * A single call to this method is all that is necessary. If the 00088 * attach fails, a message indicating the VPN service is not available 00089 * is returned. If the call succeeds, the ServiceReadyCB is 00090 * called and true is returned. 00091 * 00092 * \param ClientType clientType (default ClientType_GUI) 00093 * Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT. 00094 * ClientType_GUI: indicates that the started program is a GUI 00095 * application. With this attribute set to true, the application will 00096 * now receive WMHints. 00097 * ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation 00098 * where a GUI can be launched prior to the normal windows logon sequence. 00099 * This allows a VPN tunnel to be activated and used as part of the windows 00100 * logon sequence. This value is applicable only when a corresponding 00101 * argument has been passed to the program by the VPN agent. 00102 * ClientType_CLI: indicates that the started program is a CLI application. 00103 * ClientType_MGMT: indicates that the started program is used to initiate 00104 * an AnyConnect management VPN tunnel. This value is 00105 * applicable only to a client launched by AnyConnect VPN agent. 00106 * 00107 * \param requestFullCapabilities indicates that the client program is 00108 * requesting full API capabilities. Full capabilities allows the 00109 * client program to connect, disconnect, receive statistics, etc. 00110 * When full capabilities are not requested or not available, the 00111 * client program will not be able to establish new VPN connections. 00112 * Only a client program with full capabilites can do this. In 00113 * addition, only the first program requesting full capabilities will 00114 * be granted this level of access. The attach method can succeed 00115 * even if full capabilities is requested but not granted. To test 00116 * for this state, use the method ::hasFullCapabilities. 00117 * 00118 * \param suppressAutoConnect indicates that the client wishes to 00119 * override automatically initiating a connection to the last connected 00120 * secure gateway at startup. Normally, this is determined by the 00121 * value of the AutoConnectOnStart preference. If this flag is true 00122 * then an automatic connection will never be initiated, even if 00123 * AutoConnectOnStart is enabled. 00124 */ 00125 bool attach(ClientType clientType = ClientType_GUI, 00126 bool requestFullCapabilities = true, 00127 bool suppressAutoConnect = true); 00128 00129 00130 /** 00131 * After the client program is done, call the detach method to do a 00132 * graceful cleanup. This method stops the flow 00133 * of events and does general cleanup. 00134 */ 00135 void detach(); 00136 00137 00138 /** 00139 * When the method ClientIfc::EventAvailable has been overridden in the 00140 * client application, this method must be called to receive events. 00141 * 00142 * It is expected that GUI programs will use EventAvailable as a 00143 * signal, allowing them to set an event using their native event 00144 * handler. When that event fires, the application can call 00145 * ProcessEvents, which causes the API to deliver events in the 00146 * client's main thread. 00147 */ 00148 void ProcessEvents(); 00149 00150 00151 /** 00152 * Use this method to determine whether this application has full 00153 * capabilities. Only one application (the first one started) can have 00154 * full capabilities. If this is the first application started, this 00155 * method returns true. When an application has full capabilities, 00156 * it can initiate connections, as well as offer UI capabilities. 00157 */ 00158 bool hasFullCapabilities(); 00159 00160 00161 /** 00162 * This method returns true if the client has an active VPN 00163 * connection with a secure gateway. 00164 */ 00165 bool isConnected(bool bSilent = false); 00166 00167 00168 /** 00169 * This method returns true if the client VPN is available for use. 00170 * If false is returned this means that VPN has been intentionally 00171 * disabled. This would indicate a situation where other AnyConnect 00172 * services were in use but not VPN. 00173 */ 00174 bool isAvailable(); 00175 00176 00177 /** 00178 * This method returns true if the VPN service is available for 00179 * establishing VPN connections. 00180 */ 00181 bool isVPNServiceAvailable(); 00182 00183 00184 /** 00185 * This method returns true if the mode in which the client is 00186 * currently operating is enabled. For a list of all possible modes 00187 * of operation see the ::OperatingMode enum in api.h. 00188 */ 00189 bool isOperatingMode(OperatingMode opMode); 00190 00191 /** 00192 * This method returns a list of secure gateway host names found in an 00193 * AnyConnect profile. If no profile is available, an empty 00194 * list is returned. 00195 */ 00196 std::list<tstring> getHostNames(); 00197 00198 00199 /** 00200 * This method returns any default Host name from User Preferences. 00201 * 00202 * A host can be returned here even if there are no profiles on the 00203 * system. The host last connected to (via the connect method) is 00204 * returned by this method. 00205 * 00206 * If there is no previously connected-to host, the first host found 00207 * in an AnyConnect profile (if any) is returned. 00208 */ 00209 tstring getDefaultHostName(); 00210 00211 00212 /** 00213 * This method initiates a connection to the specified host. 00214 * The connection results in the presentation of authentication 00215 * credentials, as appropriate. Any credentials returned by the secure 00216 * gateway are delivered via the #UserPromptCB method. 00217 * 00218 * See ConnectPromptInfo for more details on possible authentication 00219 * credentials. 00220 * 00221 * If the connection request is accepted, true is returned. This does 00222 * not mean the connection succeeded. If the connection succeeds, a 00223 * state of connect will be received via the #StateCB method. 00224 */ 00225 bool connect( 00226 tstring host); 00227 00228 #if defined(HOST_DATA_SUPPORTED) 00229 bool connect( 00230 const IHostData& host); 00231 #endif 00232 00233 bool connect( 00234 #if defined(HOST_DATA_SUPPORTED) 00235 const IHostData& host, 00236 #else 00237 tstring host, 00238 #endif 00239 unsigned int origin); 00240 00241 /** 00242 * Use this method to change selected group after initial connection 00243 * request has been made and credentials were delivered. 00244 * 00245 * Depending on secure gateway configuratiion, call to this method may 00246 * result in a new connection request and will update credentials 00247 * required for the selected group. New credentials returned by the 00248 * secure gateway are delivered via the #UserPromptCB method. 00249 */ 00250 bool setNewTunnelGroup(const tstring & group); 00251 00252 /** 00253 * Use this method to initiate a disconnect of the active VPN 00254 * connection. 00255 * 00256 * An indication of VPN disconnect is received via the #StateCB 00257 * method. 00258 */ 00259 void disconnect(); 00260 00261 /** 00262 * Use this method to cancel the user authentication. VPN tunnel is not connected 00263 * at the moment. This function is used to cancel SSO authentication. 00264 * 00265 * An indication of VPN disconnect is received via the #StateCB 00266 * method. 00267 */ 00268 void cancel(); 00269 00270 /** 00271 * This method triggers the retrieval of the current VPN state. 00272 * After the client is conected to the VPN service via the #attach 00273 * method, both the current state and any changes in state are 00274 * automatically delivered to the client. In general, this method 00275 * should not be needed. 00276 * 00277 * ::VPNState is delivered via #StateCB method. 00278 */ 00279 void getState(); 00280 00281 00282 /** 00283 * This method triggers the retrieval of the current VPN statistics. 00284 * This allows an UI to notify the API that it is ready to receive 00285 * statistics. 00286 * 00287 * ::VPNState is delivered via #StatsCB method. 00288 */ 00289 void getStats(); 00290 00291 /** 00292 * This method resets current VPN statistics counters. 00293 */ 00294 void resetStats(); 00295 00296 00297 /** 00298 * This method activates the retrieval of VPN statistics and other 00299 * related data. By default, VPNStats are automatically delivered 00300 * via the method #StatsCB. 00301 * 00302 * If the #stopStats method is called to stop the delivery of 00303 * statistics, this method can be called to resume delivery. 00304 */ 00305 void startStats(); 00306 00307 00308 /** 00309 * This method stops the delivery of VPN statistics and 00310 * other related data. By default, VPNStats are automatically 00311 * delivered. This method disables delivery. 00312 * 00313 * The method #startStats can be called to resume the delivery of 00314 * statistics. 00315 */ 00316 void stopStats(); 00317 00318 00319 /** 00320 * This method directs where and how to export the statistics 00321 */ 00322 void exportStats(const tstring &tstrFilePath); 00323 00324 00325 /** 00326 * Call this method after a #BannerCB has been received to indicate 00327 * that the user response to the banner can now be read. 00328 * 00329 * \param bAccepted 00330 * indicates if the user accepted or declined the banner. 00331 */ 00332 void setBannerResponse(bool bAccepted); 00333 00334 /** 00335 * Call this method after a #PreConnectReminderCB has been received 00336 * to indicate that user has acknowledged pre-connect reminder message. 00337 * 00338 * NOTE : Ignoring the response from user (for example, closing the modal 00339 * dialog instead of clicking OK button). Old AnyConnect client (v3.1) 00340 * ignored the response too. 00341 */ 00342 void setPreConnectReminderResponse(); 00343 00344 /* 00345 * Call this method after a #CertBlockedCB has been received to 00346 * indicate the user's response to the blocked untrusted VPN server 00347 * error message. 00348 * 00349 * \param bUnblock indicates if the user wants to disable the 00350 * preference to block untrusted servers 00351 */ 00352 void setCertBlockedResponse(bool bUnblock); 00353 00354 /* 00355 * Call this method after a #CertWarningCB has been received to 00356 * indicate the user's response to the server certificate error 00357 * warning 00358 * 00359 * \param bConnect indicates user wants to connect anyways 00360 * \param bImport inidicates user wants to permanently trust 00361 * the VPN server. This would result in no future certificate 00362 * error warning prompts. bImport is only valid if 00363 * bConnect is true and bAllowImport is true when a CertWarningCB 00364 * was given. 00365 */ 00366 void setCertWarningResponse(bool bConnect, bool bImportCert); 00367 00368 00369 /** 00370 * Call this method to indicate that authentication credential 00371 * requests values solicited by the #UserPromptCB method can now 00372 * be read from the ConnectPromptInfo instance. 00373 */ 00374 void UserSubmit(); 00375 00376 00377 /** 00378 * Method for retrieving the currently available user preferences. 00379 * This method returns a instance of the class PreferenceInfo. The class 00380 * instance is a deep copy and therefore independent of any VPN API 00381 * object instances. It contains a variable number of Preference class 00382 * instance pointers. Each preference contains data identifying the 00383 * specific preference, its current value, etc. For a list of all 00384 * possible preferences see the PreferenceId enum in api.h. Note that 00385 * some of these preferences are not available to the user. 00386 * 00387 * @see PreferenceInfo 00388 */ 00389 std::shared_ptr<PreferenceInfo> getPreferences(); 00390 00391 /** 00392 * Method for retrieving the current number of available user preferences. 00393 * This method provides an optimized means of determining if there are any available user 00394 * preferences. An application may have no need to retrieve the user preferences if there are 00395 * no user preferences available, and invoking getPreferences() incurs the cost of a deep 00396 * copy of the internal PreferenceInfo class instance, possibly causing many memory 00397 * allocations, even when there are no avaiable user preferences, which could result in poor 00398 * user interface responsiveness. 00399 * 00400 * @see PreferenceInfo 00401 */ 00402 unsigned int getPreferencesCount(); 00403 00404 /** 00405 * This method stores the current set values of the preferences to the 00406 * preferences file(s). This method is a counterpart to the 00407 * getPreferences() method. 00408 */ 00409 bool savePreferences(const std::shared_ptr<PreferenceInfo>& spPreferenceInfo); 00410 00411 /** 00412 * This is called from the credential dialog in the GUI to get the correct 00413 * friendly name for the dialog title. 00414 */ 00415 tstring getConnectHost(); 00416 00417 /** 00418 * This method sets the last VPN error seen during this connection 00419 * attempt for reporting purposes. This VPN error should be cleared for 00420 * each connection attempt. 00421 */ 00422 void setLastVpnError(VPNError vpnError); 00423 00424 00425 /** 00426 * This method gets the last VPN error seen during this connection 00427 * attempt for reporting purposes. This VPN error should be cleared for 00428 * each connection attempt. 00429 */ 00430 VPNError getLastVpnError(); 00431 00432 /** 00433 * This method indicates if a request to connect has been initiated and the SG is being 00434 * contacted. Note: the connect request is not active while waiting for the user to enter 00435 * credentials. 00436 */ 00437 bool isConnectRequestActive(); 00438 00439 private: 00440 00441 // 00442 // 00443 // Private Member Methods 00444 // 00445 // 00446 00447 // Prevent copying by declaring but not defining copy constructor and operator= methods. 00448 // 00449 ClientIfc(const ClientIfc& other); 00450 ClientIfc& operator=(const ClientIfc& other); 00451 00452 #if defined(VPNAPI_EVENT_NOTIFICATION_SUPPORTED) 00453 virtual void EventNotificationInternalCB( 00454 const std::shared_ptr<CEventNotificationTlv>& spEventNtfctnTlv); 00455 #endif 00456 00457 using ClientIfcBase::ClientIfcTransmigration; 00458 00459 // 00460 // 00461 // Private Member Data 00462 // 00463 // 00464 00465 ClientIfcData* const m_pClientIfcData; 00466 }; 00467 00468 #endif //_CLIENTIFC_