Android Interface Definition Language (AIDL)
The AIDL file used to define the client interface is named IVpnProfile.aidl and contains the following:
package net.pulsesecure.pulsesecure.vpnprofile;//Package name updated in API version 3.
interface IVpnProfile {
int doCommand(String commandXML); //deprecated
int getVersion();
// The following methods were added in API version 2.
int createConnection(String jsonProfile);
int removeConnection(String profileName);
List<String> getAllConnections();
String getConnection(String profileName);
int startConnection(String profileName);
int stopConnection(String profileName);
int getState(String profileName);
String getErrorString(String profileName);This file must be included in the src/ directory used to compile the application. For more information about the AIDL, go to aidl.html.
Service intent filter action name
Use below action name to bind to service implementing this API. Updated in API version 3.
"net.pulsesecure.pulsesecure.vpnprofile.IVpnProfile"JSON String Format for createConnection
The createConnection method, new in version 2 of the API, accepts a VPN profile described in a JSON string format.
The JSON strings vary depending on the type of authentication used in the VPN profile, as shown in the following examples.
Single Username/Password Authentication
The following sample JSON string is for a VPN profile that uses a username/password for authentication:
{
"MDM_VPN_PARAMETERS": {
"profile_attribute": {
"profileName":"MyVpnProfile",
"host":"https://vpn.xyz.com/auth",
"vpn_type":"ssl",
"isUserAuthEnabled":true
},
"ssl": {
.. "basic": {
"username":"testuser",
"password":"secret123"
}
},
"vendor": {
"realm":"",
"role":"",
"certAlias":""
}
}
}Certificate Authentication
The following sample JSON string is for a VPN profile that uses a certificate for authentication:
{
"MDM_VPN_PARAMETERS": {
"profile_attribute": {
"profileName":"MyVpnProfile",
"host":"https://vpn.xyz.com/auth",
"vpn_type":"ssl",
"isUserAuthEnabled":true
},
"ssl": {
"basic": {
}
},
"vendor": {
"realm":"",
"role":"",
"certAlias":"myCertName"
}
}
}The certificate must be installed in Android’s keystore before this profile can be used. The certificate name is specified in the certAlias field in the vendor section.
Username/Password and Certificate Authentication
The following sample JSON string is for a VPN profile that uses both certificate and username/password for authentication:
{
"MDM_VPN_PARAMETERS": {
"profile_attribute": {
"profileName":"MyVpnProfile",
"host":"https://vpn.xyz.com/auth",
"vpn_type":"ssl",
"isUserAuthEnabled":true
},
"ssl": {
"basic": {
"username":"testuser",
"password":"secret123"
}
},
"vendor": {
"realm":"",
"role":"",
"certAlias":"myCertName"
}
}
}Dual Username/Password Authentication
The following sample JSON string is for a VPN profile that uses two usernames/passwords for authentication:
{
"MDM_VPN_PARAMETERS": {
"profile_attribute": {
"profileName":"MyVpnProfile",
"host":"https://vpn.xyz.com/auth",
"vpn_type":"ssl",
"isUserAuthEnabled":true
},
"ssl": {
"basic": {
"username":"testuser",
"password":"secret123"
}
},
"vendor": {
"realm":"",
"role":"",
"username2":"testuser2",
"password2":"passwd123"
}
}
}The primary username/password are specified in the ssl section and the secondary username/password are specified in the vendor section.
XML Command Format for doCommand (Deprecated)
Many commands are specified by the commandXML argument of the interface doCommand. For a single command, the general format is:
<command>
<commandName>command</commandName>
<param1>value1</param1>
<param2>value2</param2>
// additional parameters for the command
</command>Any parameter that is specified with an empty value is ignored.
The commandXML argument should specify a single command. However, multiple commands can be specified as follows:
<commands>
<command>
.
.
.
</command>
<command>
.
.
.
</command>
</commands>Multiple commands are executed in the order specified, and execution stops on the first error. The doCommand method returns a negative integer if an error occurs on the first command; otherwise, the number of commands executed successfully is returned. If an error occurs after the first command, it is logged in the Pulse client log.
Return Codes for doCommand
The doCommand method returns a negative integer if an error occurs or a positive value (1 or higher) to indicate the number of commands executed successfully. The following table lists all of the possible return codes.
Return Code | Description |
|---|---|
1 or n | Number of commands executed successfully |
-1 | COMMAND_EXECUTION_ERROR |
-2 | COMMAND_UNKNOWN |
-3 | KEY_OR_CERT_UNEXPECTED |
-4 | KEY_OR_CERT_MISSING |
-5 | PROFILE_DELETE_FAILED |
-6 | PROFILE_UPDATE_FAILED |
-7 | PROFILE_ADD_FAILED |
-8 | PROFILE_NOT_FOUND |
-9 | PROFILE_ALREADY_EXISTS |
-10 | COMMAND_XML_INVALID |
-11 | COMMAND_NOT_SUPPORTED |
-12 | CALLER_NOT_VERIFIED |
-13 | CALLER_NOT_IDENTIFIED |
-14 | CERT_ALIAS_NOT_FOUND_IN_KEYSTORE |
-15 | INCORRECT_BASE64_KEY_OR_CERT |
-16 | INCORRECT_KEY_OR_CERT_FILE |
-17 | DUPLICATE_KEY_OR_CERT_ENTRIES |
-18 | REQUIRED_PARAMETER_MISSING |
-19 | CHECK_PROFILE_URL_MISMATCH |
-20 | CHECK_PROFILE_USERNAME_MISMATCH |
-21 | CHECK_PROFILE_REALM_MISMATCH |
-22 | CHECK_PROFILE_ROLE_MISMATCH |
-23 | CHECK_PROFILE_CERT_PATH_MISMATCH |
-24 | CHECK_PROFILE_KEY_PATH_MISMATCH |
-25 | CHECK_PROFILE_CERT_ALIAS_MISMATCH |