AnyConnect Secure Mobility Client  5.1.2.42
ClientIfc.h
1 /**************************************************************************
2 * Copyright (c) 2006, 2022-2023 Cisco Systems, Inc.
3 * All Rights Reserved. Cisco Highly Confidential.
4 ***************************************************************************
5 *
6 * File: ClientIfc.h
7 * Date: 11/2006
8 *
9 ***************************************************************************
10 * Client Interface class implementation for the Client API.
11 ***************************************************************************/
12 
13 #ifndef _CLIENTIFC_
14 #define _CLIENTIFC_
15 
16 
17 /**
18 * This is the main interface class for applications that implement the
19 * Cisco AnyConnect Secure Mobility VPN API. A program wishing to use the API must create a
20 * class that extends the ClientIfc class. This new class is required to
21 * provide implementations for the pure virtual methods found in the protected
22 * section (for example, StatsCB).
23 *
24 * Finally, the public section contains methods that are available for
25 * managing the API. These include methods like attach and connect.
26 *
27 * A client must implement the CB (abstract) methods found in the protected
28 * section of this interface.
29 *
30 */
31 
32 #include "ClientIfcCommon.h"
33 #include "api.h"
34 #include "ClientIfcBase.h"
35 #include "VPNStats.h"
36 #include "ConnectPromptInfo.h"
37 #include "Preference.h"
38 #include "PreferenceInfo.h"
39 
40 class ClientIfcData;
41 
42 class VPN_VPNAPI ClientIfc :
43  protected ClientIfcBase
44 {
45  friend class ClientIfcData;
46 
47  protected:
48 
49  ClientIfc();
50 
51  virtual ~ClientIfc();
52 
53  /**
54  * Callback Declarations inherited from ClientIfcBase.
55  *
56  * Virtual Abstract Callback Method Declarations:
57  * StatsCB
58  * StateCB
59  * BannerCB
60  * NoticeCB
61  * CertBannerCB
62  * ServiceReadyCB
63  * UserPromptCB
64  * CertBlockedCB
65  * CertWarningCB (2 signatures)
66  * ClientCertificateCB
67  *
68  * Virtual Callback Method Declarations:
69  * PreConnectReminderCB
70  * ExitNoticeCB
71  * WMHintCB
72  * deliverWebLaunchHostCB
73  * EventAvailable
74  * ImportPKCS12ResultCB
75  * AgentDetachedCB
76  */
77 
78  public:
79 
80  /**
81  * After the ClientIfc class has been created, the client implementation
82  * must invoke this method prior to attempting connections,
83  * retrieving statistics, etc. If successful, this method returns
84  * true. If not successful, it returns false and returns a notice error
85  * message to the user.
86  *
87  * A single call to this method is all that is necessary. If the
88  * attach fails, a message indicating the VPN service is not available
89  * is returned. If the call succeeds, the ServiceReadyCB is
90  * called and true is returned.
91  *
92  * \param ClientType clientType (default ClientType_GUI)
93  * Other options: ClientType_GUI_SBL, ClientType_CLI, ClientType_MGMT.
94  * ClientType_GUI: indicates that the started program is a GUI
95  * application. With this attribute set to true, the application will
96  * now receive WMHints.
97  * ClientType_GUI_SBL: SBL (Start Before Logon) is a mode of operation
98  * where a GUI can be launched prior to the normal windows logon sequence.
99  * This allows a VPN tunnel to be activated and used as part of the windows
100  * logon sequence. This value is applicable only when a corresponding
101  * argument has been passed to the program by the VPN agent.
102  * ClientType_CLI: indicates that the started program is a CLI application.
103  * ClientType_MGMT: indicates that the started program is used to initiate
104  * an AnyConnect management VPN tunnel. This value is
105  * applicable only to a client launched by AnyConnect VPN agent.
106  *
107  * \param requestFullCapabilities indicates that the client program is
108  * requesting full API capabilities. Full capabilities allows the
109  * client program to connect, disconnect, receive statistics, etc.
110  * When full capabilities are not requested or not available, the
111  * client program will not be able to establish new VPN connections.
112  * Only a client program with full capabilites can do this. In
113  * addition, only the first program requesting full capabilities will
114  * be granted this level of access. The attach method can succeed
115  * even if full capabilities is requested but not granted. To test
116  * for this state, use the method ::hasFullCapabilities.
117  *
118  * \param suppressAutoConnect indicates that the client wishes to
119  * override automatically initiating a connection to the last connected
120  * secure gateway at startup. Normally, this is determined by the
121  * value of the AutoConnectOnStart preference. If this flag is true
122  * then an automatic connection will never be initiated, even if
123  * AutoConnectOnStart is enabled.
124  */
125  bool attach(ClientType clientType = ClientType_GUI,
126  bool requestFullCapabilities = true,
127  bool suppressAutoConnect = true);
128 
129 
130  /**
131  * After the client program is done, call the detach method to do a
132  * graceful cleanup. This method stops the flow
133  * of events and does general cleanup.
134  */
135  void detach();
136 
137 
138  /**
139  * When the method ClientIfc::EventAvailable has been overridden in the
140  * client application, this method must be called to receive events.
141  *
142  * It is expected that GUI programs will use EventAvailable as a
143  * signal, allowing them to set an event using their native event
144  * handler. When that event fires, the application can call
145  * ProcessEvents, which causes the API to deliver events in the
146  * client's main thread.
147  */
148  void ProcessEvents();
149 
150 
151  /**
152  * Use this method to determine whether this application has full
153  * capabilities. Only one application (the first one started) can have
154  * full capabilities. If this is the first application started, this
155  * method returns true. When an application has full capabilities,
156  * it can initiate connections, as well as offer UI capabilities.
157  */
158  bool hasFullCapabilities();
159 
160 
161  /**
162  * This method returns true if the client has an active VPN
163  * connection with a secure gateway.
164  */
165  bool isConnected(bool bSilent = false);
166 
167 
168  /**
169  * This method returns true if the client VPN is available for use.
170  * If false is returned this means that VPN has been intentionally
171  * disabled. This would indicate a situation where other AnyConnect
172  * services were in use but not VPN.
173  */
174  bool isAvailable();
175 
176 
177  /**
178  * This method returns true if the VPN service is available for
179  * establishing VPN connections.
180  */
181  bool isVPNServiceAvailable();
182 
183 
184  /**
185  * This method returns true if the mode in which the client is
186  * currently operating is enabled. For a list of all possible modes
187  * of operation see the ::OperatingMode enum in api.h.
188  */
189  bool isOperatingMode(OperatingMode opMode);
190 
191  /**
192  * This method returns a list of secure gateway host names found in an
193  * AnyConnect profile. If no profile is available, an empty
194  * list is returned.
195  */
196  std::list<tstring> getHostNames();
197 
198 
199  /**
200  * This method returns any default Host name from User Preferences.
201  *
202  * A host can be returned here even if there are no profiles on the
203  * system. The host last connected to (via the connect method) is
204  * returned by this method.
205  *
206  * If there is no previously connected-to host, the first host found
207  * in an AnyConnect profile (if any) is returned.
208  */
209  tstring getDefaultHostName();
210 
211 
212  /**
213  * This method initiates a connection to the specified host.
214  * The connection results in the presentation of authentication
215  * credentials, as appropriate. Any credentials returned by the secure
216  * gateway are delivered via the #UserPromptCB method.
217  *
218  * See ConnectPromptInfo for more details on possible authentication
219  * credentials.
220  *
221  * If the connection request is accepted, true is returned. This does
222  * not mean the connection succeeded. If the connection succeeds, a
223  * state of connect will be received via the #StateCB method.
224  */
225  bool connect(
226  tstring host);
227 
228 #if defined(HOST_DATA_SUPPORTED)
229  bool connect(
230  const IHostData& host);
231 #endif
232 
233  bool connect(
234 #if defined(HOST_DATA_SUPPORTED)
235  const IHostData& host,
236 #else
237  tstring host,
238 #endif
239  unsigned int origin);
240 
241  /**
242  * Use this method to change selected group after initial connection
243  * request has been made and credentials were delivered.
244  *
245  * Depending on secure gateway configuratiion, call to this method may
246  * result in a new connection request and will update credentials
247  * required for the selected group. New credentials returned by the
248  * secure gateway are delivered via the #UserPromptCB method.
249  */
250  bool setNewTunnelGroup(const tstring & group);
251 
252  /**
253  * Use this method to initiate a disconnect of the active VPN
254  * connection.
255  *
256  * An indication of VPN disconnect is received via the #StateCB
257  * method.
258  */
259  void disconnect();
260 
261  /**
262  * Use this method to cancel the user authentication. VPN tunnel is not connected
263  * at the moment. This function is used to cancel SSO authentication.
264  *
265  * An indication of VPN disconnect is received via the #StateCB
266  * method.
267  */
268  void cancel();
269 
270  /**
271  * This method triggers the retrieval of the current VPN state.
272  * After the client is conected to the VPN service via the #attach
273  * method, both the current state and any changes in state are
274  * automatically delivered to the client. In general, this method
275  * should not be needed.
276  *
277  * ::VPNState is delivered via #StateCB method.
278  */
279  void getState();
280 
281 
282  /**
283  * This method triggers the retrieval of the current VPN statistics.
284  * This allows an UI to notify the API that it is ready to receive
285  * statistics.
286  *
287  * ::VPNState is delivered via #StatsCB method.
288  */
289  void getStats();
290 
291  /**
292  * This method resets current VPN statistics counters.
293  */
294  void resetStats();
295 
296 
297  /**
298  * This method activates the retrieval of VPN statistics and other
299  * related data. By default, VPNStats are automatically delivered
300  * via the method #StatsCB.
301  *
302  * If the #stopStats method is called to stop the delivery of
303  * statistics, this method can be called to resume delivery.
304  */
305  void startStats();
306 
307 
308  /**
309  * This method stops the delivery of VPN statistics and
310  * other related data. By default, VPNStats are automatically
311  * delivered. This method disables delivery.
312  *
313  * The method #startStats can be called to resume the delivery of
314  * statistics.
315  */
316  void stopStats();
317 
318 
319  /**
320  * This method directs where and how to export the statistics
321  */
322  void exportStats(const tstring &tstrFilePath);
323 
324 
325  /**
326  * Call this method after a #BannerCB has been received to indicate
327  * that the user response to the banner can now be read.
328  *
329  * \param bAccepted
330  * indicates if the user accepted or declined the banner.
331  */
332  void setBannerResponse(bool bAccepted);
333 
334  /**
335  * Call this method after a #PreConnectReminderCB has been received
336  * to indicate that user has acknowledged pre-connect reminder message.
337  *
338  * NOTE : Ignoring the response from user (for example, closing the modal
339  * dialog instead of clicking OK button). Old AnyConnect client (v3.1)
340  * ignored the response too.
341  */
342  void setPreConnectReminderResponse();
343 
344  /*
345  * Call this method after a #CertBlockedCB has been received to
346  * indicate the user's response to the blocked untrusted VPN server
347  * error message.
348  *
349  * \param bUnblock indicates if the user wants to disable the
350  * preference to block untrusted servers
351  */
352  void setCertBlockedResponse(bool bUnblock);
353 
354  /*
355  * Call this method after a #CertWarningCB has been received to
356  * indicate the user's response to the server certificate error
357  * warning
358  *
359  * \param bConnect indicates user wants to connect anyways
360  * \param bImport inidicates user wants to permanently trust
361  * the VPN server. This would result in no future certificate
362  * error warning prompts. bImport is only valid if
363  * bConnect is true and bAllowImport is true when a CertWarningCB
364  * was given.
365  */
366  void setCertWarningResponse(bool bConnect, bool bImportCert);
367 
368 
369  /**
370  * Call this method to indicate that authentication credential
371  * requests values solicited by the #UserPromptCB method can now
372  * be read from the ConnectPromptInfo instance.
373  */
374  void UserSubmit();
375 
376 
377  /**
378  * Method for retrieving the currently available user preferences.
379  * This method returns a instance of the class PreferenceInfo. The class
380  * instance is a deep copy and therefore independent of any VPN API
381  * object instances. It contains a variable number of Preference class
382  * instance pointers. Each preference contains data identifying the
383  * specific preference, its current value, etc. For a list of all
384  * possible preferences see the PreferenceId enum in api.h. Note that
385  * some of these preferences are not available to the user.
386  *
387  * @see PreferenceInfo
388  */
389  std::shared_ptr<PreferenceInfo> getPreferences();
390 
391  /**
392  * Method for retrieving the current number of available user preferences.
393  * This method provides an optimized means of determining if there are any available user
394  * preferences. An application may have no need to retrieve the user preferences if there are
395  * no user preferences available, and invoking getPreferences() incurs the cost of a deep
396  * copy of the internal PreferenceInfo class instance, possibly causing many memory
397  * allocations, even when there are no avaiable user preferences, which could result in poor
398  * user interface responsiveness.
399  *
400  * @see PreferenceInfo
401  */
402  unsigned int getPreferencesCount();
403 
404  /**
405  * This method stores the current set values of the preferences to the
406  * preferences file(s). This method is a counterpart to the
407  * getPreferences() method.
408  */
409  bool savePreferences(const std::shared_ptr<PreferenceInfo>& spPreferenceInfo);
410 
411  /**
412  * This is called from the credential dialog in the GUI to get the correct
413  * friendly name for the dialog title.
414  */
415  tstring getConnectHost();
416 
417  /**
418  * This method sets the last VPN error seen during this connection
419  * attempt for reporting purposes. This VPN error should be cleared for
420  * each connection attempt.
421  */
422  void setLastVpnError(VPNError vpnError);
423 
424 
425  /**
426  * This method gets the last VPN error seen during this connection
427  * attempt for reporting purposes. This VPN error should be cleared for
428  * each connection attempt.
429  */
430  VPNError getLastVpnError();
431 
432  /**
433  * This method indicates if a request to connect has been initiated and the SG is being
434  * contacted. Note: the connect request is not active while waiting for the user to enter
435  * credentials.
436  */
437  bool isConnectRequestActive();
438 
439  private:
440 
441  //
442  //
443  // Private Member Methods
444  //
445  //
446 
447  // Prevent copying by declaring but not defining copy constructor and operator= methods.
448  //
449  ClientIfc(const ClientIfc& other);
450  ClientIfc& operator=(const ClientIfc& other);
451 
452 #if defined(VPNAPI_EVENT_NOTIFICATION_SUPPORTED)
453  virtual void EventNotificationInternalCB(
454  const std::shared_ptr<CEventNotificationTlv>& spEventNtfctnTlv);
455 #endif
456 
458 
459  //
460  //
461  // Private Member Data
462  //
463  //
464 
465  ClientIfcData* const m_pClientIfcData;
466 };
467 
468 #endif //_CLIENTIFC_
Definition: ClientIfcBase.h:59
#define tstring
Definition: api.h:35
Definition: ClientIfc.h:42
OperatingMode
Definition: api.h:534
VPNError
Definition: api.h:586
virtual void EventNotificationInternalCB(const std::shared_ptr< CEventNotificationTlv > &spEventNtfctnTlv)=0
void ClientIfcTransmigration()