DualDAR UEM integration

Prerequisite

DualDAR is supported on Galaxy S10, N10, S20, and future flagship models.

• To check your Knox version, use the getAPILevel() method and ensure that it is above level 28.

• To check if the device supports DualDAR use the getDualDARversion() API.

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.

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

   This permission must be bound to the KPE-DualDAR license key. For more information, see theSamsung Knox License key and learn more about license permissions.

3. 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 DualDAR Container
• Create a KPE container
• Setup DualDAR Container for company-owned devices
• Setup DualDAR for fully managed devices

// 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);

// 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();

Intent mIntent = new Intent();

// Create Dual DAR configuration bundle
PersistableBundle adminExtras = new PersistableBundle();
adminExtras.putBoolean(DualDARPolicy.KEY_DUAL_DAR_CONFIG, true);
adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE, "");
adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_SIGNATURE, "");
adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_LOCATION, "");
mIntent.putExtra(EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE, adminExtras);

// Set provisioning mode
mIntent.putExtra(EXTRA_PROVISIONING_MODE, PROVISIONING_MODE_MANAGED_PROFILE);

// Provide result data from admin app's ACTION_GET_PROVISIONING_MODE activity
setResult(RESULT_OK, mIntent);

Intent mIntent = new Intent();

// Create Dual DAR configuration bundle
PersistableBundle adminExtras = new PersistableBundle();
adminExtras.putBoolean(DualDARPolicy.KEY_DUAL_DAR_CONFIG, true);
adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_PACKAGE, "");
adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_SIGNATURE, "");
adminExtras.putString(DualDARPolicy.KEY_CONFIG_CLIENT_LOCATION, "");
mIntent.putExtra(EXTRA_PROVISIONING_ADMIN_EXTRAS_BUNDLE, adminExtras);

// Set provisioning mode
mIntent.putExtra(EXTRA_PROVISIONING_MODE, PROVISIONING_MODE_FULLY_MANAGED_DEVICE);

// Provide result data from admin app's ACTION_GET_PROVISIONING_MODE activity
setResult(RESULT_OK, mIntent);

The API reference for the feature is com.samsung.android.knox.ddar.

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.

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
• Whitelist app packages
• Restrict DE storage access

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.

UEM integration options

There are two options when integrating KPE DualDAR into UEMs:

• Deep API integration
• Using Knox Mobile Enrollment (KME) and Knox Service Plugin (KSP)

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.

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:

• setTrustAgentConfiguration

• KEYGUARD_DISABLE_TRUST_AGENTS

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), that is, 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

The following known errors can occur with DualDAR:

• 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.

Additional error codes are as follows:

• 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 supports only Samsung devices with FBE. For details, please see File-based Encryption (FBE).

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 allows 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:

• DualDAR architecture
• Knox SDK API reference