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