Menu

DualDAR UEM integration

On this page

Prerequisite

DualDAR is supported on devices with Knox version 3.3 or later.

Before you begin, start by getting permission to access APIs that enable dual encryption to a workspace:

Get permission to access APIs

DualDAR ,enhanced by Knox Platform for Enterprise (KPE), is quick and easy to configure on top of your existing PO/DO containers. Before you begin, start by obtaining permission to access APIs that enable dual encryption to a workspace.

To obtain permission to access DualDAR APIs:

  1. Activate a KPE-DualDAR license.
    • For details on this process, follow the tutorial.
  2. Add the KNOX_DUAL_DAR permission.
  3. <uses-permission android:name="com.samsung.android.knox.permission.KNOX_DUAL_DAR" />
    NOTE — This permission must be bound to the KPE-DualDAR license key. For more information, see the Samsung Knox License key and learn more about license permissions.
  4. Ensure strong protection is enabled.
    • Samsung FBE enabled devices provide the setting ‘strong protection’. This user setting is enabled by default and ensures FBE is active. If turned off, FBE will not be available and DualDAR can't be created.

Create a DualDAR Workspace container

After activating a KPE-DualDAR license and binding the permission to access the APIs:

  1. Set up a DualDAR container by configuring the Profile with DualDAR settings.
  2. Create a KPE container:
    • Setup an Android Profile.
    • Once a KPE license has been activated, the Android enterprise will be upgraded to a KPE container.

Setup a DualDAR Workspace container:

NOTE — A KPE license must be activated prior to provisioning a profile so the below KPE DualDAR configuration can be implemented.
// Create Android For Work manage provisioning intent
Intent provisioningIntent = new Intent(DevicePolicyManager.ACTION_PROVISION_MANAGED_PROFILE);
provisioningIntent.putExtra(DevicePolicyManager.EXTRA_PROVISIONING_DEVICE_ADMIN_COMPONENT_NAME, EDMAppAdmin.getComponentName(mContext));

// Create DualDAR configuration bundle. These two lines are the only differentiators between the KPE workspaces
// and DualDAR
PersistableBundle dualDARConfig = new PersistableBundle();
dualDARConfig.putBoolean(DualDARPolicy.KEY_DUAL_DAR_CONFIG,true);
     
/* IT admin can optionally provide the independent 3rd party to provide the inner layer of encryption.
 * dualDARConfig.putString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE,"com.samsung.android.knox.dualdar.test");
 * dualDARConfig.putString(DualDARPolicy.KEY_CONFIG_CLIENT_SIGNATURE,"421e1cf8a047556df7334b9a9b4f7c7c38b3d7280e68cf4245593ec2b47baa64");
 * If the above two configurations are not provided the inner layer 
 * encryption is performed by an independent FIPS 140-2 certified cryptographic module included on the device.
 */

// Start workspace provisioning  
provisioningIntent.putExtra(android.app.admin.DevicePolicyManager.EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE, dualDARConfig);
startActivityForResult(provisioningIntent, RESULT_PROVISION_MANAGED_PROFILE);

Create a KPE container

The following are steps to set up an Android Profile.

  • Once a KPE license is activated, before or after the following code executes, it will upgrade the Android enterprise profile to a KPE workspace.
// Set up the provisioning intent
Intent provisioningIntent = new Intent("android.app.action.PROVISION_MANAGED_PROFILE");
provisioningIntent.putExtra(EXTRA_PROVISIONING_DEVICE_ADMIN_PACKAGE_NAME, getPackageName());

// REQUEST_PROVISION_MANAGED_PROFILE is defined
startActivityForResult(provisioningIntent, 1);
provisioningActivity.finish();

Setup DualDAR configuration

There are many different ways to configure a DualDAR workspace. As seen above, all DualDAR workspace configuration must begin with:

<uses-permission android:name="com.samsung.android.knox.permission.KNOX_DUAL_DAR" />

After this, any additional configuration options may be added before the profile is provisioned.

Use the following syntax to add the DAR policy to the Bundle before the workspace is provisioned, as seen in the full implementation of the source code above.

dualDARConfig.putString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE,"com.samsung.android.knox.dualdar.test");

For more information on these constants, see the API reference.

Configure DualDAR

To update a workspace that's been provisioned with two layers of encryption with DualDAR, use the DualDARPolicy class. In addition to the configurations used above to create a DualDAR workspace during provisioning, API methods are also included to update a DualDAR Workspace.

Once a DualDAR workspace is created, it can continue to be updated with new specifications using the getConfig and setConfig methods.

NOTEKEY_CONFIG_CLIENT_PACKAGE and KEY_CONFIG_CLIENT_SIGNATURE can't be updated after creation.

Update configurations

  1. Retrieve policy object associated with the DualDAR workspace.
    // When you create workspace(container) successfully, containerID is returned using intent.
    // Use this containerID in below API.
    EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);
    KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);
    DualDARPolicy dualDARPolicy = kcm.getDualDARPolicy();
    			
  2. (Optional) Get the existing configuration bundle.
    • Use this to check your existing settings associated with the workspace.
     try {
         // get DualDAR 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);
         Parcelable[] parcelables = config.getParcelableArray(DualDARPolicy.KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES);
         AppIdentity[] whitelistedPackages = new AppIdentity[parcelables.length];
         for(int i=0;i<parcelables.length;i++) {
             whitelistedPackages[i] = (AppIdentity) parcelables[i];
         }
     } catch (SecurityException e) {
         Log.w(TAG, "SecurityException: " + e);
     }		
  3. Set the new configuration bundle.
     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);
     }		

DualDAR custom configurations

Currently the following 3 customizations options can be added:

  1. KEY_CONFIG_DATA_LOCK_TIMEOUT
  2. KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES
  3. KEY_CONFIG_DE_RESTRICTION

Set data timeout

IT admins can use the KEY_CONFIG_DATA_LOCK_TIMEOUT variable to set the data lock timeout for DualDAR workspace. From Knox 3.4, the default value for this variable is INFINITY , minimum allowable value is 1 min.

Create a Whitelist app packages

When a DualDAR Workspace is locked, Knox ensures that all work apps are stopped so that they don't handle any sensitive data. It admins can create a whitelist to specify white apps can continue to run in a locked state.

Note that when a whitelist is created, it will overwrite the previous list of applications. To clear an existing whitelist, pass NULL into the KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES when setting the configuration.

Restrict DE storage access

When a DualDAR Workspace is locked, Knox ensures that all work apps are stopped so that they don't handle any sensitive data. DE restriction is a configurable parameter for DualDAR, which controls whether apps can write in the device's DE storage while a DualDAR workspace container is locked using the KEY_CONFIG_DE_RESTRICTION variable.

Since Knox 3.4, the default value for KEY_CONFIG_DE_RESTRICTION is set to false to enhance app stability, which gives system apps write access to the DE storage by default.

IT admins can restrict which apps can access DE storage by creating a package whitelist with KEY_CONFIG_WHITELISTED_DATA_LOCK_STATE_PACKAGES and changing the value for KEY_CONFIG_DE_RESTRICTION to true.

Disable a DualDAR workspace

  • Uninstalling workspace: IT admin can call the removeUser method to remove a Workspace and all associated data. This can't be called on the primary user. If allowed by IT admin, end users can uninstall Workspace as well.
  • Factory reset the device: IT admin can call wipeData to erase all device data and reboot the device.
NOTE — By uninstalling a Workspace or factory reset the device, all data within the Workspace will be lost.

UEM integration options

There are two options when integrating KPE DualDAR into UEMs:

Zero day support with KME and KSP

Since Knox 3.4, DualDAR can be integrated using KME and KSP to ensure access to the most up to date features that Knox offers. Note that this integration requires devices to have Knox 3.4 and above.

The KME and KSP UEM integration workflow is as follows:

  1. Enroll enterprise devices using KME (required).
    • During KME profile setup, enable DualDAR.
  2. Once devices are enrolled with DualDAR enabled, the UEM agent creates a DualDAR Workspace container.
  3. After a workspace is created, Managed Google Play is setup.
    • Using Managed Google Play, download KSP inside the Workspace container.

    Once KSP is installed in the Workspace container, the Knox license is activated and DualDAR policies can be applied.

NOTE — UEMs can also activate Knox license prior to Workspace creation. PO only Workspace is not currently supported by this feature.

What to remember when enabling DualDAR

When creating Samsung Knox DualDAR Workspace, there are many factors to consider as described in this section. Please ensure that you follow these specifications.

Password quality

Samsung Knox DualDAR by default doesn't enforce password quality for both the device and Workspace. IT admin are recommended to enforce password quality for both the device and Workspace based on their company policies.

Biometric Authentication

End user's will not be able to use biometric authentication for the DualDAR Workspace because when a Workspace is locked the encryption keys are evicted. After the key eviction, the user is required to enter a strong authentication (Pin/Pattern/Password) to enter the Workspace. Hence even if the end user has configured biometric authentication, they will be required to enter their Pin/Pattern/Password to enter the Workspace after it is locked. For better user experience it is recommended that a IT admin disallows biometric authentication for the Workspace, so user does not have that option available. For device authentication, users will be able to use their biometric authentication.

Prevent Workspace Uninstall

On the Knox Workspace with a Fully Managed Device configuration, IT admins should prevent a user from uninstalling the Workspace by setting DISALLOW_REMOVE_MANAGED_PROFILE user restriction.

Smart lock

Android provides the end user with the ability to keep their phone or tablet unlocked in some situations, such as when the device is in a trusted place (home or work). Please see this article for more information. As a result, data lock set by the IT admin will not be enforced in these trusted places which are configured by end user and the Workspace will remain unlocked. IT admins can disable Smart Lock using the following APIs

Reset Password

The Data-at-Rest (DAR) Capability Package (CP) published by the Commercial Solutions for Classified (CSfC) program within the National Security Agency (NSA) provides architectures and configuration requirements to empower customers to implement a secure DAR solution that meets the needs of having two independent layers of encryption using Commercial National Security Algorithm (CNSA) Suite. One such requirement in DAR CP is to disable all key recovery mechanism. Samsung Knox DualDAR by default does not disable reset passwords. Customers looking to meet CSfC DAR CP requirements can simply not set a password using a token, which will prevent a password reset from the IT admin.

Admins

For Knox Workspace on Fully Managed Device, configuration for both Device Owner (DO) and Profile Owner (PO) must be from the same vendor and have the same package name.

Remote Attestation

It is recommended for IT admin to perform Knox Remote attestation prior to the creation of a Workspace and periodically after creation. This helps IT admin ensure that the device has not been compromised by an unauthorized agent. Please see following for more details on Knox Remote Attestation.

Admin Lock

Samsung Knox Platform for Enterprise provides admins the ability to lock the device or Workspace in case where the device is lost or out of compliance. This feature enables the flexibility to only lock the Workspace or lock the entire device. Please note if admin wishes to lock the entire device, the UEM agent as Device Owner (DO) must call admin lock. A UEM agent as a Profile Owner (PO) will only lock the Workspace.

Knox Workspace Only Mode

For deployment where it is Workspace only (PO only), i.e. the device is not fully managed and there is no Device Owner (DO), special considerations need to be taken if customer wants to provide the 2nd layer of encryption via a 3rd party app. The 3rd party app needs to be installed and updated in user0 and in PO only mode there is no agent in user0 side. Thus the 3rd party app will need to installed via an app store in user0 or via DPC leveraging Android native package installer APIs.

Troubleshooting

  • DualDAR license not activated: If DualDAR config is set and an IT admin attempts to create a container without activating a DualDAR license the following error is shown. Ensure that a DualDAR license has been activated.
  • DualDAR client app not installed: If DualDAR config specifies a client app but the client app is not installed then the following error is shown.
  • Strong Protection not enabled: On Samsung FBE devices, the end user is provided with the setting ‘Strong Protection’. By default this setting is enabled and is required to be enabled for DualDAR. If user has turned this setting off prior to the DualDAR creation then the following error will be shown.
  • ERROR_FAILURE_IN_SETTING_WHITELIST_PACKAGES
  • ERROR_FAILURE_IN_SETTING_DATA_LOCK_TIMEOUT
  • ERROR_FAILURE_IN_SETTING_DE_RESTRICTION
  • ERROR_NONE
 try {
     // set new DualDAR config
     // ...
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }

Constraints

Samsung Knox DualDAR leverages Android File Based Encryption (FBE) architecture and as such only supports Samsung devices with FBE. Samsung smart phones – scheduled to reach consumers in early 2019 – adds support for File-based Encryption (FBE). For details please see Samsung devices and File-based Encryption (FBE) for more information.

Note: The Samsung Knox DualDAR outer layer of encryption leverages the hardware crypto module available with the chipset Qualcomm ICE or Exynos Flash Memory Protector (FMP). Certain low end devices will not have support for FMP. The recommended way to check if DualDAR is supported for a device is to use the getDualDARversion() API.

Calendar Notifications

The Samsung calendar app syncs events for the next 24 hours from the alarm service. If the user does not launch notifications or the calendar app within that period, then notifications for calendar events later than 24 hours are not shown to the user. If the DualDAR Workspace is locked for more than 24hrs then the user will not be notified of calendar events. To mitigate this constraint, users will be alerted with the following notification if the Workspace is locked for more than 24 hours:

"Workspace is locked for more than 24 hours. Please unlock to sync up calendar events"

Safe Mode

Samsung Knox DualDAR is not supported in Safe Mode as third party apps are not allowed to run. As a result, the DualDAR client will not be able to execute Safe Mode.

Biometric authentication for Workspace

As mentioned, end users are not able to authenticate with biometrics for a DualDAR Workspace because the encryption key is evicted when the workspace is data locked. After the key eviction, the user is required to enter a strong authentication (Pin/Pattern/Password) to enter the Workspace. Therefore, even if the user has configured a biometric authentication for workspace, they will be required to enter their Pin/Pattern/Password after a Workspace is data locked. Before Data lock happens, biometric can be used to unlock the workspace. For the device, authentication end user will be able to use biometric authentication.

User settings

After the creation of a DualDAR Workspace the following settings are not available to a user:

  • One Lock: This setting unlocks the Workspace when the user unlocks the device. As DualDAR requires two levels of authentication, users cannot turn on one lock when there is a DualDAR Workspace on the device.
  • Uninstall/clear cache and data from a DualDAR client: A user is prevented from uninstalling, clearing cache, and deleting data from the 3rd party DualDAR client app.
  • Strong Protection: After a DualDAR Workspace is provisioned, users cannot turn off FBE by toggling the Strong Protection setting.

Preloaded Apps

Samsung Knox DualDAR by default whitelists all system apps run when the Workspace is locked. IT admin can choose to disable any system apps via APIs.

Need more help?

For more information, see the: