- 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 seat 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 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
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:
Knox 3.2.1 Certificate Policies
- Install CA certificates into a given keystore without requiring user unlock
- Allow or revoke reading private keys to an app
- Add, retrieve, remove, or clear lists of trusted or untrusted CA certificates
- Allow or block the user of removing certificates or resetting the keystore
- Allow or block the installation of apps signed with a non-trusted CA certificate
- Revoke permissions of reading private keys of any application
- Notify users whenever a certificate digital signature failure occurs
- Enable validation of certificates when installing them into device's Certificate Store
Knox 3.2 Certificate Policies
- Allow or revoke reading private keys to an app
- Add, retrieve, remove, or clear lists of trusted or untrusted CA certificates
- Allow or block the user of removing certificates or resetting the keystore
- Allow or block the installation of apps signed with a non-trusted CA certificate
- Revoke permissions of reading private keys of any application
- Notify users whenever a certificate digital signature failure occurs
- Enable validation of certificates when installing them into device's Certificate Store
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