Back to top

Access the TIMA Keystore

This feature was deprecated in API level 33 with Knox SDK v3.7. For more information, see Deprecation of TIMA/CCM Keystore support.

There are many ways to set up Knox and access the TIMA Keystore. Some options, such as setting up the Workspace and populating it with apps, automatically switch to the TIMA Keystore. Other choices, such as an MDM app, can require code changes to handle the switch.

Access TIMA Keystore using apps

Once digital credentials are safely in the TIMA Keystore, there are several ways that they can be accessed by using existing apps:

  • With Samsung email and browser apps — These apps are integrated with the TIMA CCM Keystore so calls to the SmartCardEmailPolicy and SmartCardBrowserPolicy API through the Knox SDK can fetch certificates

  • Through an app in a Knox container — When an app is inside a Knox container, the TIMA keystores automatically become available to it

  • By an MDM administrator — An MDM admin can switch an app’s keystore regardless of whether or not the app is in a Knox Workspace. An MDM admin can even switch the keystore of an ISV app

  • Using the enableTimaKeystorePerApp API — A new version of S Health app (v5.0) has been introduced in the Knox 2.7 timeline. Only the S Health app is integrated with TIMA Keystore, and only a caller app has the permission to access TIMA Keystore with the enableTimeKeystorePerApp API. Note that the S Health app is a native Samsung app that can be provisioned pre-loaded or as a post load app on the device.

Enable the TIMA Keystore per app

  1. Activate License

    EnterpriseLicenseManager licenseMgr = EnterpriseLicenseManager.getInstance(getApplicationContext());
    licenseMgr.activateLicense("0BB8D22F7327ED7BA6A5237B7E8E56C7AD1532D44A6C96E6A5273CB9ADA265EE7A768BD464FDA511AD4B821F1544A68C223E0C5C2C0BD0DCF
    CD51B9ED863337E", "com.example.perapptimakeystore");
    
  2. Check the permission you have.

        int checkKeystore = getApplicationContext().checkCallingOrSelfPermission(KNOX_KEYSTORE_PERMISSION);
        int checkKeystorePerApp = getApplicationContext().checkCallingOrSelfPermission(KNOX_KEYSTORE_PERMISSION_PER_APP);
    
        if (checkKeystore == PackageManager.PERMISSION_GRANTED) {
                Toast.makeText(getApplicationContext(), KNOX_KEYSTORE_PERMISSION + " is granted", Toast.LENGTH_LONG).show();
        } else if (checkKeystorePerApp == PackageManager.PERMISSION_GRANTED) {
        Toast.makeText(getApplicationContext(), KNOX_KEYSTORE_PERMISSION_PER_APP + " is granted", Toast.LENGTH_LONG).show();
        } else {
                Toast.makeText(getApplicationContext(), KNOX_KEYSTORE_PERMISSION  + " and " + KNOX_KEYSTORE_PERMISSION_PER_APP + " are not granted. You can't use
    TimaKeystorePerApp ", Toast.LENGTH_LONG).show();
        }
    
    // If you have one of these permissions: com.samsung.android.knox.permission.KNOX_TIMA_KEYSTORE or com.samsung.android.knox.permission.KNOX_KEYSTORE_PER_APP, you can store
    symmetric key using TimaKeystore.
    
  3. Enable TimaKeystorePerApp

    try {
    if (true == mTKS.enableTimaKeystorePerApp(true)) {
        .....
        }
     }
    

Access TIMA Keystore using Knox SDK

This topic explains how apps (both within and outside the Knox Workspace) can use the TIMA Keystore.

There are two apps, namely APP1 and APP2. APP1 runs inside the Knox Workspace and APP2 runs in the personal side. For each of the apps, TIMA uses a symmetric key. Configure the device so that both APP1 and APP2 use TIMA Keystore for their keys.

Subsequently, the admin decides to disable the TIMA Keystore and prove that no app can use it.

/* get CCM Policy _/
mTimaKeyStorePolicyHandler = EnterpriseKnoxManager.getInstance().getTimaKeystorePolicy(Context);

mTimaKeyStorePolicyHandler.enableTimaKeystore(true);

/_ To enable TimaKeystore for all the apps on the device (both inside and outside container). */

mTimaKeyStorePolicyHandler. isTimaKeystoreEnabled();
*/ Should return true; */
*/ (Returns "true" if enabled, "false" otherwise) */

mTimaKeyStorePolicyHandler.enableTimaKeystore(false);
*/  Use  To disable TimaKeystore for all the apps on the device (both inside and outside container) */

-   mTimaKeyStorePolicyHandler. isTimaKeystoreEnabled();
*/ Should now return false */

Required calls for MDM apps

An EMM admin app has to make the following call to enable the Knox TIMA Keystore:

EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance();
try {
      ekm.getTimaKeystorePolicy().enableTimaKeystore(true);
} catch (SecurityException e) {
      Log.w(TAG, "Exception" + e);
}

The following call checks the status of the TIMA Keystore:

EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance();
try {
      ekm.getTimaKeystorePolicy().isTimaKeystoreEnabled();
} catch (SecurityException e) {
      Log.w(TAG, "Exception" + e);
}

Access TIMA Keystore using the Java Keystore class

The TIMA Keystore and the TIMA CCM Keystore are implemented as a keystore provider for the Java Keystore class and is accessible through the standard Java Keystore class available on Android. The following Java APIs will prove to be the most useful for your app’s needs:

  • Load()
  • setKeyEntery()
  • setEntry()
  • setCertificateEntry()
  • getKey()
  • getEntry()
  • getCertificate()
  • getCertificateChain()
  • Store()

Is this page helpful?