- Welcome
- Basics
- Device apps
- Overview
- Knox licenses
- Knox SDK
- Overview
- About the SDK
- What's new
- What's new
- Migrations
- Android 11
- Android Enterprise
- Device admin deprecation
- DA deprecation and Samsung
- DA deprecation and VMware
- FAQs
- FAQ Index
- What is DA Deprecation?
- What is being deprecated with device admin?
- What is API level 29, as it relates to DA deprecation?
- What is the impact of DA deprecation to Knox?
- As a Knox partner, what do I need to do?
- What happens to DA apps when upgraded to Android Q?
- When can I safely upgrade to Android Q?
- What if a device already has Android Q?
- Can my DA app coexist with a UEM app running as DO?
- Are there changes to Knox Configure due to DA deprecation?
- Can I use my DA app alongside Knox Configure?
- Does KME still support device enrollment using DA?
- As DA is not in Android Q, can I enroll via KME to Work Profile?
- Get started
- Sample app tutorials
- Features
- Independent Software Vendors
- ML Developers
- Introduction
- Whitepaper
- Model Protection APIs
- Protect ML model
- ML Encryption Tool
- Knox ML Encryption Tool Revision
- FAQs
- Are there any additional steps for Linux to give execute permissions to conversion tool?
- Do I to change my app to run the encrypted model?
- Where are the encrypted files saved?
- Which devices support Knox for Model Protection?
- Which ML file types are supported by Knox for Model Protection?
- Which operating systems (OS) support Knox ML Model Conversion Tool?
- Independent Software Vendors (DA)
- MDM Providers
- System Integrators
- VPN Providers
- Storage Providers
- API Reference
- Tools
- FAQs
- FAQ Index
- General
- What is the Samsung Knox SDK?
- Where can I obtain a white paper for Samsung Knox?
- What versions of Android support the Knox SDK?
- How can I check if my device firmware is an engineering or commercial build?
- How can I access the binaries before they are released?
- What is a deprecated API method?
- What kind of support is offered after an API is deprecated?
- Why were the API classes deprecated?
- What are the features by default set to hidden/disabled in ProKiosk mode?
- What are credentials?
- What is Knox TIMA CCM?
- Is Knox supported on other platforms, such as windows?
- Which hardware control features can be managed inside Knox Workspace, using the Knox SDK?
- Why do a few Knox SDK APIs not work on some devices?
- Can Google Play used to deploy Knox apps?
- Can I use managed configurations for Samsung Knox features?
- Can a third-party app use the Knox SDK to get LDAP information?
- How do I enable users to select a 3rd party keyboard?
- How does my device's serial number change with Knox 3.2.1?
- If I don’t use the UCM APIs of the Knox SDK, what are my options for credential storage?
- What are the changes in Samsung Calendar data sharing in Knox SDK 3.8?
- What are the alternative Google APIs for Samsung Knox Wi-fi deprecation?
- Installation
- How do I use an SDK packaged as an Eclipse IDE add-on with the Android Studio IDE?
- Is it possible to install an app silently on a device using Knox SDK?
- Why am I still able to download an app even though I have added it to blacklist with the method addAppPackageNameToBlackList(), from the Knox SDK?
- How can an app find out which apps are installed in and outside a container, using the Knox SDK?
- How can an app block the installation of a non-trusted app, using the Knox SDK?
- What does "Security policy prevents installation of this application" mean?
- Can I prevent an end user from installing certificates, with the Knox SDK?
- Does API method installApplication(String packageName) download apps from the play store and install them silently?
- Does the API method setApplicationUninstallationDisabled disable the uninstallation of apps inside the container, when using the Knox SDK?
- Why is the installCertificate API method not successfully installing a certificate on my device?
- Licensing
- How do I use license keys?
- What is the KPE Premium license key and why should I use it?
- What is the backwards compatible key?
- When do I need to use the backwards compatible key?
- Do I need to associate my app with a backwards compatible key?
- How have license key names changed?
- Which keys can be used in combination with each other?
- What is automatic license assignment release?
- What are license permissions?
- What is the difference between Standard and Premium permissions?
- How do I declare permissions?
- Deprecated licenses
- Operations
- Are the Knox SDK browser policies applicable to Chrome as well?
- How can an enterprise disable roaming access over an enterprise APN, using the Knox SDK?
- Can an app using the Knox SDK clear an email signature?
- Can I add system or pre-installed app packages, using the Knox SDK, to the notification blacklist?
- Can I use Google push notifications inside a Knox Workspace container?
- Can I use SDP for an app that is outside the Knox container?
- Can multi-window mode be disabled through blocklisting, using the Knox SDK?
- Does my launcher app need a special intent to work in Kiosk mode?
- Does the API method enforceMultifactorAuthentication(), in the Knox SDK, come into effect immediately?
- How can I disable GPS on the device using the Knox SDK?
- How can I move an app from the user's personal mode to the Knox container using an API in the Knox SDK?
- How does the Knox API method EmailPolicy.setAllowEmailForwarding work?
- How does the Knox SDK method, setAllowChangeDataSyncPolicy(), sync contacts with the container so they are visible on the personal side?
- How do I disable the USB port except for charging, using the Knox SDK?
- How do I use the Knox SDK to allow or block phone numbers?
- How do I use the SDK to prevent launching the screen saver when an app is running?
- Is an APN validated when I use the Knox SDK to add it to a device?
- Is it possible to block application access to data while roaming, using the Knox SDK?
- Is there a limit to the number of applications that can be blocked or allowed using the Knox SDK?
- Is there any way to create IMAP, POP, or Exchange accounts in the emulator?
- What does the RCPPolicy.NOTIFICATIONS argument do in the API method setAllowChangeDataSyncPolicy?
- What Keystores can I use?
- What kind of phone numbers are allowed after setting setEmergencyCallOnly(true) in the Knox SDK?
- What secure hardware can I use with the UCM APIs to store credentials?
- What should I do if I find API errors?
- Why are app shortcuts not showing up in Kiosk mode for the Knox SDK?
- Why are Knox Customization policies still active on my device even after my app is uninstalled?
- Why can't you enable the camera inside a container when it is blocked in the personal space?
- Why does the allowOTAUpgrade API method, in the Knox SDK, have no effect when allowFirmwareRecovery() is set to false?
- Why does the API method call setEnableApplication(), using the Knox SDK, disable the app?
- Why does the createVpnProfile method, in the Knox SDK, fail when a Profile name has whitespace?
- Why does the SDK return a NullPointerException when I access the SMS/MMS content URI?
- Why is video recording also blocked when I use the Knox SDK to block audio recording?
- Standard features
- Can I force a device to update to the latest firmware?
- Can multi-window mode be disabled through blacklisting, using the Knox SDK?
- Does the API method setApplicationUninstallationDisabled disable the uninstallation of apps inside the container, when using the Knox SDK?
- What is the difference between hideStatusBar() and hideSystemBar() in the Knox SDK?
- What Knox SDK API methods are available to manage device firmware?
- Why do a few Knox SDK APIs not work on some devices?
- Will the legacy ELM and KLM keys still work with the Knox Platform for Enterprise (KPE) key?
- Premium features
- Customization
- Security
- As a developer, how can I access the device root key?
- Can an app prevent access to specific networks, using the Knox SDK?
- Can fingerprint be used as a substitute for other forms of screen unlock methods, when using the Knox SDK?
- Can I use the Knox SDK to disable the "Unlock Via Google" password unlock option?
- Can I use the Knox SDK to encrypt the SD card?
- Can I use the Knox SDK to modify the fingerprint passcode requirements?
- Does a Knox container enforce authentication by default?
- Do the SDP APIs support a security standard?
- How can I ensure that certificates are stored in the TIMA KeyStore, using the Knox SDK?
- How does SDP secure the cryptographic keys used for data encryption?
- How do you programmatically unlock the container after the maximum amount of failed attempts, using the Knox SDK?
- What does "Security policy prevents installation of this application" mean?
- What is the maximum length allowed for a Wi-Fi SSID, when using the Knox SDK?
- What is the scope of the setPasswordVisibilityEnabled() API method, in the Knox SDK?
- When I call the Knox SDK API method setExternalStorageEncryption, why doesn't the device prompt the user to encrypt?
- Why are HTTPS requests bypassing global proxy settings in the Knox SDK?
- Why doesn't the Knox method "isActivePasswordSufficient" check for forbidden strings?
- Why do I see "Cannot safely connect to server" when I create an email account using SSL??
- Why is my timeout of 15 minutes not working for the resetContainerPassword() method, using the Knox SDK?
- Why is the Knox API method setMaximumTimeToLock() not showing the time I configured?
- SDP
- UCM
- VPN
- VPN Provider
- Does the Knox framework store any type of data passed during profile creation?
- Do I need a license to use the Knox VPN SDK?
- How can I verify if the VPN connection that is starting belongs to the Knox profile or the default Android VPN profile?
- How do I add all apps inside AND outside the container to a VPN profile?
- How is the Knox container affected by VPN On-Premise Bypass?
- How should the network state change be handled by the VPN Client Integration?
- If the framework takes the responsibility of starting the VPN connection, and since it is MDM-controlled, how will the user be able to connect to the VPN if a time-out or networking error occurs?
- Under what circumstances does the framework trigger the start connection?
- What API do I use to create a On-Premise Bypass VPN profile?
- What is VPN On-Premise Bypass?
- When should the various Android VPN service APIs be called?
- Workspace
- Samsung DeX
- Containers
- How does an app detect if a container was created using the Knox SDK?
- How do I install the MDM agent inside the Knox container?
- I have created a "container only mode" container and I am locked inside, using the Knox SDK. How do I exit?
- Why do I get error KnoxContainerManager.ERROR_INTERNAL_ERROR(-1014) while creating a container?
- KBAs
- Knox POS SDK
- Knox Capture SDK
- Knox Tizen SDK
- Overview
- About the SDK
- What's new
- Get started
- Tutorials
- API Reference
- Sample Apps
- FAQs
- FAQ Index
- General
- How is Tizen related to Knox?
- Which devices support the Knox Tizen SDK for Wearables?
- What version of the Tizen SDK should I install before installing the Samsung Knox Tizen SDK for Wearables?
- Should I install any extension SDK before installing the Samsung Knox Tizen SDK for Wearables?
- What are the modes in which you can use the Samsung wearable device?
- What are the supported Wi-Fi security types?
- How do I get the attestation blob?
- What is a nonce and why is it valid for a short time period?
- What is ProKiosk mode?
- Licensing
- Samsung India Identity SDK
- Overview
- About the SDK
- What's new
- Get started
- Features
- API Reference
- Sample Apps
- FAQs
- FAQ Index
- General
- Installation
- Licensing
- Usage
- How do I verify if my device supports Samsung India Identity SDK?
- Should I capture the IRIS image of one or both eyes?
- When do I use the UIDAI Staging server and UIDAI Production server?
- What are the URLs that need to be whitelisted for enterprise-managed devices using the Samsung India Identity SDK APIs?
- Who is impacted by the upgrade of the biometric public devices to registered devices?
- Is there any hardware change required to upgrade the public devices to registered devices?
- What are the application (APK) changes required to upgrade the public devices to registered devices?
- Web services
- Managed configurations
- Introduction
- Deploy managed configurations
- FAQs
- FAQ Index
- What are managed configurations?
- Why should I use managed configurations?
- How do managed configurations work?
- Can I use managed configurations for Samsung Knox features?
- What is a managed configurations XML schema file?
- Which Samsung apps support managed configurations?
- How do I deploy managed configurations on an MDM console?
- Where can I get the XML schemas for Samsung apps that support managed configurations?
- Is there sample code showing how an MDM web console can deploy an iframe that renders a managed configurations XML schema?
- What email app is preloaded on Samsung devices?
- Knox Service Plugin
- Samsung Email
DualDAR ISV integration
Samsung Knox DualDAR allows enterprises to ensure their work data is secured with two layers of encryption. For details please see the DualDAR architecture.
Knox DualDAR architecture allows ISVs to build and provide their own custom encryption library for the second layer of encryption. ISV developers can provide second layer of encryption via a native library and an Android application. Once provided, Knox DualDAR ensures work data is also protected by the ISV provided custom encryption implementation.
Supported Devices
DualDAR is supported on Galaxy S10, N10, S20, and future flagship models.
Components
Samsung Knox DualDAR consists of the following components:
Knox Workspace
Knox Workspace is a secure container designed to separate, isolate, encrypt, and protect enterprise apps and data. This container enables a mobile phone that provides both work and play environments. Enterprises can remotely manage the work environment, but not access personal information like photos and messages. For additional details, read more about the Knox Workspace.
DualDAR Framework and SDK
DualDAR framework provides classes and APIs that allow:
- UEM solutions to enable creation and configuration of a workspace container with DualDAR protection.
- ISVs to enable third party applications to provide an implementation for an independent second layer of encryption.
For additional details, see the DualDAR API reference and the UEM integration guide.
DualDAR Client
The DualDAR client is the implementation of the second layer of encryption provided by the ISV. The DualDAR client APK is installed on the end user’s device prior to creation of DualDAR Workspace.
It consists of two components:
- File Encryption Component – Native Library
- Key Management and Authentication Component – Android Application
Native Library
The native library is the file encryption component responsible for encryption and decryption of data. ISVs will need to build and include this native library(.so
file) in their android application. The native library runs inside the DualDAR daemon of the android framework and the daemon gives the native library access to the file system. We will refer to this library as DualDAR client library.
Android Application
The Android application is responsible for key management, authentication, installing the native library and other bookkeeping functions. We will refer to this application as DualDAR client application.
Implement the DualDAR client
Create Android Application
As a first step you'll need to create an Android application, targeting Android SDK version 28 and above, that will invoke DualDAR platform APIs and receive platform callbacks. You'll need to mention the target DualDAR SDK version in the manifest file.
Sample DualDAR client AndroidManifest.xml
:
<?xml version="1.0"?> <manifest xmlns:android="http://schemas.android.com/apk/res/android" package="com.samsung.android.knox.test"> <application> <meta-data android:name="supportedDualDarSdkVersion" android:value="1.0"/> <service android:name="com.samsung.android.knox.test.MyDualDARClient"> <intent-filter> <action android:name="com.samsung.android.knox.ddar.BIND_DUAL_DAR_CLIENT"/> </intent-filter> </service> </application> </manifest>
Extend DualDARClient class
Next, you'll need to extend abstract DualDARClient class and implement the callbacks to handle authentication, key management and other tasks. Figure 1
below highlights the various events, callbacks and states. The sections after the diagram provides information on how to extend the abstract class and provide implementation for the client callbacks.
Figure 1: Represents the platform states, user events and the callback client app receives
Client Bringup
During DualDAR workspace creation and user restart (after device restart and data lock state), the client app receives the onClientBringup() callback. The client app should perform all the DualDAR client initialization related activities in this callback.
The client should also install libraries and other supporting files using the installLibrary() API:
- The getInstalledClientLibraryVersion() API can be used to check the current version of the DualDAR library, and get the newest version of the DualDAR library. This will return
null
if no library is installed.
public boolean onClientBringup() { // Install new version of dual dar client library and other files if version mismatch if (!getInstalledClientLibraryVersion().equals(“ < Your client version > ”)) { List < String > secondaryLibs = new ArrayList < > (); secondaryLibs.add(“ < Your secondary file > ”); if (installLibrary(“ < your client library path > ”, secondaryLibs, true) != ERROR_NONE) { Log.e(TAG, "Error installing Dual DAR client lib"); return false; } } return true; }
DualDAR setup
During DualDAR Workspace creation, the DualDAR client app also receives the onDualDARSetupForUser() callback. As part of the setup process, the DualDAR client should generate the necessary keys and secrets as shown by the following sample code:
public boolean onDualDARSetupForUser(int userId) { // Generate Secret (Master Key) and set it to platform for (de)encrypting filesystem byte[] masterKey = generateSecretKey(); Map < String, Byte[] > secrets = new HashMap < > (); Byte[] secretData = new Byte[masterKey.length]; for (int i = 0; i < masterKey.length; i++) { secretData[i] = masterKey[i]; } secrets.put(MASTER_KEY_ALIAS, secretData); setSecret(userId, secrets); // Generate and save salt byte[] salt = generateAndSaveSalt(); // Generate and save default auth token byte[] defAuthToken = generateAndSaveDefAuthToken(); // Encrypt primary key and save saveEncryptedMasterKey(encryptMasterKeyWithPassword(masterKey, defAuthToken, salt)); return true; }
Set secret
During workspace creation and authentication, the client app should pass their secret/keys to the native client library. The native client library uses these secret/keys to encrypt and decrypt file encryption key. The file encryption keys are used to encrypt and decrypt files. The secret should be set when the platform invokes the onDualDARSetupForUser() and onPasswordAuth() callbacks.
Handle Authentication
When the user is authenticated to the DualDAR Workspace, the DualDAR client app receives onPasswordAuth() callback. In this callback, the DualDAR client app should verify the second layer password and set appropriate secret as shown by the following sample code:
public boolean onPasswordAuth(int userId, byte[] password) { byte[] salt = getSalt(); if (password == null) { //get default password password = getDefaultAuthToken(); } // Generate KEK using given auth token SecretKey kek = generateKek(password, salt); // Decrypt the encrypted primary key on disk with KEK and set to platform byte[] masterKey = getSecret(kek, getEncryptedMasterKey()); // Decrypt the encrypted primary key on disk with KEK and set to platform Map<String, Byte[]> secrets = new HashMap<>(); Byte[] secretData = new Byte[masterKey.length]; for(int i=0;i<masterKey.length;i++) { secretData[i] = masterKey[i]; } secrets.put(MASTER_KEY_ALIAS, secretData); setSecret(userId, secrets); return true; }
Handle change password
When the user changes the password for the DualDAR Workspace, the DualDAR client app receives onPasswordChange() callback. DualDAR client app will need to unwrap the existing encrypted primary key and re-wrap the primary key with the new password as shown by the sample code below:
public boolean onPasswordChange(int userId, byte[] oldPassword, byte[] newPassword) { byte[] salt = getSalt(); if(oldPassword == null) { oldPassword = getDefaultAuthToken(); } saveEncryptedMasterKey(reEncryptMasterKeyWithNewPassword( getEncryptedMasterKey(), derivedOldSystemToken, derivedNewSystemToken, salt)); return true; }
Handle reset password
The IT admin can reset the user’s password in case the user has forgotten their password. In order to reset password, the IT admin would need to first setup and activate a token. When the reset password token is set, cleared or reset for DualDAR Workspace, the DualDAR client app is informed via onSetResetPasswordToken(), onClearResetPasswordToken() and onResetPasswordWithToken() callbacks respectively. The DualDAR client app will then need to provision, manage the token and reset password when requested as shown by the following sample code:
public boolean onSetResetPasswordToken(int userId, byte[] password, long tokenHandle, byte[] token) { // Decrypt Master Key using password and re-encrypt with token EncryptedMasterKey reEncryptedMasterKey = null; byte[] salt = getSalt(); if(password == null) { password = getDefaultAuthToken(); } reEncryptedMasterKey = reEncryptMasterKeyWithNewPassword( getEncryptedMasterKey(), password, token, salt); // Save token encrypted Master Key saveTokenEncryptedMasterKey(reEncryptedMasterKey, userId, tokenHandle); // Save token handle addTokenHandleAndSave(userId, tokenHandle); return true; } public void onClearResetPasswordToken(int userId, long tokenHandle) { // Clear token encrypted Master Key removeTokenEncryptedMasterKey(userId, tokenHandle); // Clear token handle removeTokenHandleAndSave(userId, tokenHandle); } public boolean onResetPasswordWithToken(int userId, byte[] newPassword, long tokenHandle, byte[] token) { // Decrypt Master Key using token and re-encrypt with new password EncryptedMasterKey reEncryptedMasterKey = null; byte[] salt = getSalt(); if(newPassword == null) { newPassword = getDefaultAuthToken(); } reEncryptedMasterKey = reEncryptMasterKeyWithNewPassword( getTokenEncryptedMasterKey(userId, tokenHandle), token, newPassword, salt); saveEncryptedMasterKey(reEncryptedMasterKey); return true; }
Implement the native interface
You'll need to build the native library for file encryption and decryption. The native library is installed by the DualDAR client application and loaded in the DualDAR daemon, which provides access to the file system. Details for the native library can be found in the Samsung Mobile Device Management: Native SDK.
Declare entry point
The native interface must have an entry symbol DDAR_ABSTRACT_CRYPTO_SYM
with a type of abstract_crypto
, so that the system daemon can dynamically load the derived class at the time of device boot up. Crypto library must also declare library version by defining a symbol DDAR_ABSTRACT_CRYPTO_VERSION
. This version can be retrieved in the java side by calling getInstalledClientLibraryVersion() API in DualDARClient
.
MyTestCrypto DDAR_ABSTRACT_CRYPTO_SYM; const char * DDAR_ABSTRACT_CRYPTO_VERSION = "1.0";
Native library should perform the following tasks:
Prepare
The prepare
callback is used to initialize crypto
materials prior to encryption and decryption, while the platform provides metadata
object to access persistent and ephemeral storage. It's called for each file after the data locked state or during file creation.
For example, an implementation of prepare
would be to derive the file encryption key (FEK) from the primary key in secret object and store the FEK in the ephemeral cache to be used with encypt/decrypt callbacks:
bool MyTestCrypto::prepare(ddar::context *context, ddar::metadata *md) { ddar::secret *sec = context->get_secret("my_master_key_alias"); # vendor client app defined struct my_metadata *my_md = (struct my_metadata *) md->ephemeral_addr; char *iv = NULL; char efek[FEK_KEYLEN]; int rc = md->persistent_get(ALIAS_EFEK, efek); if (rc <= 0) { // No FEK associate with the file, create new mSSL.rand_bytes(my_md->fek, FEK_KEYLEN); rc = mSSL.encrypt((unsigned char *)my_md->fek, FEK_KEYLEN, (unsigned char *)sec->data, (unsigned char *)iv, (unsigned char *)efek); if (rc < 0) return false; // failed to encrypt efek md->persistent_set(ALIAS_EFEK, efek, FEK_KEYLEN); // store efek } else { mSSL.decrypt((unsigned char *)efek, rc, (unsigned char *)sec->data, (unsigned char *)iv, (unsigned char *)my_md->fek); } }
Encrypt
The encrypt
callback is called when a file is currently being written to disk. The native interface will encrypt the data prior to being written to the disk:
bool MyTestCrypto::encrypt(ddar::metadata *md, void *pt, void *ct, unsigned long page_offset, int page_len) { struct my_metadata *my_md = (struct my_metadata *) md->ephemeral_addr; if(mSSL.encrypt((unsigned char *)pt, page_len, (unsigned char *)my_md->fek, NULL, (unsigned char *)ct) > 0) return true; return false; }
Decrypt
The decrypt
callback is called when a file is currently being read from disk. The native interface will need to decrypt the data in-place:
bool MyTestCrypto::decrypt(ddar::metadata *md, void *ct, unsigned long page_offset, int page_len) { struct my_metadata *my_md = (struct my_metadata *) md->ephemeral_addr; if(mSSL.decrypt((unsigned char *)ct, page_len, (unsigned char *)my_md->fek, NULL, (unsigned char *)ct) > 0) // implement crypto inplace return true; return false; }
Logging
The DualDAR native framework provides the following APIs in the context class to capture logs:
- logd(const char *fmt) – writes debug log to both adb, logcat and dumpstate
- loge(const char *fmt) – writes debug log to both adb, logcat and dumpstate
The Android application can use Log
class to write logs or use its own logging mechanism to write logs.
Logging and Debugging
To get the log files for debugging, contact Samsung support team to get the issue tracker light tool. The tool enables to extract log files. The following list important log files related to DualDAR workspace:
- act_dumpstate.txt – entire framework and app logs are saved here.
- ddar_fw.txt – dualdar framework logs are saved here
- ddar_log.txt – native library logging is saved here.
Deploy the DualDAR client
DualDAR client APK needs to be installed on end user’s device prior to creation of DualDAR Workspace. DualDAR client can either be installed by UEM or be uploaded to a public or private app store.
Need more help?
For more information, see the: