AnyConnect Secure Mobility Client  5.1.2.42
ClientIfcBase.h
1 /**************************************************************************
2 * Copyright (c) 2006, 2021-2023 Cisco Systems, Inc.
3 * All Rights Reserved. Cisco Highly Confidential.
4 ***************************************************************************
5 *
6 * File: ClientIfcBase.h
7 * Author: Chris Fitzgerald
8 * Date: 08/2007
9 *
10 ***************************************************************************
11 * Client Interface Base class implementation for the Client API.
12 ***************************************************************************/
13 
14 #ifndef _CLIENTIFCBASE_
15 #define _CLIENTIFCBASE_
16 
17 #include <list>
18 #include <vector>
19 #include <memory>
20 
21 #include "ClientIfcCommon.h"
22 #include "api.h"
23 
24 #if defined(ANYCONNECT_USE_SNAK)
25 #include "SNAK_CertPlugin.h"
26 #endif
27 
28 #if defined(HOST_DATA_SUPPORTED)
29 class IHostData;
30 #endif
31 
32 class ConnectPromptInfo;
33 class MsgWithArg;
34 class VPNStats;
35 class PreferenceInfo;
36 class ProxyIfc;
37 class CIpcMessage;
38 class CertObj;
39 class HostEntry;
40 class ClientIfcInternal;
41 
42 #if defined(VPNAPI_EVENT_NOTIFICATION_SUPPORTED)
43 class CEventNotificationTlv;
44 #endif
45 
46 #if defined(CREDENTIAL_PREFILL_SUPPORTED)
47 class CredentialPrefill;
48 #endif
49 
50 #if (defined(ANYCONNECT_USE_SNAK) || defined(PLATFORM_APPLE_SSLVPN)) && !defined(PLATFORM_WIN_APP)
51 class ManagedCertificate;
52 #endif
53 
54 #if defined(PROGRAM_DATA_IMPORT_SUPPORTED)
55 class IACImporterAsync;
56 class IACImporterAsyncCB;
57 #endif
58 
59 class VPN_VPNAPI ClientIfcBase
60 {
61  friend class EventMgr;
62  friend class ClientIfcInternal;
63 
64  protected:
65 
66  ClientIfcBase();
67  virtual ~ClientIfcBase();
68 
69  /**
70  * Callback used to deliver new statistics related to the VPN
71  * connection.
72  *
73  * When a connection is active, a new set of statistics is
74  * delivered each second.
75  *
76  * @see resetStats(), stopStats() and startStats()
77  *
78  */
79  virtual void StatsCB(VPNStats &stats) = 0;
80 
81 
82  /**
83  * Callback used to deliver VPN state and state change string.
84  * The stateString delivered by this method is localized.
85  *
86  * See the ::VPNState enum found in api.h for set of valid states.
87  */
88  virtual void StateCB(const VPNState state,
89  const VPNSubState subState,
90  const tstring stateString) = 0;
91 
92 
93  /**
94  * If a banner needs to be acknowledged, this CB delivers the banner
95  * to the client.
96  *
97  * NOTE: Connection establishment will block until the method
98  * setBannerResponse() is called.
99  *
100  * In a GUI, a banner would typically be displayed in a modal dialog
101  * with an accept or decline button selection.
102  *
103  * @see setBannerResponse() to set the user response to the banner.
104  */
105  virtual void BannerCB(const tstring &banner) = 0;
106 
107  /**
108  * If a pre-connect reminder needs to be acknowledged, this CB delivers
109  * the pre-connect reminder to the client.
110  *
111  * NOTE: Connection establishment will block until the method
112  * setPreConnectReminderResponse() is called.
113  *
114  * In a GUI, a pre-connect reminder would typically be displayed in a modal
115  * dialog with an OK button selection.
116  *
117  * @see setPreConnectReminderResponse() to set the user acknowledgement to
118  * the pre-connect reminder message.
119  */
120  virtual void PreConnectReminderCB(const tstring &rtstrPreConnectReminder);
121 
122  /**
123  * Messages are delivered via the NoticeCB and can come from multiple
124  * sources. There are four message types (error, warning, info and
125  * status). See the ::MessageType enum in api.h for the list.
126  *
127  * Clients using the API as an embedded application (not
128  * user visible) might want to further characterize
129  * messages. One option here is to use the AnyConnect message
130  * catalog and assign message codes as the translations for
131  * various messages. An application could then track messages based
132  * on its own error code scheme.
133  */
134  virtual void NoticeCB(const tstring &notice,
135  const MessageType type,
136  const bool bSensitive = false) = 0;
137 
138 #if defined(PLATFORM_APPLE_SSLVPN) || defined(PLATFORM_ANDROID) || defined(PLATFORM_CHROMEBOOK)
139  virtual void CertBannerCB(const tstring &certBannerSummary,
140  const uint32_t nCertBannerCertLen,
141  const uint8_t *pCertBannerCertDer,
142  const std::list<tstring> &confirmReasons,
143  const std::list<CertConfirmReason> &confirmReasonEnums,
144  bool bImportAllowed = true) = 0;
145 #endif
146 
147  /**
148  * This CB would likely occur only during a connection when it was
149  * detected that the software needed to be upgraded, or when Start
150  * Before Logon (SBL) is being used.
151  *
152  * Unlike the other callback methods, this method provides a default
153  * implementation (calling the system's exit() function).
154  * If clients of the API wish to override this behavior, they are
155  * responsible for ensuring that the current running process exits with
156  * the return code specified by returnCode.
157  *
158  * <b>Caution</b>: IF YOU OVERRIDE THIS METHOD AND DO NOT EXIT WITH
159  * THE PROPER CODE SOFTWARE UPDATE FUNCTIONALITY IN YOUR CLIENT WILL
160  * BREAK
161  */
162  virtual void ExitNoticeCB(const tstring &tstrNotice,
163  const int returnCode);
164 
165 
166  /**
167  * Under normal operating conditions, this CB is called as soon
168  * as the attach method completes. In case the service (vpn agent)
169  * is not ready, this CB is not called until it is.
170  *
171  * Any API calls made prior to this CB being called will result in a
172  * NoticeCB error message.
173  */
174  virtual void ServiceReadyCB() = 0;
175 
176 
177 
178  /**
179  * This method supports prompting for single or multiple values. All
180  * prompts are considered mandatory.
181  *
182  * The ConnectPromptInfo object contains a list of PromptEntry
183  * instances. The labels and their default values (if any) can be
184  * found in these instances. After the data has been collected from the user
185  * it can be set into these same instances. When ready, the client
186  * application should call the method UserSubmit() to have the
187  * responses read by the API.
188  */
189  virtual void UserPromptCB(ConnectPromptInfo &ConnectPrompt) = 0;
190 
191 
192  /**
193  * Use this method to provide Window Manager hints to GUI
194  * applications. To receive these hints, the application must
195  * identify itself as a GUI in the attach method. In addition, this
196  * method should be overridden to receive any generated events.
197  *
198  * Event that can be received include those indicating that a user is
199  * starting a second instance of the GUI application. This information
200  * can be used to tell the already running application to un-minimize
201  * itself and let the new program know that it should Quit (since a GUI
202  * is already running).
203  */
204  virtual void WMHintCB(const WMHint hint,
205  const WMHintReason reason);
206 
207 
208  /**
209  * This method is useful when the connection to the secure gateway
210  * has been established as part of a web-launch of the VPN tunnel.
211  *
212  * If the client application wishes to be notified of the secure
213  * gateway to which the VPN has been established, this method should
214  * be overridden.
215  *
216  * If the client application is started and a tunnel is already active,
217  * this method also delivers the name of the secure gateway host.
218  */
219  virtual void deliverWebLaunchHostCB(const tstring &activeHost);
220 
221  /**
222  * This method is called when the preference to block untrusted
223  * servers is enabled and the current VPN server being connected
224  * to is untrusted. Clients should present an error to the user
225  * notifying them that the current connection to rtstrUntrustedServer
226  * is being blocked. The client should also provide a way for the
227  * user to change the preference to block untrusted servers.
228  *
229  * The user response must be indicated using setCertBlockedResponse
230  */
231  virtual void CertBlockedCB(const tstring &rtstrUntrustedServer) = 0;
232 
233  /**
234  * This method is called when connections to untrusted VPN servers
235  * is allowed by policies and the current VPN server being connected
236  * to is untrusted. Clients should present a warning to the user
237  * notifying them that the current connection to rtstrUntrustedServer
238  * is unsafe. The reason the VPN server is untrusted is provided in
239  * rltstrCertErrors. The client should provide a way for the user to
240  * connect once, connect and always trust or cancel the connection.
241  * If bAllowImport is set to false then the always trust option should
242  * not be presented to users.
243  *
244  * The user response must be indicated using setCertWarningResponse
245  */
246  virtual void CertWarningCB(const tstring &rtstrUntrustedServer,
247  const std::list<tstring> &rltstrCertErrors,
248  bool bAllowImport) = 0;
249 
250 #if defined(PLATFORM_WIN_APP)
251  /**
252  * Same as above but also passes the Server certificate DER for details display
253  */
254  virtual void CertWarningCB(const tstring &rtstrUntrustedServer,
255  const std::list<tstring> &rltstrCertErrors,
256  const std::vector<uint8_t> &rvServerCertDER,
257  bool bAllowImport) = 0;
258 #endif
259 
260  /**
261  * This method should be overridden by the client application to
262  * exercise some control over the delivery of events from the other
263  * protected methods in this class.
264  *
265  * This might be necessary in cases where a GUI/CLI is being written and
266  * the data from this API needs to be delivered in the GUI/CLI or main
267  * thread. In this case, you should override this method and when it
268  * is called by the API post an event to your event queue (message
269  * pump, etc.). After this event executes in your GUI/CLI or main thread,
270  * call the method ClientIfc::ProcessEvents to have events delivered
271  * to your client application.
272  */
273  virtual void EventAvailable();
274 
275 #if defined(MANUAL_PKCS12_IMPORT_SUPPORTED)
276  virtual void ImportPKCS12ResultCB(const std::vector<uint8_t> &certHash,
277  const tstring &tstrError);
278 #endif
279 #if defined(PLATFORM_ANDROID)
280  virtual void ClientCertificateCB(std::vector< std::pair<uint32_t, uint8_t*> > certList) = 0;
281  virtual void AgentDetachedCB();
282 #endif
283 
284 #if defined(VPNAPI_EVENT_NOTIFICATION_SUPPORTED)
285  /**
286  * Internal callback between ClientIfcBase and ClientIfc.
287  */
288  virtual void EventNotificationInternalCB(
289  const std::shared_ptr<CEventNotificationTlv>& spEventNtfctnTlv) = 0;
290 #endif
291 
292 
293  /**
294  * Internal method for use by ClientIfc.
295  */
296  void ClientIfcTransmigration();
297 
298  public:
299 
300  bool attach(const ClientType clientType = ClientType_GUI,
301  const bool requestFullCapabilities = true,
302  const bool suppressAutoConnect = true,
303  const bool bSuppressEventAvailableCB = false);
304 
305  void detach();
306 
307  void ProcessEvents();
308 
309  bool hasFullCapabilities();
310 
311  bool isConnected(bool bSilent = false);
312 
313  bool isAvailable();
314 
315  std::list<tstring> getHostNames();
316 
317  std::list<HostEntry> getHostEntries();
318 
319  tstring getDefaultHostName();
320 
321  bool connect(
322 #if defined(HOST_DATA_SUPPORTED)
323  const IHostData& host);
324 #else
325  tstring host);
326 #endif
327 
328  bool connect(
329 #if defined(HOST_DATA_SUPPORTED)
330  const IHostData& host,
331 #else
332  tstring host,
333 #endif
334  unsigned int origin);
335 
336  bool setNewTunnelGroup(const tstring & group);
337 
338  void disconnect();
339 
340  void cancel();
341 
342  void resetStats();
343 
344  void getState();
345 
346  VPNState getCurrentState();
347  VPNSubState getCurrentSubState();
348  VPNSubState getPreviousSubState();
349 
350  tstring getStateText();
351  static tstring getNoticeTypeText(MessageType msgType);
352 
353  static tstring getStateText(VPNState state,
354  VPNSubState subState = VPNSS_NORMAL,
355  NETENV_STATE netEnvState = NES_NETWORK_ACCESSIBLE,
356  const tstring& tstrConnectedHost = tstring());
357 
358  void setNetworkStates(NETENV_STATE netEnvState,
359  NETCTRL_STATE netCtrlState,
360  NETWORK_TYPE netType,
361  bool bACBrowserForCPRemediation,
362  bool bUpdateUI);
363  void refreshOperatingModeForCurrentNetStates();
364  NETENV_STATE getCurrentNetEnvState();
365  NETENV_STATE getPreviousNetEnvState();
366  NETCTRL_STATE getCurrentNetCtrlState();
367  NETWORK_TYPE getCurrentNetType();
368  bool isACBrowserForCPRemediation();
369 
370  static tstring getNetCtrlText(NETCTRL_STATE netCtrlState);
371  static tstring getNetEnvText(NETENV_STATE netEnvState,
372  bool bSimple = false);
373  static tstring getNetTypeText(NETWORK_TYPE netType);
374  static tstring getQuarantinedStatusText();
375  static tstring getNetworkStatusSimpleText(const NETENV_STATE netEnvState,
376  const NETCTRL_STATE netCtrlState);
377 
378  // can't be static due to requiring operating mode information
379  tstring getNetworkStatusText(const VPNState state,
380  const VPNSubState subState,
381  const NETENV_STATE netEnvState,
382  const NETCTRL_STATE netCtrlState);
383 
384  PreferenceInfo& getPreferences();
385 
386  bool savePreferences();
387 
388  void startStats();
389 
390  void stopStats();
391 
392  void UserSubmit();
393 
394  void setBanner(const tstring &banner);
395  void setBannerResponse(bool bResponse);
396 
397  void setPreConnectReminder(const tstring &tstrPreConnectReminder);
398  void setPreConnectReminderResponse();
399 
400  bool getUserResponse();
401  bool isUserResponseSet();
402 
403  void setCertBlocked(const tstring &tstrUntrustedServer);
404  void setCertWarning(const tstring &rtstrUntrustedServer,
405  const std::list<tstring> &rltstrCertErrors,
406  bool bAllowImport);
407 #if defined(PLATFORM_WIN_APP)
408  void setCertWarning(const tstring &rtstrUntrustedServer,
409  const std::list<tstring> &rltstrCertErrors,
410  const std::vector<uint8_t>& rvServerCertDER,
411  bool bAllowImport);
412 #endif
413  bool getCertImportResponse();
414 
415 #if defined(PLATFORM_APPLE_SSLVPN) || defined(PLATFORM_ANDROID) || defined(PLATFORM_CHROMEBOOK)
416  void setCertBanner(tstring tstrCertBannerSummary,
417  uint32_t nCertBannerCertLen,
418  const uint8_t *pCertBannerCertDer,
419  const std::list<tstring> &confirmReasons,
420  const std::list<CertConfirmReason> &confirmReasonEnums,
421  bool bImportAllowed);
422 
423  void setCertBannerResponse(bool bResponse, bool bImportCert);
424  void importServerCert(std::vector<uint8_t> certData);
425  bool setFipsMode(bool bEnableFips);
426 #if defined(PLATFORM_ANDROID)
427  bool setStrictMode(bool bEnableStrictMode);
428  bool setRevocationEnabled(bool bRevocationEnabled);
429  bool IsRevocationEnabled();
430 #endif // currently supported only for android
431 #endif
432 
433  void setUserPrompt(ConnectPromptInfo &ConnectPrompt);
434 
435 #if defined(PLATFORM_ANDROID)
436  void setClientCertResponse(std::vector< std::pair<uint32_t, uint8_t*> > &derList);
437  void setAgentDetached();
438  bool getClientCertificates();
439 #endif
440 
441 #if defined(PLATFORM_APPLE_SSLVPN) || defined(PLATFORM_ANDROID)
442  void setSCEPEnrollInProgress(bool bInProgress);
443  bool isSCEPEnrollInProgress();
444 #endif
445 
446 #if defined(MANUAL_PKCS12_IMPORT_SUPPORTED)
447  void setImportPKCS12Result(const std::vector<uint8_t> &certHash, const tstring &tstrError);
448  bool requestImportPKCS12(const std::vector<uint8_t> &data);
449  std::vector<uint8_t> importPKCS12WithPassword(const std::vector<uint8_t> &data, const tstring &password);
450 #endif
451 
452  void setCertBlockedResponse(bool bUnlock);
453  void setCertWarningResponse(bool bConnect, bool bImportCert);
454 
455  void insertStateToConnectPrompt(ConnectPromptInfo &ConnectPrompt);
456 
457  void ExitNotice(const tstring &tstrNotice, const int code = 0);
458 
459  void notice(const tstring &tstrNotice,
460  const MessageType type = MsgType_Info,
461  bool bClearLastMsg = false,
462  bool bForce = false,
463  bool bStateMsg = false,
464  bool bSensitiveMsg = false);
465 
466  void notice(MsgWithArg &notice,
467  const MessageType type = MsgType_Info,
468  bool bClearLastMsg = false,
469  bool bForce = false,
470  bool bStateMsg = false,
471  bool bSensitiveMsg = false);
472 
473  void getStats(void);
474 
475  void setStats(VPNStats &stats);
476 
477  void exportStats(const tstring &tstrFilePath);
478 
479  void initState(VPNState state,
480  VPNState previousState,
481  VPNSubState subState);
482 
483  void setState(VPNState state,
484  VPNState previousState,
485  VPNSubState subState = VPNSS_NORMAL,
486  bool bUpdateStateMsg = true,
487  bool bOnlyUpdateUI = false);
488 
489 #if defined(PROGRAM_DATA_IMPORT_SUPPORTED)
490  IACImporterAsync *createACImporter(IACImporterAsyncCB *pCallback);
491 #endif
492 
493  void setWMHint(WMHint hint,
494  WMHintReason reason);
495 
496  bool isLastConnectType (const ConnectPromptType connPromptType);
497 
498  bool isOperatingMode(OperatingMode opMode);
499  void setOperatingMode(OperatingMode opMode);
500  void unsetOperatingMode(OperatingMode opMode);
501 
502  bool CanRemediateCaptivePortal();
503  bool policyAllowsCaptivePortalRemediation();
504 
505  bool isEventShutdown();
506 
507  bool isUsingEventModel();
508 
509  time_t getLastDisconnectTime();
510 
511  ConnectPromptInfo getConnectPromptInfo();
512  void resetConnectPromptPasswordData();
513 
514  void setStandaloneConnection(bool isStandalone);
515 
516  void deliverActiveHost(const tstring &activeHost,
517  ConnectProtocolType vpnProtocol = PROTOCOL_TYPE_UNKNOWN,
518  bool bActiveHostFriendlyName = false);
519 
520  bool isVPNServiceReady();
521 
522  // reset last disconnect time indicator.
523  //
524  void resetLastDisconnectTime(time_t time = 1);
525 
526  void processMinimize();
527 
528  // cert enrollment
529  void setEnrollClientCert(CertObj* pCert);
530 
531  // Show user banner for cert import warning on linux
532  // SCEPIfc to ConnectMgr
533  void linuxCertImportWarnUser();
534 
535  // Response to cert warning on linux
536  // ConnectMgr to SCEPIfc
537  void linuxCertImportWarnUserResponse(bool bAccept);
538 
539  void setDefaultHost(tstring &host);
540 
541 #if defined(HOST_DATA_SUPPORTED)
542  void setDefaultHostProfile(const IHostData &hostProfile);
543  IHostData* getDefaultHostData();
544 #endif
545 
546  void setLastVpnError(VPNError vpnError);
547  VPNError getLastVpnError();
548 
549 #if defined(PLATFORM_ANDROID)
550  bool requestClientCertificates();
551 #endif
552 
553  bool requestImportLocalization(const tstring tstrLocale,
554  const std::vector<unsigned char> &MoFileData);
555 
556  // Start the Automatic Headend Selection operation
557  void startAHS(const unsigned int uiReason,
558  const ProxyIfc& proxy);
559  // statusReturnCode is a long to match the current type of STATUSCODE.
560  // It is not using a STATUSCODE directly so that we do not have to
561  // expose the header files for STATUSCODEs to ClientIfcBase.h
562  void AHSSelectedHost(const unsigned int uiReason,
563  const std::vector<tstring> &headendList,
564  const long statusReturnCode,
565  const tstring& extraInfo);
566  std::vector<tstring> getAHSHostList();
567  unsigned int getAHSState();
568  bool isAHSHasRun();
569  bool IsAHSCachingRestricted();
570 
571  bool suppressConnectionErrorPopups();
572 
573  tstring getCaptivePortalDetectedMsg();
574 
575  void setProxyAuthPrompts(ProxyIfc* pProxy,
576  const tstring& promptMsg);
577 
578 #if defined(INTERPROCESS_COMMUNICATION_SUPPORTED)
579  bool handleIpcMessage(CIpcMessage *pIpcMessage);
580 #endif
581  bool IsCsdTokenVerified() const;
582 
583 #if defined(PLATFORM_APPLE_SSLVPN) || defined(PLATFORM_ANDROID)
584  virtual void SCEPEnrollStartCB();
585  virtual void SCEPEnrollExitCB();
586 #endif
587 
588  void activateConnectMgrTunnelInitiationCompletionEvent();
589  bool isConnectRequestActive();
590 #if defined(PLATFORM_ANDROID) || defined(PLATFORM_CHROMEBOOK)
591  bool deleteProfileByName(const tstring &profileName);
592  tstring getProfileContents(const tstring &profileName);
593  bool importProfile(const tstring &profileName, const tstring &profileContents);
594 #endif
595 
596  bool syncProfileChange(const tstring &profileName);
597 
598 #if defined(CREDENTIAL_PREFILL_SUPPORTED)
599  bool hasPrefilledCredentials();
600  bool prefillCredentials(ConnectPromptInfo &connectPrompt);
601  void setPrefilledCredentials(CredentialPrefill *prefill);
602 #endif
603 
604 #if defined(PLATFORM_ANDROID) || defined(PLATFORM_APPLE_SSLVPN)
605  std::list<ManagedCertificate *> enumerateCertificates(CertificateType certType);
606  bool deleteCertificates(CertificateType certType, const std::list<std::string> &idList);
607  bool deleteServerCertificates(const std::list<std::string> &idList);
608 #endif
609 
610 #if defined(ANYCONNECT_USE_SNAK) && !defined(PLATFORM_WIN_APP)
611  std::list<ManagedCertificate *> enumerateSNAKCertificates(SNAK_CertType certType);
612  SNAK_CertType getSNAKCertType(CertificateType certType);
613  bool deleteClientCertificates(const std::list<std::string> &idList);
614 #endif
615 
616 #if defined(PLATFORM_APPLE_SSLVPN)
617  bool canUseBackupServers();
618 #endif
619 
620  tstring getConnectHost();
621 
622  tstring getMgmtTunnelHostname();
623 
624  VPN_TUNNEL_SCOPE getVpnTunnelScope();
625 
626  bool isStandaloneConnection();
627 
628  void sendSSoLogoutPrompt(ConnectPromptInfo &cpi);
629 
630  void setExternalSSOLogoutUrlFromAgent(const tstring& logoutUrl);
631 
632  private:
633 
634  //
635  // Private Member Data
636  //
637 
638  ClientIfcInternal* m_pClientIfcInternal;
639 
640 
641  //
642  // Private Member Methods
643  //
644 
645  // Prevent copying by declaring but not defining copy constructor and operator= methods.
646  //
647  ClientIfcBase(const ClientIfcBase& other);
648  ClientIfcBase& operator=(const ClientIfcBase& other);
649 
650 };
651 
652 
653 #endif // _CLIENTIFCBASE_
Definition: api.h:113
ConnectPromptType
Definition: api.h:233
Definition: PreferenceInfo.h:26
WMHintReason
Definition: api.h:209
VPNState
Definition: api.h:144
Definition: ClientIfcBase.h:59
#define tstring
Definition: api.h:35
WMHint
Definition: api.h:190
Definition: ConnectPromptInfo.h:37
MessageType
Definition: api.h:108
OperatingMode
Definition: api.h:534
VPNSubState
Definition: api.h:168
VPNError
Definition: api.h:586
Definition: VPNStats.h:35