NPA ISV Integration

ISV developers can integrate their apps with the NPA framework by way of the NPA APIs and AIDL interfaces. Integrated apps can then work with the data flows to help identify threats. The profile provided by the EMM determines which data flows are available, but the ISV app provides the device-level interface with the NPA framework.

Requirements

The following are required for developing the NPA client:

• The Samsung Knox SDK
• Devices running Knox 2.8 or newer
• An EMM agent which supports NPA
• The INetworkAnalyticsService.aidl file

Supported Use Cases

The NPA client is allowed to observe data flows based on whether it is installed in user 0, in profile owner, or in a Knox container. The following use cases are supported.

• Main-user wide data flow observation — The NPA client can observe data flows only from user 0 as long as the NPA client is installed in main user or user 0. The set of data flows to observe is defined by the flag parameter of the profile defined by the EMM.

• Container wide data flow observation — The NPA client can observe data flows only from the container user as long as the NPA client is installed in the container user. The set of data flows to observe is defined by the flag parameter of the profile defined by the EMM.

• Device wide data flow observation — The NPA client can observe data flows from both the main user and the container user as long as the NPA client is installed in main user or user 0. The set of data flows to observe is defined by the flag parameter of the JSON message.

The Framework Interface

This section lists the calls available to the NPA client for working with the NPA framework on the device and controlling the flow of data.

getProfiles

public List <profiles_list> getProfiles()

Returns profile object(s) with the following getter methods to help identify the state of the profile:

• getJsonProfile() — Provides information in JSON format for the specific named profile

• getUserId() — Identifies for which user the NPA data flow is being observed

• getActivationState() — Indicates whether or not the profile has started observing data flows by either returning NetworkAnalyticsConstants.ActivationState.PROFILE_ACTIVATED or by returning NetworkAnalyticsConstants.ActivationState.PROFILE_NOT_ACTIVATED.

start

public int start(profileName);

Begins the flow of data points to the NPA client. This is a synchronous call which validates whether or not the NPA client is authorized to observe data flows. The actual observation of data flows begins when the NPA framework calls onActivateProfile() for the binder object.

stop

public int stop(String profileName)

Stops the flow of data points to the NPA client. This is a synchronous call which validates whether or not the NPA client is authorized to stop data flows. The actual cessation of data flow observation occurs when the NPA framework calls onDectivateProfile() for the binder object.

There are two circumstances under which the NPA framework stops sending data flows to the NPA client:

• The NPA client calls stop().
• The device profile is unregistered by the EMM.

getInstance

public static NetworkAnalytics getInstance (Context cxt)

Returns an instance of the Network Analytics class which handles calls to NPA API such as start() and stop().

AIDL Details

This section provides the details for the interface between the NPA client and the NPA framework.

onActivateProfile

The NPA framework calls onActivateProfile to inform clients that the client’s call to NetworkAnalytics.start is successful and that the NPA client will start receiving data flows.

int onActivateProfile(String jsonProfile, int userId, String uniqueId);

jsonProfile — The profile associated with the client which made the successful call
userId — The user associated with the observation of data flows
uniqueId — The unique device key

onDeactivateProfile

The NPA framework calls onDeactivateProfile to inform clients that the client’s call to NetworkAnalytics.stop was successful and that the NPA client will stop receiving data flows.

int onDeactivateProfile(String profileName, int userId);

profileName — The name of the profile for which data flows are no longer observed
userId — The user associated with the observation of data flows

onDataAvailable

The NPA framework calls onDataAvailable to provide the requested data flows to the NPA client.

void onDataAvailable(String profileName, List<string> data);

profileName — The profile for which the data flows are observed
data — The data flows provided by the NPA framework

Start Collecting Data

The following steps explain how the NPA client can check whether or not the EMM agent has assigned a profile to the mobile device. A profile must be assigned to the mobile device in order to determine which data flows are available for observation.

1. Implement a broadcast receiver in the NPA client to listen for the action:

   NetworkAnalyticsConstants.BroadcastActions

   This call is required to determine whether or not a profile is registered for the device. NPA profiles are created and authorized by EMMs and applied to enterprise devices.

2. Upon successful registration, call NetworkAnalytics.start

   NetworkAnalytics mNap = NetworkAnalytics.getInstance(mContext);
       if (mNap != null)
           {
               mNap.start("testing");
           }
   

   A successful call means the NPA framework binds to a service in the NPA client using the action package_name.NetworkAnalyticsConstants.VENDOR_BIND_ACTION.

   For example, if the package name is com.samsung.test.networkmonitor_denali, then the bind action is com.samsung.test.networkmonitor_denali_namonitoraction.

3. The NPA client needs to return the interface com.samsung.android.knox.net.nap.serviceprovider.INetworkAnalyticsService as the Ibinder object.

The NPA framework calls the onActivateProfile() API in the binder object and notifies the NPA client that the profile has been updated to receive data points. The framework then starts calling onDataAvailable() in the binder object at regular intervals depending on the data flow. The onDataAvailable() API contains the data-point information.

<service>
  android:name="$package_name.NPAService"
  android:enabled="true"
  android:exported="true">
  <intent-filter>
    <action android:name="$package_name_namonitoraction" />
  </intent-filter>
</service>

public class NPAService extends Service {
  @Override
  public IBinder onBind(Intent intent) {
    return getBinder();
  } 
            private INetworkAnalyticsService.Stub getBinder() {
    return new INetworkAnalyticsService.Stub() {
      @Override
         public int onDeactivateProfile(String profileName, int userId) throws RemoteException{
          return 0;
      }
            @Override
            public void onDataAvailable(String profileName, List<String> data) throws RemoteException {
      }
        @Override
        public int onActivateProfile(String jsonProfile, int userId, String uniqueId) throws RemoteException {
          return 0;
      }
    };
  }
}

Stop Collecting Data

The following steps explain how the NPA client can detect when a profile is unregistered by the EMM. When this happens, the NPA framework responds to the change by stopping data flows to the NPA client.

1. Implement a broadcast receiver to listen for the action: NetworkAnalyticsConstants.BroadcastActions.

   The action provides information regarding whether or not an admin has registered a profile for the device.

   Once the profile is unregistered, the client stops receiving data flows from the NPA framework.

   The NPA client does not have to implement NetworkAnalytics.stop because the function is handled internally by the NPA framework.

2. The NPA framework calls onDeactivateProfile() in the binder object to notify the NPA client that the profile has been successfully deactivated and that the client will not receive any further data flows.

Stop Collecting Data Without Unregistering the Profile

The NPA client can call NetworkAnalytics.stop to stop observing data flows.

// Use the same instance of the NetworkAnalytics class as when
// starting data collection
NetworkAnalytics.getInstance(mContext);
    if(mNap != null) {
            mNap.stop("testing");
            }

The NPA framework calls onDeactivateProfile() in the binder object to notify the NPA client that the profile has been successfully deactivated and that the client will not receive any further data flows.

Retrieve Profile Details Configured by the EMM

The NPA client can retrieve the profile details through the getJsonProfile() call from the profile object. The profile object is available through a call to the getProfiles() API of the NetworkAnalytics class.

See JSON format for a complete description of the message format.