|
AnyConnect Secure Mobility Client 4.1.06020
|
The API is fully integrated into the AnyConnect environment. This includes the use of SBL, CSD and web launch
There are several points of interest with the API that GUI programmers should be aware of. The main area of concern will be using the appropriate Event Model. For additional information see the Event Models section.
Other topics of interest related to GUI and the features that are available include:
A GUI program can further integrate with the AnyConnect API by taking advantage of available Window Managaement Hints. These hints will, for various reasons, instruct the GUI to OPEN, QUIT or MINIMIZE. For a complete list see WMHint. For integration into a GUI program, see the ClientIfc::WMHintCB method.
Only signed binaries work as expected when integrated into the AnyConnect environment. A number of the AnyConnect feature implementations work only when the GUI program is signed.
If the AnyConnect software determines that an upgrade of its software is required, any currently running GUI will be terminated as part of the upgrade process. The upgrade process will be preceeded by a running GUI being sent a WMHint to QUIT. If this hint is ignored, the GUI will be forcibly killed.
Once the updated software has been installed, the GUI will be automatically restarted. This restart requires that the GUI follow both Program Naming and Program Signing conventions.
See the section Cisco Secure Desktop under Program Arguments for details on Cisco Secure Desktop integration.
This capability is available to Windows based GUI programs. This functionality will allow a GUI program to start and activate a VPN prior to the Windows logon.
Using Start Before Logon requires that the Program Naming conventions as well as Program Signing be followed.
With the API, the name of the application binary must be the same as the currently supplied AnyConnect GUI. Further, the binary must be installed into the application directory used by the AnyConnect software. This overwrites the AnyConnect GUI supplied by Cisco. If the binary is imported into ASDM, it is automatically installed into the mentioned location.
A GUI that does not use the current vpnui.exe does work and can be installed. It cannot however take advantage of the integration previously described. In addition, the existing AnyConnect GUI is still used during the integration events mentioned if it is not removed from the system.
The API supports a special mode of processing called Start Before Logon (SBL). In this model the GUI (vpnui.exe) is launched by a special windows program (GINA on Windows XP and PLAP on VISTA). This program allows the GUI program to run prior to the windows login, enabling a VPN tunnel to be established. Once the tunnel is established, the normal Windows login will continue.
For this mode to work with a client GUI program, the GUI Program should recognize the program argument -sbl. This argument is passed by Windows when the AnyConnect GINA or PLAP component is installed. In addition, the argument occurs only when the user is logging in using <ctrl><alt><del> keyboard sequence.
The GUI client program recognizing this command line argument should use it to configure the API ClientIfc::attach method. Specifically, the SBL argument for the attach method should be set to true. Setting this argument enables the API to work correctly when it is invoked as part of a pre-login sequence.
As noted previously, the GUI used in this mode of operation must be signed for it to be started.
The Cisco Secure Desktop (CSD) environment has various options and capabilities. The API manages all of these for the client program. One mode of operation with CSD is referred to as the vault which s an option within Secure Desktop.
When this option is used, the GUI detects it (handled by the API) and exits automatically. Once the vault environment has started, the GUI is re-launched. When it is re-launched, a command line argument is passed to the GUI program.
To complete the GUI restart once the Secure Desktop vault has been started, CSD launches the GUI with additional parameters. These parameters must be used as part of the subsequent connect method call. The two parameters are -connect and -connectparam.
These two parameters must be combined and passed to the connect method. For example, the value for -connect may be hosta.xyz.com and for connectparam #csd123. The value passed to the connect method would then e hosta.xyz.com#csd123.
There are cases where the GUI can be launched automatically. Once such case is as part of a WEB-based launch. In this mode, the VPN is started using a web page. After the VPN is active, the GUI is started. As part of this mode, the program argument -autolaunched is passed to the program. This argument can be used to indicate to the GUI that it should start minimized as opposed to opening on the desktop.
This launch capability requires the GUI to follow both Program Naming and Program Signing requirements.
A third party GUI can take advantage of localization capabilities provided via the AnyConnect API. Localized string are available via labels associated with PromptEntry objects (see PromptEntry::getPromptLabel). In addition, all notices (see ClientIfc::NoticeCB) and banner (see ClientIfc::BannerCB) can be localized. Finally, statistics labels (see VPNStats::getTranslatedLabel) can also be localized.
See the AnyConnect Release notes for additional details on localization and how to manage for AnyConnect.
Global proxy settings are supported on Windows only. These can be used for service-based implementations of the AnyConnect client. The preferences file defining the proxy settings goes in the C:\Documents and Settings\All Users\Application Data\Cisco\Cisco AnyConnect VPN Client\ directory on Windows machines.
Two examples are available with the API bundle. One is a CLI and the other a GUI. The code for these can be found in example/CLI and example/GUI.
The example code is tied to the documentation for quick referencing. An example of this linkage can be seen by viewing the ClientIfc class. For some of the methods, the text Implemented in CLIClientImpl will provide a link to example code implementing the described method.