Implementation

The Knox VPN Framework is based on the Android VpnService. Samsung’s GenericVpnContext extends this class and adds features to enhance your VPN client beyond standard Android’s offerings.

Classes

Requirements

1. Review the VPN security requirements.
2. Create your VPN client.

How it works

Here are the general steps to get a Knox VPN client working.

1. Create your VPN client, using Android’s VpnService.

2. Pass Knox’s GenericVpnContext as part of the prepare() call, such as:

   • Profile name
   • Implementing UID/PID meta headers
   • Whether you’re preparing to start or stop the connection

3. Pass the profile name as the session name as part of the establish() call.

4. Implement required GenericVpnService calls.

Create VPN client

There are two main classes that you can choose from to develop your VPN solution: Android’s VpnService and Knox’s GenericVpnService.

We recommend you extend Android’s VpnService and pass in any extra parameters using GenericVpnContext

VpnService

This helps support backward compatibility for previous versions of Android. GenericVpnService is proprietary to Samsung, and may not function across all Android OEM devices.

Using VpnService provides the following benefits:

• Compatibility: Using Androids core VPN architecture, ensures your VPN client is compatible across more devices.
• Maintainability: The version number across your 2 clients will stay in sync – your Knox client and regular Android client version can be the same, while their logic is trivially different.

See the following Android topics for detailed information on creating a VPN client.

• Add a service
• Prepare a service
• Connect service

GenericVPNService

Using GenericVpnService is only recommended if you need to support older Knox devices (e.g Knox 2.0). Skip this section if this does not apply to you.

The only difference between Android’s VpnService and Knox’s GenericVpnService are the parameters that are passed to their prepare() methods.

• VpnService's prepare() signature: is: public static Intent prepare(Context context)
• GenericVpnService's prepare() signature is: public static Intent prepare(Context context, String Profile, boolean type, boolean isConnecting)

The GenericVpnService prepare() method uses its parameters as follows:

• context — Internally used to identify caller package, caller ID, and so on.
• profile — Keep track of Knox VPN profile name.
• type — Identify if the VPN that corresponds to the profile name is a system VPN or a per-application VPN.
• isConnecting — Specify the call to prepare() is to create a new VPN connection or to terminate an existing VPN connection.

Considerations

• Call prepare() with isConnecting set to TRUE to start a new VPN connection.
• Call prepare() with isConnecting set to FALSE to try to disconnect from a VPN connection that was previously started.
• The calling sequence of the GenericVpnService APIs is the same order as those from VPNService.

Implementation considerations

IKnoxVpnService interface

The IKnoxVpnService interface defines how a VPN client and the Knox SDK communicate with each other.

• You must implement these IKnoxVpnService interfaces if your client needs to be a managed and configured by an MDM. An MDM can the configure the client remotely, bypassing any configuration interaction with the end-user.
• You do not need to implement the IKnoxVpnService interface, if your client only needs to configured by an end use (for example, manually configured on a phone)

All of the IKnoxVpnService APIs are synchronous and return immediately. If an API involves time-consuming network operations (for example, startConnection(), stopConnection(), and removeConnection() ) then the API returns once the time-consuming network operation is initiated.

Your VPN client should have an intent declared in the manifest of the framework to bind, where the name of the intent action is the package name followed by " .BIND_SERVICE “. For example, the manifest entry is as follows, where " ${PACKAGENAME} " is the package name of your framework:

<intent-filter>  <action  android:name="${PACKAGENAME}.BIND_SERVICE "/>  </intent-filter>

In addition, make sure that the call is coming from the Knox networking framework (that is, ensure that the calling UID has the value Process.SYSTEM_UID ).

The Security Requirements Guide compliance details are available in Security requirements for the following API:

setServerCertValidationUserAcceptanceCriteria(String profileName, boolean enableValidation, in List<String> condition, int frequency);

Define the configuration profile

Your client must use JSON to define it’s VPN configurations. An example is provided below, however, you must define what parameters you need in order to satisfy your specific VPN requirements.

"KNOX_VPN_PARAMETERS": {
   "profile_attribute": {
        "profileName": "planet", 
        "host": "66.7.251.72", 
        "vpn_type": "ipsec", 
        "vpn_route_type": 1
        },
    "knox": {
        "uidpid_search_enabled": 0,
        "chaining_enabled": -1,
        "ConnectionType": "keepon"
        },
    "vendor": {
    }
}

Integrating with UID/PID support

You can gather per-packet UID and PID metadata information with your VPN client. This can be done if meta data information is set with GenericVpnContext and passed to the VPN prepare() call.

As a result of enabling this feature, each IP packet received by the network app client is prepended by 8-bytes of metadata, which consists of a 4 byte UID, followed by a 4 byte PID.

Auto-reconnect

When a VPN connection fails due to certain networking issues, you can have your client automatically try to reconnect. These situations include timeouts, lack of response from server, client disconnected from server, and so on. To support auto-reconnection you must use setAutoRetryOnConnectionError() from the IKnoxVpnService.

This API can also be used in an MDM to allow an Admin to enable or disable auto-reconnect. When enabled, automatic reconnection attempts are made periodically.

Automatic attempts to reconnect are not made in the following situations:

• Invalid configuration
• Missing user certificate
• Authentication failure
• Other configuration or connectivity failures

The VPN client user can manually attempt to reconnect at any time.

User Interface Guidelines

For best results in managed scenarios, you should try to avoid the need for any user interaction, which can hinder some Knox VPN features. For example, the auto-reconnect feature works best when it doesn’t require the user to tap a button to restore the connection.

Some general client UI recommendations are:

• Either only require a EULA to be accepted during installation, or integrate the VPN EULA with the EULA displayed by the MDM
• Avoid requiring the user to enter their username and password each time they connect; consider securely storing and using their credentials

Security Guidelines

This section provides a set of security guidelines that you should follow when designing and implementing your solution.

• We highly recommend that you use the Knox Client Certificate Manager (CCM) to store and manage client certificates. The Knox CCM uses Trusted Boot and ARM TrustZone hardware to ensure that certificate and key operations are secure.
• Use FIPS-compliant libraries for cryptographic operations.
• Be very diligent when managing user credentials and passwords, even though this may conflict with the user interface guideline to minimize user interaction. Use your best judgement to balance between security and the user and MDM experience.

Multi-user support

A VPN can be installed inside the Knox Workspace, or on the personal side. They can operate independently and each client only receives traffic for that profile. The Knox VPN framework ensures the segregation of API calls between profile.

All UI-related activities are only shown to the persona to which the activity applies. This includes the client GUI, pop-up dialogs, notifications, and so on. All notifications are synced across the main user and all profiles.