TIMA Keystore

This topic describes the Knox TIMA keystore and how it works in the Knox Workspace container. It is designed to help you take advantage of the digital credential storage features of Samsung devices that have the Knox Workspace container installed. Samsung Knox devices feature the ability to manage security credentials. If a certificate authority (CA) certificate becomes compromised, or for some reason untrustable, they can be disabled or removed, if configured appropriately by the MDM. Depending on the scope (device or app) app developers may also enable or disable the following Knox certificate policies:

• 3.2.1
• 3.2

For more information regarding these Knox policies, refer to the CertificatePolicy, CertificateProvisioning and PermissionApplicationPrivateKey classes. For general information regarding digital credentials, see:

• Working with certificates
• Encrypted Android certificates
• Installing certificates on Android devices
• Android central forum: Credential storage

It’s possible that an Android app can benefit from the high security of a Knox Keystore without any code changes. However, the opposite is also true — an app can only benefit from the high security of a Knox Keystore after making some changes. The extent of these changes depends on the app’s purpose and functionality. Consider the following factors to help determine how much the Android app has to change:

Android Keystore and KeyChain APIs

The Android OS provides APIs for securely storing digital credentials in a keystore and all Android apps can access this keystore by default. The Android Keystore provides cryptographic services, such as encryption and decryption, using the credentials in its store.

Android’s Keystore class supports per-app keys so a key that is created for a given application can’t be accessed by other applications.

Complementary to Android’s Keystore class for per-app keys, the Android KeyChain class allows apps to sign data using system-wide private key/certificate pairs. So, even though the Android Keystore provides per-app access to credentials, the Android KeyChain runs as a system user, and hence, credentials stored through the Android KeyChain are associated with the system ID instead of a user ID.

An application running as a system user has access to the Android KeyChain credentials either through the Android KeyChain API or directly through the Android Keystore API. User applications accessing the Android Keystore directly do not have access to credentials stored by the Android KeyChain, and therefore, must use the Android KeyChain API to access those credentials.

Samsung Knox Keystores

Samsung Knox also offers keystores for digital credentials. These keystores are part of the TrustZone-based Integrity Measurement Architecture (TIMA). The Knox keystores are accessible through Android APIs as long as the app explicitly specifies TIMAKeyStore in the Android KeyStore.getInstance() method.

Knox controls access to all keys based on the trusted boot measurements for the device. During device boot, measurements of aboot and kernel images are collected and compared against Samsung signed measurements. If there is any difference, the device is considered to be booted into a custom kernel. Knox only supports signed, official, versions of the kernel, so in the case of a custom kernel, Knox refuses to store or retrieve keys.

The TrustZone-based Keystore provides apps with services for generating and maintaining cryptographic keys. It encrypts the keys with a device-unique hardware key that can only be decrypted by the hardware from within TrustZone. It performs all cryptographic operations only within TrustZone, and it disables all cryptographic operations if the system is compromised, as determined by Trusted Boot.

TIMA Keystore

One of the Knox Keystores is the TIMA Keystore (TKS). Apps from both inside and outside the Knox Workspace can use the TKS. TKS simply stores and returns digital credentials. It does not perform any operations, such as encryption, decryption, or signing with the digital credentials it is storing. However, there are Knox API which help implement such functions.

The following diagram shows the available Keystore for symmetric keys in each Knox Workspace product:

In summary, the TIMA Keystore provides the following support:

• Support for symmetric keys
• Platform-specific encrypted key files
• Individually encrypted and hardware-bound keys
• Additional integrity protection of encrypted key files
• A device-specific hardware key for wrapping encrypted files
• Encryption of key-storage file names for additional obfuscation
• Protection of keys in the event of compromised system integrity

SE for Android is always enforced

Knox always enforces SE for Android which ensures that only Knox apps can access the TIMA Keystore. Otherwise, a non-Knox app on a good Knox device can access the Keystore and then read the enterprise data.

TIMA Keystore operations

Initialize the TIMA Keystore before:

• Installing a key into the Keystore
• Retrieving a key from the Keystore

The following two security conditions must be met before installing or retrieving a key:

• The Warranty violation bit is intact
• Boot-time measurements are a match to the TrustZone PKM values

You need to specify which key (ID) to install or retrieve:

• The ID specified is the position in the Keystore
• The position is converted to the offset in the file for reading (retrieving the key) or writing (installing the key)

TIMA CCM Keystore

The CCM keystore is also part of TIMA. It supports asymmetric keys and it provides cryptographic operations based on the credentials such as encrypting, decrypting, and signing. The TIMA CCM Keystore provides a trusted way to use the private half of an asymmetric key and perform cryptographic operations on information that was encrypted with the public portion of the key. The following diagram shows the available keystore for asymmetric keys in each Knox Workspace product:

The TIMA CCM Keystore supports interfaces for the following:

• Installing PKCS 12 and PEM certificates
• Installing encrypted PKCS 8 private key/certificate files
• Requests for key-pair generation followed by certificate signing requests
• Leveraging the default, pre-installed, client certificates which are signed by the device root key and which uniquely identify the device

Once the keys are created and stored in the TIMA CCM Keystore, they can only be accessed under the PKCS 11 cryptographic token standard which mandates password-based logins for sensitive cryptographic operations. Apps can worked with these stored credentials through the following APIs:

• Knox SDK APIs — MDM admins can push certificates into the TIMA CCM Keystore, generate certification signing requests, and administer the TIMA CCM Keystore by calling the Knox SDK APIs
• Android KeyChain APIs — The TIMA CCM Keystore is integrated with the Android KeyChain so that Android apps can transparently access it by using the regular Android KeyChain interface

Possible limitations of switching keystores

If you decide to switch keystores for your digital credentials, it’s possible that the format of some of the stored credentials will not be supported in the new keystore.

Compatibility between the credentials that an app stores in the Android keystore and a newly selected keystore is not certain. For example, the TIMA CCM Keystore supports certain asymmetric key formats which may not include the format used by a given app. Consequently, the availability of a new keystore doesn’t mean that the new keystore is a better option. It’s possible that the original keystore was the better option.

Credential storage spaces and types

Knox supports Samsung’s Universal Credential Management (UCM) framework and API. An Android app can bypass the proprietary API of storage vendors by using the UCM framework and API instead. For example, an app that needs to store digital credentials in both a SIM card and the embedded Secure Element (eSE), needs to call APIs that are specific to each type of storage. This overhead complicates app development, deployment, and maintenance. The UCM APIs, instead, provide a single interface for both types of storage as shown below:

For more information regarding the Samsung UCM framework, refer to UCM Overview.

Provisioning digital certificates

Mobile apps such as email, Wi-Fi, browser, and so on, use digital certificates for authentication, digital signatures, and encryption. CEP enables MDMs and third-parties to perform certificate enrollment without the need of any manual intervention.

Apps use the CEP service to to acquire the public part of an asymmetric key. Asymmetric keys have a public part and a private part. The private part never leaves the Keystore, but the public part is distributed freely. An app uses the Samsung Knox CEP service to acquire the public part of the key, encrypt a message, and send the encrypted message to whoever issued the public key. The owner of the key can then use the Keystore’s functionality to apply the private part of the asymmetric key to the encrypted message and decrypt it.

Certificate operations using CEP service

Using the Samsung Knox Certificate Enrollment Policy APIs, you can perform the following operations:

• Enroll certificates
• Renew certificates
• Delete certificates
• Check enrollment or renewal status