AnyConnect Secure Mobility Client  4.0.00061
include/ClientIfc.h
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_