AnyConnect Secure Mobility Client 4.4.00243

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 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_