public class

GenericVpnService

extends Service
java.lang.Object
   ↳ android.content.Context
     ↳ android.content.ContextWrapper
       ↳ android.app.Service
         ↳ com.samsung.android.knox.net.vpn.serviceprovider.GenericVpnService

Class Overview

The class provides APIs to create and establish multiple virtual interface tunnels per user. Please refer to Android`s VpnService documentation for further details on VPN solution creation. Following are some key points:

  • VPN clients can integrate with Knox VPN framework either by using the VPN service provided by Android (prepare function needs to be called with GenericVpnContext) or by using GenericVpnService.
  • When establishing the VPN connection for a Knox profile, set the setSession value of the VpnService.Builder class to the profile name of the connection.
  • When establishing the VPN connection for Knox profile, the addRoute value of the VpnService.Builder class will be set to null by default.
  • GenericVpnService is almost replica of Android`s VpnService and it facilitates to create multiple interfaces.

Since
API level 9
KNOX 1.1.0

Summary

Nested Classes
class GenericVpnService.Builder Helper class to create a VPN interface. 
Constants
String SERVICE_INTERFACE The action must be matched by the IntentFilter of this service.
[Expand]
Inherited Constants
From class android.app.Service
From class android.content.Context
From interface android.content.ComponentCallbacks2
Public Constructors
GenericVpnService()
Public Methods
IBinder onBind(Intent intent)
Return the communication interface to the service.
void onRevoke()
Invoked when the application is revoked.
static Intent prepare(Context context, String profile, boolean type, boolean isConnecting)
Prepare to establish a VPN connection.
boolean protect(Socket socket)
Convenience method to protect a Socket from VPN connections.
boolean protect(int socket)
Protect a socket from VPN connections.
boolean protect(DatagramSocket socket)
Convenience method to protect a DatagramSocket from VPN connections.
[Expand]
Inherited Methods
From class android.app.Service
From class android.content.ContextWrapper
From class android.content.Context
From class java.lang.Object
From interface android.content.ComponentCallbacks
From interface android.content.ComponentCallbacks2

Constants

public static final String SERVICE_INTERFACE

Since: API level 29

The action must be matched by the IntentFilter of this service. It also needs to require BIND_VPN_SERVICE permission so that other applications cannot abuse it.

Constant Value: "android.net.VpnService"

Public Constructors

public GenericVpnService ()

Since: API level 9

Public Methods

public IBinder onBind (Intent intent)

Since: API level 9

Return the communication interface to the service. This method returns null on Intents other than SERVICE_INTERFACE action. Applications overriding this method must identify the Intent and return the corresponding interface accordingly.

Parameters
intent The Intent that was used to bind to this service.
Returns
  • The communication interface to the service.
Since
API level 9
KNOX 1.1.0

public void onRevoke ()

Since: API level 9

Invoked when the application is revoked. At this moment, the VPN interface is already deactivated by the system. The application should close the file descriptor and shut down gracefully. The default implementation of this method is calling stopSelf().

Calls to this method may not happen on the main thread of the process.

Since
API level 9
KNOX 1.1.0

public static Intent prepare (Context context, String profile, boolean type, boolean isConnecting)

Since: API level 9

Prepare to establish a VPN connection. Following is the explanation of prepare API in context of system VPN. This method returns null if the VPN application is already prepared. Otherwise, it returns an Intent to a system activity. The application should launch the activity using startActivityForResult to get itself prepared. The activity may pop up a dialog to require user action, and the result will come back via its onActivityResult. If the result is RESULT_OK, the application becomes prepared and is granted to use other methods in this class.

Only one application can be granted at the same time. The right is revoked when another application is granted. The application losing the right will be notified via its onRevoke(). Unless it becomes prepared again, subsequent calls to other methods in this class will fail. In case of per application VPN, the function can be called before establish and can be called at the end to destroy the connection based on profile name.

Parameters
context Context of the VPN Application trying to bind to Knox Framework.
profile Name of the VPN Connection.
type True: if the profile is system VPN; false: if the profile is per-app VPN.
isConnecting True: for starting the VPN connection; false: for stopping a VPN connection.
Returns
  • Null if the VPN application is already prepared. Otherwise, it returns an Intent to a system activity.
Since
API level 9
KNOX 1.1.0
See Also

public boolean protect (Socket socket)

Since: API level 9

Convenience method to protect a Socket from VPN connections.

Parameters
socket The socket that will be protected from VPN connections.
Returns
  • True on success.
Since
API level 9
KNOX 1.1.0
See Also

public boolean protect (int socket)

Since: API level 9

Protect a socket from VPN connections. The socket will be bound to the current default network interface, so its traffic will not be forwarded through VPN. This method is useful if some connections need to be kept outside of VPN. For example, a VPN tunnel should protect itself if its destination is covered by VPN routes. Otherwise its outgoing packets will be sent back to the VPN interface and cause an infinite loop. This method will fail if the application is not prepared or is revoked.

The socket is NOT closed by this method.

Parameters
socket The socket that will be protected from VPN connections.
Returns
  • True on success. Parameter required for protect.
Since
API level 9
KNOX 1.1.0

public boolean protect (DatagramSocket socket)

Since: API level 9

Convenience method to protect a DatagramSocket from VPN connections.

Parameters
socket The socket that will be protected from VPN connections.
Returns
  • True on success.
Since
API level 9
KNOX 1.1.0
See Also