![]() |
AnyConnect Secure Mobility Client 4.4.00243
|
00001 /************************************************************************** 00002 * Copyright (c) 2006, Cisco Systems, All Rights Reserved 00003 *************************************************************************** 00004 * 00005 * File: ClientIfc.h 00006 * Date: 11/2006 00007 * 00008 *************************************************************************** 00009 * 00010 * Client Interface class implementation for the Client API. 00011 * 00012 ***************************************************************************/ 00013 00014 #ifndef _CLIENTIFC_ 00015 #define _CLIENTIFC_ 00016 00017 00018 /** 00019 * This is the main interface class for applications that implement the 00020 * Cisco AnyConnect Secure Mobility VPN API. A program wishing to use the API must create a 00021 * class that extends the ClientIfc class. This new class is required to 00022 * provide implementations for the pure virtual methods found in the protected 00023 * section (for example, StatsCB). 00024 * 00025 * Finally, the public section contains methods that are available for 00026 * managing the API. These include methods like attach and connect. 00027 * 00028 * A client must implement the CB (abstract) methods found in the protected 00029 * section of this interface. 00030 * 00031 */ 00032 00033 00034 00035 #include "api.h" 00036 #include "ClientIfcBase.h" 00037 #include "VPNStats.h" 00038 #include "ConnectPromptInfo.h" 00039 #include "Preference.h" 00040 #include "PreferenceInfo.h" 00041 00042 class VPN_VPNAPI ClientIfc : protected ClientIfcBase 00043 { 00044 protected: 00045 00046 /** 00047 * Callback used to deliver new statistics related to the VPN 00048 * connection. 00049 * 00050 * When a connection is active, a new set of statistics is 00051 * delivered each second. 00052 * 00053 * @see resetStats(), stopStats() and startStats() 00054 * 00055 */ 00056 virtual void StatsCB(VPNStats &stats) = 0; 00057 00058 00059 /** 00060 * Callback used to deliver VPN state and state change string. 00061 * The stateString delivered by this method is localized. 00062 * 00063 * See the ::VPNState enum found in api.h for set of valid states. 00064 */ 00065 virtual void StateCB(const VPNState state, 00066 const VPNSubState subState, 00067 const tstring stateString) = 0; 00068 00069 00070 /** 00071 * If a banner needs to be acknowledged, this CB delivers the banner 00072 * to the client. 00073 * 00074 * NOTE: Connection establishment will block until the method 00075 * setBannerResponse() is called. 00076 * 00077 * In a GUI, a banner would typically be displayed in a modal dialog 00078 * with an accept or decline button selection. 00079 * 00080 * @see setBannerResponse() to set the user response to the banner. 00081 */ 00082 virtual void BannerCB(const tstring &banner) = 0; 00083 00084 00085 /** 00086 * Messages are delivered via the NoticeCB and can come from multiple 00087 * sources. There are four message types (error, warning, info and 00088 * status). See the ::MessageType enum in api.h for the list. 00089 * 00090 * Clients using the API as an embedded application (not 00091 * user visible) might want to further characterize 00092 * messages. One option here is to use the AnyConnect message 00093 * catalog and assign message codes as the translations for 00094 * various messages. An application could then track messages based 00095 * on its own error code scheme. 00096 */ 00097 virtual void NoticeCB(const tstring notice, 00098 const MessageType type) = 0; 00099 00100 00101 /** 00102 * This CB would likely occur only during a connection when it was 00103 * detected that the software needed to be upgraded, or when Start 00104 * Before Logon (SBL) is being used. 00105 * 00106 * Unlike the other callback methods, this method provides a default 00107 * implementation (calling the system's exit() function). 00108 * If clients of the API wish to override this behavior, they are 00109 * responsible for ensuring that the current running process exits with 00110 * the return code specified by returnCode. 00111 * 00112 * <b>Caution</b>: IF YOU OVERRIDE THIS METHOD AND DO NOT EXIT WITH 00113 * THE PROPER CODE SOFTWARE UPDATE FUNCTIONALITY IN YOUR CLIENT WILL 00114 * BREAK 00115 */ 00116 virtual void ExitNoticeCB(const tstring &tstrNotice, 00117 const int returnCode); 00118 00119 00120 /** 00121 * Under normal operating conditions, this CB is called as soon 00122 * as the attach method completes. In case the service (vpn agent) 00123 * is not ready, this CB is not called until it is. 00124 * 00125 * Any API calls made prior to this CB being called will result in a 00126 * NoticeCB error message. 00127 */ 00128 virtual void ServiceReadyCB() = 0; 00129 00130 00131 00132 /** 00133 * This method supports prompting for single or multiple values. All 00134 * prompts are considered mandatory. 00135 * 00136 * The ConnectPromptInfo object contains a list of PromptEntry 00137 * instances. The labels and their default values (if any) can be 00138 * found in these instances. After the data has been collected from the user 00139 * it can be set into these same instances. When ready, the client 00140 * application should call the method UserSubmit() to have the 00141 * responses read by the API. 00142 */ 00143 virtual void UserPromptCB(ConnectPromptInfo &ConnectPrompt) = 0; 00144 00145 00146 /** 00147 * Use this method to provide Window Manager hints to GUI 00148 * applications. To receive these hints, the application must 00149 * identify itself as a GUI in the attach method. In addition, this 00150 * method should be overriden to receive any generated events. 00151 * 00152 * Event that can be received include those indicating that a user is 00153 * starting a second instance of the GUI application. This information 00154 * can be used to tell the already running application to un-minimize 00155 * itself and let the new program know that it should Quit (since a GUI 00156 * is already running). 00157 */ 00158 virtual void WMHintCB(const WMHint hint, 00159 const WMHintReason reason); 00160 00161 00162 /** 00163 * This method is useful when the connection to the secure gateway 00164 * has been established as part of a web-launch of the VPN tunnel. 00165 * 00166 * If the client application wishes to be notified of the secure 00167 * gateway to which the VPN has been established, this method should 00168 * be overriden. 00169 * 00170 * If the client application is started and a tunnel is already active, 00171 * this method also delivers the name of the secure gateway host. 00172 */ 00173 virtual void deliverWebLaunchHostCB(const tstring &activeHost); 00174 00175 /** 00176 * This method is called when the result of a vpnapi_request_importpkcs12(..) 00177 * call is known. If bResult is false then pszError will be an error string. 00178 */ 00179 virtual void ImportPKCS12ResultCB(bool bResult, const tstring &strError); 00180 00181 /** 00182 * This method is called when the preference to block untrusted 00183 * servers is enabled and the current VPN server being connected 00184 * to is untrusted. Clients should present an error to the user 00185 * notifying them that the current connection to rtstrUntrustedServer 00186 * is being blocked. The client should also provide a way for the 00187 * user to change the preference to block untrusted servers. 00188 * 00189 * The user response must be indicated using setCertBlockedResponse 00190 */ 00191 virtual void CertBlockedCB(const tstring &rtstrUntrustedServer) = 0; 00192 00193 /** 00194 * This method is called when connections to untrusted VPN servers 00195 * is allowed by policies and the current VPN server being connected 00196 * to is untrusted. Clients should present a warning to the user 00197 * notifying them that the current connection to rtstrUntrustedServer 00198 * is unsafe. The reason the VPN server is untrusted is provided in 00199 * rltstrCertErrors. The client should provide a way for the user to 00200 * connect once, connect and always trust or cancel the connection. 00201 * If bAllowImport is set to false then the always trust option should 00202 * not be presented to users. 00203 * 00204 * The user response must be indicated using setCertWarningResponse 00205 */ 00206 virtual void CertWarningCB(const tstring &rtstrUntrustedServer, 00207 const std::list<tstring> &rltstrCertErrors, 00208 bool bAllowImport) = 0; 00209 00210 /** 00211 * This method can be overriden if the client application wishes to 00212 * exercise some control over the delivery of events from the other 00213 * protected methods in this class. 00214 * 00215 * This might be necessary in cases where a GUI is being written and 00216 * the data from this API needs to be delivered in the GUI or main 00217 * thread. In this case, you should override this method and when it 00218 * is called by the API post an event to your event queue (message 00219 * pump, etc.). After this event executes in your GUI or main thread, 00220 * call the method ClientIfc::ProcessEvents to have events delivered 00221 * to your client application. 00222 */ 00223 virtual void EventAvailable(); 00224 00225 00226 ClientIfc(); 00227 00228 00229 public: 00230 00231 /** 00232 * After the ClientIfc class has been created, the client implementation 00233 * must invoke this method prior to attempting connections, 00234 * retrieving statistics, etc. If successful, this method returns 00235 * true. If not successful, it returns false and returns a notice error 00236 * message to the user. 00237 * 00238 * A single call to this method is all that is necessary. If the 00239 * attach fails, a message indicating the VPN service is not available 00240 * is returned. If the call succeeds, the ServiceReadyCB is 00241 * called and true is returned. 00242 * 00243 * \param SBL Start Before Logon 00244 * is a mode of operation where a GUI 00245 * can be launched prior to the normal windows logon sequence. This 00246 * allows a VPN tunnel to be activated and used as part of the windows 00247 * logon sequence. The SBL attribute should be set to true only when 00248 * it has been passed as an argument to the program by the VPN agent. 00249 * 00250 * \param isGUI indicates that the started program is a UI 00251 * application. With this attribute set to true, the application will 00252 * now receive WMHints. 00253 * 00254 * \param requestFullCapabilities indicates that the client program is 00255 * requesting full API capabilities. Full capabilities allows the 00256 * client program to connect, disconnect, receive statistics, etc. 00257 * When full capabilities are not requested or not available, the 00258 * client program will not be able to establish new VPN connections. 00259 * Only a client program with full capabilites can do this. In 00260 * addition, only the first program requesting full capabilities will 00261 * be granted this level of access. The attach method can succeed 00262 * even if full capabilities is requested but not granted. To test 00263 * for this state, use the method ::hasFullCapabilities. 00264 * 00265 * \param suppressAutoConnect indicates that the client wishes to 00266 * override automatically initiating a connection to the last connected 00267 * secure gateway at startup. Normally, this is determined by the 00268 * value of the AutoConnectOnStart preference. If this flag is true 00269 * then an automatic connection will never be initiated, even if 00270 * AutoConnectOnStart is enabled. 00271 */ 00272 bool attach(bool SBL = false, 00273 bool isGUI = true, 00274 bool requestFullCapabilities = true, 00275 bool suppressAutoConnect = true); 00276 00277 00278 /** 00279 * After the client program is done, call the detach method to do a 00280 * graceful cleanup. This method stops the flow 00281 * of events and does general cleanup. 00282 */ 00283 void detach(); 00284 00285 00286 /** 00287 * When the method ClientIfc::EventAvailable has been overriden in the 00288 * client application, this method must be called to receive events. 00289 * 00290 * It is expected that GUI programs will use EventAvailable as a 00291 * signal, allowing them to set an event using their native event 00292 * handler. When that event fires, the application can call 00293 * ProcessEvents, which causes the API to deliver events in the 00294 * client's main thread. 00295 */ 00296 virtual void ProcessEvents(); 00297 00298 00299 /** 00300 * Use this method to determine whether this application has full 00301 * capabilities. Only one application (the first one started) can have 00302 * full capabilities. If this is the first application started, this 00303 * method returns true. When an application does not have full 00304 * capabilities, it cannot initiate connections. 00305 */ 00306 bool hasFullCapabilities(); 00307 00308 00309 /** 00310 * This method returns true if the client has an active VPN 00311 * connection with a secure gateway. 00312 */ 00313 bool isConnected(); 00314 00315 00316 /** 00317 * This method returns true if the client VPN is available for use. 00318 * If false is returned this means that VPN has been intentionally 00319 * disabled. This would indicate a situation where other AnyConnect 00320 * services were in use but not VPN. 00321 */ 00322 bool isAvailable(); 00323 00324 00325 /** 00326 * This method returns true if the VPN service is available for 00327 * establishing VPN connections. 00328 */ 00329 bool isVPNServiceAvailable(); 00330 00331 00332 /** 00333 * This method returns true if the mode in which the client is 00334 * currently operating is enabled. For a list of all possible modes 00335 * of operation see the ::OperatingMode enum in api.h. 00336 */ 00337 bool isOperatingMode(OperatingMode opMode); 00338 00339 /** 00340 * This method returns a list of secure gateway host names found in an 00341 * AnyConnect profile. If no profile is available, an empty 00342 * list is returned. 00343 */ 00344 std::list<tstring> getHostNames(); 00345 00346 00347 /** 00348 * This method returns any default Host name from User Preferences. 00349 * 00350 * A host can be returned here even if there are no profiles on the 00351 * system. The host last connected to (via the connect method) is 00352 * returned by this method. 00353 * 00354 * If there is no previously connected-to host, the first host found 00355 * in an AnyConnect profile (if any) is returned. 00356 */ 00357 tstring getDefaultHostName(); 00358 00359 00360 /** 00361 * This method initiates a connection to the specified host. 00362 * The connection results in the presentation of authentication 00363 * credentials, as appropriate. Any credentials returned by the secure 00364 * gateway are delivered via the #UserPromptCB method. 00365 * 00366 * See ConnectPromptInfo for more details on possible authentication 00367 * credentials. 00368 * 00369 * If the connection request is accepted, true is returned. This does 00370 * not mean the connection succeeded. If the connection succeeds, a 00371 * state of connect will be received via the #StateCB method. 00372 */ 00373 bool connect(tstring host); 00374 00375 /** 00376 * Use this method to change selected group after initial connection 00377 * request has been made and credentials were delivered. 00378 * 00379 * Depending on secure gateway configuratiion, call to this method may 00380 * result in a new connection request and will update credentials 00381 * required for the selected group. New credentials returned by the 00382 * secure gateway are delivered via the #UserPromptCB method. 00383 */ 00384 virtual bool setNewTunnelGroup(const tstring & group); 00385 00386 /** 00387 * Use this method to initiate a disconnect of the active VPN 00388 * connection. 00389 * 00390 * An indication of VPN disconnect is received via the #StateCB 00391 * method. 00392 */ 00393 void disconnect(); 00394 00395 /** 00396 * Use this method to cancel the user authentication. VPN tunnel is not connected 00397 * at the moment. This function is used to cancel SSO authentication. 00398 * 00399 * An indication of VPN disconnect is received via the #StateCB 00400 * method. 00401 */ 00402 void cancel(); 00403 00404 /** 00405 * This method triggers the retrieval of the current VPN state. 00406 * After the client is conected to the VPN service via the #attach 00407 * method, both the current state and any changes in state are 00408 * automatically delivered to the client. In general, this method 00409 * should not be needed. 00410 * 00411 * ::VPNState is delivered via #StateCB method. 00412 */ 00413 void getState(); 00414 00415 00416 /** 00417 * This method triggers the retrieval of the current VPN statistics. 00418 * This allows an UI to notify the API that it is ready to receive 00419 * statistics. 00420 * 00421 * ::VPNState is delivered via #StatsCB method. 00422 */ 00423 void getStats(); 00424 00425 /** 00426 * This method resets current VPN statistics counters. 00427 */ 00428 void resetStats(); 00429 00430 00431 /** 00432 * This method activates the retrieval of VPN statistics and other 00433 * related data. By default, VPNStats are automatically delivered 00434 * via the method #StatsCB. 00435 * 00436 * If the #stopStats method is called to stop the delivery of 00437 * statistics, this method can be called to resume delivery. 00438 */ 00439 void startStats(); 00440 00441 00442 /** 00443 * This method stops the delivery of VPN statistics and 00444 * other related data. By default, VPNStats are automatically 00445 * delivered. This method disables delivery. 00446 * 00447 * The method #startStats can be called to resume the delivery of 00448 * statistics. 00449 */ 00450 void stopStats(); 00451 00452 00453 /** 00454 * This method directs where and how to export the statistics 00455 */ 00456 void exportStats(const tstring &tstrFilePath); 00457 00458 00459 /** 00460 * Call this method after a #BannerCB has been received to indicate 00461 * that the user response to the banner can now be read. 00462 * 00463 * \param bAccepted 00464 * indicates if the user accepted or declined the banner. 00465 */ 00466 void setBannerResponse(bool bAccepted); 00467 00468 /* 00469 * Call this method after a #CertBlockedCB has been received to 00470 * indicate the user's response to the blocked untrusted VPN server 00471 * error message. 00472 * 00473 * \param bUnblock indicates if the user wants to disable the 00474 * preference to block untrusted servers 00475 */ 00476 void setCertBlockedResponse(bool bUnblock); 00477 00478 /* 00479 * Call this method after a #CertWarningCB has been received to 00480 * indicate the user's response to the server certificate error 00481 * warning 00482 * 00483 * \param bConnect indicates user wants to connect anyways 00484 * \param bImport inidicates user wants to permanently trust 00485 * the VPN server. This would result in no future certificate 00486 * error warning prompts. bImport is only valid if 00487 * bConnect is true and bAllowImport is true when a CertWarningCB 00488 * was given. 00489 */ 00490 void setCertWarningResponse(bool bConnect, bool bImportCert); 00491 00492 00493 /** 00494 * Call this method to indicate that authentication credential 00495 * requests values solicited by the #UserPromptCB method can now 00496 * be read from the ConnectPromptInfo instance. 00497 */ 00498 void UserSubmit(); 00499 00500 00501 /** 00502 * Method for retrieving the currently available user preferences. 00503 * This method returns an instance of the class PreferenceInfo. The 00504 * instance contains a variable number of Preference object pointers. 00505 * Each preference contains data identifying the specific preference, 00506 * its current value, etc. For a list of all possible preferences see 00507 * the ::PreferenceId enum in api.h. Note that some of these 00508 * preferences are not available to the user. 00509 * 00510 * @see PreferenceInfo 00511 */ 00512 PreferenceInfo &getPreferences(); 00513 00514 00515 /** 00516 * This method stores the current set values of the preferences to the 00517 * preferences file(s). This method is a counterpart to the 00518 * getPreferences() method. 00519 */ 00520 bool savePreferences(); 00521 00522 /** 00523 * This is called from the credential dialog in the GUI to get the correct 00524 * friendly name for the dialog title. 00525 */ 00526 tstring getConnectHost(); 00527 00528 /** 00529 * This method is used to import a PKCS12 file from a byte array. 00530 * May incite UserPromptCB() to prompt for the p12 password. Will 00531 * invoke ImportPKCS12ResultCB() to indicate the result. 00532 * Returns true if the request was acknowledged, false otherwise. 00533 */ 00534 bool requestImportPKCS12(const std::vector<unsigned char> &der); 00535 00536 /** 00537 * This method is used to import a gettext localization file from a 00538 * byte array, for the specified locale. Returns true if the locale 00539 * file was successfully imported, false otherwise. 00540 * Note: successful import does not guarantee that the specified 00541 * locale will be used. 00542 */ 00543 bool requestImportLocalization(const tstring tstrLocale, 00544 const std::vector<unsigned char> &MoFileData); 00545 00546 virtual ~ClientIfc(); 00547 00548 private: 00549 00550 ClientIfc(const ClientIfc& other); 00551 ClientIfc& operator=(const ClientIfc& other); 00552 00553 }; 00554 00555 #endif //_CLIENTIFC_