In a former blog article I explained the two different user interfaces of the NetScaler Access Gateway plug-in. As outlined in that article already, my client was not satisfied with the look and feel of the software interface and asked for something more flexible and extensible (e.g. running certain programs depending on the tunnel being up or not).

In order to accommodate this and similar requests, Citrix provides a shared Access Gateway client API library for third party application integration. The shared library is located in the client’s installation folder (e.g.: C:\program files\Citrix\Secure Access Client\). The file name of the C++ library is nscltapi.dll. It exports the following functions to be used in any 3rd party code:

  • login
  • logout
  • connected
  • setproxy

This blog post is not intended to cover all details about the API but to give you an overview how you can use it to create your own solution and/or what to ask Citrix Consulting for when the need arises. Using the below code snippets, adding a few extra lines of code to make it all look prettier it took some 20 minutes to get something basic as this:

Example of basic Secure Access Client
Example of basic Secure Access Client

Below examples are written in C# code. Outlined are the basic steps to introduce the exported functions from the Citrix API DLL to your project. After you told your environment that unmanaged code will be used within the project through this instruction,

using System.Runtime.InteropServices;

you can start importing the functions you need and use them afterwards. In the following, the four functions and a quick example on how you may use them will be documented. Not following best practices on how to import a DLL to your project I reference the library with its full path instead of importing it to the project. For your project I suggest to do it right from the beginning 🙂

Function: login

This API function is exported to log in to the NetScaler Access Gateway. It expects the following parameters:

  • FQDN
  • Username
  • Password

The shared library defines the function as follows:

int  login(char * url, char * username, char * password)

The function returns either a positive integer value indicating a successful tunnel initialization (the return value is then also the id for your VPN session) or it returns a value <=0. The relevant error codes are listed below

return value meaning
-1 Invalid input parameters
-2 Agent is not installed
-3 Agent could not be launched
-4 Agent port not detected
-5, -6, -7 Sending login to agent failed
-8 Agent is upgrading
-9 Agent did not send valid login reply
-10 Memory allocation failure
-11 Login failed because forward proxy requires credentials and credential prompting in client is turned off.

Example in C#

[DllImport (“C:/Program Files/Citrix/Secure Access Client/nscltapi.dll”)]
private static extern int login (String URL, String Username, String Password);
int SessionID = login(“https://myagee.example.com”, “David”, “Citrix123”);

Function: logout

This API function is exported to logout from the SSL VPN. It expects the parameters

  • SessionID
  • Flag

where “SessionID” is the value returned from API login function and “Flag” sets the way the client is going to logout. Possible options are:

0: logout silently without warning prompt.
2: exit without prompt.
4: logout with prompt.
6: exit with prompt.

The shared library defines the function as follows:

int  logout(int sessionid, int flag)

For a successful disconnect the logout function return 1, for a failure during logout it reports 0 back to the invoking context.

Example in C#

[DllImport (“C:/Program Files/Citrix/Secure Access Client/nscltapi.dll”)]
private static extern int logout (int SessionID, int flag);
int logout_flag = 0;
int logged_out = logout (SessionID, logout_flag);

Function: connected

This API function is exported to check the status of SSL VPN session. It has no parameters but returns whether or not the Access Gateway plug-in is connected.

Return values are expeted:

0: Not connected to SSL VPN.
1: Connected to SSL VPN.

The shared library defines the function as follows:

int  connected()

Example in C#

[DllImport (“C:/Program Files/Citrix/Secure Access Client/nscltapi.dll”)]
private static extern int connected ();
int status = connected();

Function: setproxy

The setproxy function is used to set forward proxy information for the VPN connection.

Forward proxy information lives during the time the shared library is loaded. If the shared library has been unloaded while the program runs, the proxy has to be reset again.

It expects the parameters

  • Proxy address
  • Proxy dialog
  • Authentication method

The shared library defines the function as follows:

int  setproxy(char * proxy, int proxydlg, int prefermethod))

Possible formats for the proxy address are:

  1. domain
  2. ipaddress
  3. domain:port
  4. ipaddress:port
  5. domain:port:username:password
  6. ipaddress:port:username:password

Possible options for the proxy dialog, meaning whether to turn on/off the SSL VPN client dialog window for setting the forward proxy credentials:

0: turn on SSL VPN client prompt for forward proxy credentials. (default)
1: turn off SSL VPN client prompt for forward proxy credentials.

Possible methods for the proxy authentication are:

0: Pickup the first available choice from forward proxy returned list. Default.
1: preferred authentication method BASIC
2: preferred authentication method DIGEST
3: preferred authentication method NTLM

The functions returns “0” when setting the forward proxy information failed. This typically happens when the proxy string is longer than the allowed maximum 256 bytes. The value 1 is returned when the forward proxy information is set successfully.

Example in C#

[DllImport (“C:/Program Files/Citrix/Secure Access Client/nscltapi.dll”)]
private static extern int setproxy (String proxy_address, int proxy_dialog, int proxy_method);
int proxy_defined = setproxy (“192.168.0.1:8080”, 0, 0);

With these four functions from the client API of NetScaler Access Gateway it’s relatively easy to implement custom login utilities for very specific use cases. If the above description and examples aren’t of much help for you (despite my best intention), but you need to implement a solution where this API might be useful, please contact Citrix Consulting for guidance on how to use the provided library or of course find other possible ways to accomplish your task at hand.

This code is provided to you “as is” with no representations, warranties or conditions of any kind. You may use and distribute it at your own risk. CITRIX DISCLAIMS ALL WARRANTIES WHATSOEVER, EXPRESS, IMPLIED, WRITTEN, ORAL OR STATUTORY, INCLUDING WITHOUT LIMITATION WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NONINFRINGEMENT. Without limiting the generality of the foregoing, you acknowledge and agree that (a) the software application may exhibit errors, design flaws or other problems, possibly resulting in loss of data or damage to property; (b) it may not be possible to make the software application fully functional; and (c) Citrix may, without notice or liability to you, cease to make available the current version and/or any future versions of the software application. In no event should the code be used to support of ultra-hazardous activities, including but not limited to life support or blasting activities. NEITHER CITRIX NOR ITS AFFILIATES OR AGENTS WILL BE LIABLE, UNDER BREACH OF CONTRACT OR ANY OTHER THEORY OF LIABILITY, FOR ANY DAMAGES WHATSOEVER ARISING FROM USE OF THE SOFTWARE APPLICATION, INCLUDING WITHOUT LIMITATION DIRECT, SPECIAL, INCIDENTAL, PUNITIVE, CONSEQUENTIAL OR OTHER DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. You agree to indemnify and defend Citrix against any and all claims arising from your use, modification or distribution of the code.