AnyConnect Secure Mobility Client 5.1.9.113

include/ClientIfc.h

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