Since: API level 28
public class

DualDARPolicy

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.ddar.DualDARPolicy

Class Overview

This class supports MDM(EMM) to create a workspace(container) protected with Dual DAR and provides APIs to access and set Dual DAR configurations.

Usage
Following code snippet represents how an MDM Agent shall create a Dual DAR container
     // Create Android For Work manage provisioning intent
     Intent intent = new Intent(DevicePolicyManager.ACTION_PROVISION_MANAGED_PROFILE);
     intent.putExtra(DevicePolicyManager.EXTRA_PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME, EDMAppAdmin.getComponentName(mContext));

     // Create Dual DAR configuration bundle
     PersistableBundle dualDARConfig = new PersistableBundle();
     dualDARConfig.putBoolean(DualDARPolicy.KEY_DUAL_DAR_CONFIG,true);
     dualDARConfig.putString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE,"<client_package_name>");
     dualDARConfig.putString(DualDARPolicy.KEY_CONFIG_CLIENT_SIGNATURE,"<client_package_signature>");
     intent.putExtra(android.app.admin.DevicePolicyManager.EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE, dualDARConfig);

     // Start workspace provisioning
     startActivityForResult(intent, RESULT_PROVISION_MANAGED_PROFILE);
 
If the KEY_CONFIG_CLIENT_PACKAGE is not specified (or empty) during workspace(container) creation, then the inner layer encryption is performed by an independent FIPS 140-2 certified cryptographic module included on the device. NOTE: This class is only applicable to Dual DAR enabled workspace(container).

Since
API level 28
KNOX 3.3

Summary

Nested Classes
class DualDARPolicy.DUAL_DAR_VERSION_CODES Enumeration of the currently known DUAL DAR version codes. 
Constants
int ERROR_FAILURE_IN_SETTING_DATA_LOCK_TIMEOUT Signifies FAILURE in setting data lock timeout
int ERROR_FAILURE_IN_SETTING_DE_RESTRICTION Signifies FAILURE in setting DE storage restriction
int ERROR_FAILURE_IN_SETTING_WHITELIST_PACKAGES Signifies FAILURE in setting data lock whitelisted packages
int ERROR_NONE Signifies SUCCESS
String KEY_CONFIG_CLIENT_LOCATION Used to set Dual DAR Client App's location during workspace(container) creation time.
String KEY_CONFIG_CLIENT_PACKAGE Used to set Dual DAR Client App's package name during workspace(container) creation time.
String KEY_CONFIG_CLIENT_SIGNATURE Used to set Dual DAR Client App's signature during workspace(container) creation time.
String KEY_CONFIG_DATA_LOCK_TIMEOUT Used to set/get Dual DAR data lock timeout value with getConfig() and setConfig(Bundle)
String KEY_CONFIG_DE_RESTRICTION Used to enable/disable DE storage access to applications running in Dual DAR enabled workspace(container).
String KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES Used to set/get Dual DAR data lock whitelisted package list with getConfig() and setConfig(Bundle)
String KEY_DUAL_DAR_CONFIG Used to mark workspace(container) for Dual DAR protection during creation time.
Public Methods
Bundle getConfig()
API to get active DualDAR Config
static String getDualDARVersion()
Get the Dual DAR version.
int setConfig(Bundle config)
API to set DualDAR Config
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final int ERROR_FAILURE_IN_SETTING_DATA_LOCK_TIMEOUT

Since: API level 28

Signifies FAILURE in setting data lock timeout

Usage
Error code used by an application to identify the result of the execution is failure in case of setting data lock timeout.
Since
API level 28
KNOX 3.3
Constant Value: -1 (0xffffffff)

public static final int ERROR_FAILURE_IN_SETTING_DE_RESTRICTION

Since: API level 28

Signifies FAILURE in setting DE storage restriction

Usage
Error code used by an application to identify the result of the execution is failure in case of setting DE storage restriction.
Since
API level 28
KNOX 3.3
Constant Value: -3 (0xfffffffd)

public static final int ERROR_FAILURE_IN_SETTING_WHITELIST_PACKAGES

Since: API level 28

Signifies FAILURE in setting data lock whitelisted packages

Usage
Error code used by an application to identify the result of the execution is failure in case of setting whitelisted packages.
Since
API level 28
KNOX 3.3
Constant Value: -2 (0xfffffffe)

public static final int ERROR_NONE

Since: API level 28

Signifies SUCCESS

Usage
Error code used by an application to identify the result of the execution is success.
Since
API level 28
KNOX 3.3
Constant Value: 0 (0x00000000)

public static final String KEY_CONFIG_CLIENT_LOCATION

Since: API level 33

Used to set Dual DAR Client App's location during workspace(container) creation time.

Usage
Used as a String param field in admin extras bundle passed as DevicePolicyManager#EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE with DevicePolicyManager#PROVISIONING_MODE_MANAGED_PROFILE extra value. Client location should be an external storage(sdcard area) and should be passed with "file://" prefix.
 // Create Dual DAR with configuration bundle
 PersistableBundle adminExtras =  new PersistableBundle();
 adminExtras.putBoolean(DualDARPolicy.KEY_DUAL_DAR_CONFIG, true);
 adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE, DUALDAR_CLIENT_EXAMPLE_PACKAGE_NAME);
 adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_SIGNATURE, DUALDAR_CLIENT_EXAMPLE_PACKAGE_SHA256_SIGNATURE);

 // Set the file path of the client exist location adding with "file://" prefix.
 String DUALDAR_CLIENT_PACKAGE_DOWNLOAD_LOCATION = getExternalFilesDir(null) + "/client_example_app.apk";
 adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_LOCATION, "file://" + DUALDAR_CLIENT_PACKAGE_DOWNLOAD_LOCATION);

 // Param field in admin extras bundle passed as DevicePolicyManager.EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE
 Intent intent = new Intent();
 if (adminExtras !=null && adminExtras.size() > 0) {
     intent.putExtra(DevicePolicyManager.EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE, adminExtras);
 }

 // Return DevicePolicyManager.PROVISIONING_MODE_MANAGED_PROFILE in DevicePolicyManager.EXTRA_PROVISIONING_MODE as result.
 intent.putExtra(DevicePolicyManager.EXTRA_PROVISIONING_MODE, DevicePolicyManager.PROVISIONING_MODE_MANAGED_PROFILE);
 
Note: To be used only during container(WPCOD) creation time.
Since
API level 33
KNOX 3.7
Constant Value: "dualdar-config-client-location"

public static final String KEY_CONFIG_CLIENT_PACKAGE

Since: API level 28

Used to set Dual DAR Client App's package name during workspace(container) creation time. Also used in getConfig() to get Client App's package name.

Usage
Used as a String param field in admin extras bundle DevicePolicyManager#EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE with DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE action. Note: To be used as bundle params key during container creation time and getConfig() only.
Since
API level 28
KNOX 3.3
Constant Value: "dualdar-config-client-package"

public static final String KEY_CONFIG_CLIENT_SIGNATURE

Since: API level 28

Used to set Dual DAR Client App's signature during workspace(container) creation time. Also used in getConfig() to get Client App's signature.

Usage
Used as a String param field in admin extras bundle passed as DevicePolicyManager#EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE with DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE action. Note: To be used as bundle params key during container creation time and getConfig() only.
Since
API level 28
KNOX 3.3
Constant Value: "dualdar-config-client-signature"

public static final String KEY_CONFIG_DATA_LOCK_TIMEOUT

Since: API level 28

Used to set/get Dual DAR data lock timeout value with getConfig() and setConfig(Bundle)

Usage
Used as a Long by the application that is administering the workspace(container) to set the data lock timeout.
The timeout can range from 1*60*1000 to Long.MAX_VALUE milliseconds. The default timeout is set to infinity. To set timeout to infinity use -1
Note: To be used as bundle params key with getConfig() and setConfig(Bundle) only.
Since
API level 28
KNOX 3.3
Constant Value: "dualdar-config-datalock-timeout"

public static final String KEY_CONFIG_DE_RESTRICTION

Since: API level 28

Used to enable/disable DE storage access to applications running in Dual DAR enabled workspace(container).

Usage
Used as a Boolean by the application that is administering the workspace(container) to allow/disallow packages to access DE storage. If enabled (set to true), only whitelisted applications (refer KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES) can access DE storage. If disabled (set to false) all applications can access DE storage.
Note: To be used as bundle params key with getConfig() and setConfig(Bundle) only. Default value is false.
Since
API level 28
KNOX 3.3
Constant Value: "dualdar-config-de-restriction"

public static final String KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES

Since: API level 28

Used to set/get Dual DAR data lock whitelisted package list with getConfig() and setConfig(Bundle)

Usage
Used as a Parcelable(AppIdentity) Array by the application that is administering the workspace(container) to set the whitelisted packages to run in data locked state.
This will overwrite previously set list of applications. Setting an empty list will clear previously set list.
Note: To be used as bundle params key with getConfig() and setConfig(Bundle) only.
Since
API level 28
KNOX 3.3
Constant Value: "dualdar-config-datalock-whitelistpackages"

public static final String KEY_DUAL_DAR_CONFIG

Since: API level 28

Used to mark workspace(container) for Dual DAR protection during creation time.

Usage
Used as a Boolean param field in admin extras bundle DevicePolicyManager#EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE with DevicePolicyManager#ACTION_PROVISION_MANAGED_PROFILE action. If the value is true, marks the container to be protected with Dual DAR during container creation time.
Note: To be used only during container creation time.
Since
API level 28
KNOX 3.3
Constant Value: "dualdar-config"

Public Methods

public Bundle getConfig ()

Since: API level 28

API to get active DualDAR Config

Returns
  • returns current active DualDAR config
Throws
SecurityException If caller does not have required permissions
For Container:
 // When you create workspace(container) successfully, containerID will be returned via intent.
 // Use this containerID in below API.
 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
 DualDARPolicy dualDARPolicy = kcm.getDualDARPolicy();
 try {
     // get Dual DAR active config
     Bundle config = dualDARPolicy.getConfig();
     String clientPackage = config.getString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE);
     String clientSignature = config.getString(DualDARPolicy.KEY_CONFIG_CLIENT_SIGNATURE);
     long dataLockTimeout = config.getLong(DualDARPolicy.KEY_CONFIG_DATA_LOCK_TIMEOUT);
     boolean deRestriction = config.getBoolean(DualDARPolicy.KEY_CONFIG_DE_RESTRICTION);
     Parcelable[] parcelables = config.getParcelableArray(DualDARPolicy.KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES);
     AppIdentity[] datalockWhitelistedPackages = new AppIdentity[parcelables.length];
     for(int i=0;i<parcelables.length;i++) {
         datalockWhitelistedPackages[i] = (AppIdentity) parcelables[i];
     }
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }
 
Multiuser Environment
User Scope
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_DUAL_DAR" permission with a protection level of signature.
Since
API level 28
KNOX 3.3

public static String getDualDARVersion ()

Since: API level 28

Get the Dual DAR version.

Format: <major.minor.patch>

where major, minor and patch are the string representations of the version number's three components: major version number, minor version number and patch. The components must appear in the specified order, and must be separated by periods.
The components are used by convention as follows:
Major:
A higher version number might indicate a major rewrite of a product where backward compatibility cannot be assumed.
Minor:
If the major version number remains the same, but the minor version number is increased, then this indicates significant enhancement with the intention of backward compatibility. A higher minor version number might indicate fully backward-compatible new version of a product.
Patch:
If the major and minor version numbers are same but patches is increased, then the product is intended to be fully interchangeable. A higher patch number might indicate bug fixes and security patches.

Returns
  • null if DualDAR feature not available, else DualDAR version in <major.minor.patch> format.
Usage

Administrator can get the DualDAR version on the product.

Since
API level 28
KNOX 3.3

public int setConfig (Bundle config)

Since: API level 28

API to set DualDAR Config

Parameters
config new Dual DAR configuration to be set
Returns
Throws
SecurityException If caller does not have required permissions
Usage
Set DualDAR Config as a bundle. Use KEY_CONFIG_DATA_LOCK_TIMEOUT, KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES and KEY_CONFIG_DE_RESTRICTION to set passed config values. Note: KEY_CONFIG_CLIENT_PACKAGE and KEY_CONFIG_CLIENT_SIGNATURE cannot be changed after initial configuration
For Container:
 // When you create workspace(container) successfully, containerID will be returned via intent.
 // Use this containerID in below API.
 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
 DualDARPolicy dualDARPolicy = kcm.getDualDARPolicy();
 try {
     // set new Dual DAR config
     Bundle newConfig = new Bundle();
     newConfig.putBoolean(DualDARPolicy.KEY_CONFIG_DE_RESTRICTION, false);
     newConfig.putLong(DualDARPolicy.KEY_CONFIG_DATA_LOCK_TIMEOUT, 62000);

     List<AppIdentity> whitelistPackages = new ArrayList<>();
     whitelistPackages.add(new AppIdentity("com.test.app1","sign1"));
     whitelistPackages.add(new AppIdentity("com.test.app2","sign2"));
     newConfig.putParcelableArray(DualDARPolicy.KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES,
         (Parcelable[]) whitelistPackages.toArray(new AppIdentity[0]));

     newConfig.putBoolean(DualDARPolicy.KEY_CONFIG_DE_RESTRICTION, true);
     dualDARPolicy.setConfig(newConfig);
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }
 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_DUAL_DAR" permission with a protection level of signature.
Multiuser Environment
User Scope
Since
API level 28
KNOX 3.3