Since: API level 12
public class

ClientCertificateManager

extends Object
java.lang.Object
   ↳ com.samsung.android.knox.keystore.ClientCertificateManager

Class Overview

This class provides APIs for managing certificates in TIMA Client Certificate Manager (CCM). Client Certificate Manager is a virtual Smart Card on the device. Certificates stored in CCM are managed securely in TrustZone. This class provides APIs to provision certificates in CCM and to use device default certificate. CCM allows per package access control to access installed certificates.

Device Default Certificate is a device unique certificate rooted at Samsung root certificate. It can be used to uniquely identify a Samsung device.

Certificates installed in CCM can be accessed using TimaKeystore. CCM Keys can also be accessed via KeyChain. In order to use certificates from CCM via KeyChain, TimaKeystore must be enabled.

WifiPolicy allows Wi-Fi configuration to be set to fetch certificate from CCM Smart Card token.

Smart Card token is the storage space allocated to the caller in TrustZone. A Smart Card token can be requested by calling setCCMProfile(CCMProfile) which allocates Smart Card token to the caller. Access to allocated Smart Card token can be controlled with CCMProfile. Only the packages whitelisted to access the allocated token will be able to use installed certificates in the token. Smart Card token is isolated at user scope. Certificates installed in Owner space or a container are isolated from other containers. Smart Card token must be requested for each container by calling setCCMProfile(CCMProfile).

As a first step to enable and use Client Certificate Manager setCCMProfile(CCMProfile) must be called as other Client Certificate Manager APIs require a Smart Card token to be already allocated to the caller. Once a token is allocated, certificates can be installed and access control to certificates can be enforced.

Access to the allocated token can be controlled. CCMProfile provides various access control methods that can be enforced.

Certificates and Keys provisioned in CCM can be accessed using PKCS11 APIs. Please refer to CCM Description and PKCS11 API Document for detailed description of TZ based smart card and supported PKCS11 APIs.

Certificate Signing Request can be generated in the allocated token using setCSRProfile(CSRProfile) and generateCSRUsingTemplate(String, String, String) APIs.

installCertificate(CertificateProfile, byte[], String) API installs certificates in the token. Access to the installed certificate can be controlled with CertificateProfile.

Applications which need access to certificates without user interaction can be exempted from enforced access control method using addPackageToExemptList(String) and can be removed from the exemption list using removePackageFromExemptList(String). Exemption list can be managed for applications which need access to certificates even when the user is not interacting with the device.

Since
API level 12
KNOX 2.1

Summary

Public Methods
boolean addPackageToExemptList(String packageName)
API to exempt a package from access control enforced using CCMProfile.
boolean deleteCCMProfile()
API to delete Client Certificate Manager profile set using setCCMProfile(CCMProfile).
boolean deleteCSRProfile(String templateName)
API to delete a Certificate Signing Request template set using setCSRProfile(CSRProfile).
boolean deleteCertificate(String alias)
API to delete an installed certificate from the token.
byte[] generateCSRUsingTemplate(String templateName, String alias, String challengePassword)
API to generate Certificate Signing Request (CSR) using the template set with setCSRProfile(CSRProfile).
CCMProfile getCCMProfile()
API to get the Client Certificate Manager profile set using setCCMProfile.
String getCCMVersion()
API to get Client Certificate Manager version.
String getDefaultCertificateAlias()
API to get device default certificate alias.
boolean installCertificate(CertificateProfile profile, byte[] certificateBuffer, String privateKeyPassword)
API to install a certificate in the allocated Smart Card token.
boolean isCCMPolicyEnabledForPackage(String packageName)
API to check whether Client Certificate Manager is enabled for a package.
boolean removePackageFromExemptList(String packageName)
API to remove a package from access control exempt list.
boolean setCCMProfile(CCMProfile profile)
API to setup Client Certificate Manager profile.
boolean setCSRProfile(CSRProfile profile)
API to set the Certificate Signing Request (CSR) template.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public boolean addPackageToExemptList (String packageName)

Since: API level 12

API to exempt a package from access control enforced using CCMProfile. This is required in case an appplication (running in background) need access to certificates when the device/container is locked or user is not expected to enter password. An example package which needs exemption could be a third party VPN applicaiton which needs access to certificates without user interaction.

Parameters
packageName Name of the package to be exempted from access control.
Returns
  • true if success, else false
Throws
SecurityException If caller does not have required permissions.
Usage

API to add a package to access control exempt list.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

 

  boolean result = clientCertificateManager

          .addPackageToExemptList("packageName");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.addPackageToExemptList("packageName");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 

Permission
Use of this API requires caller to have "com.samsung.android.knox.permission.KNOX_CCM_KEYSTORE" permission which has protection level of signature.

Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean deleteCCMProfile ()

Since: API level 12

API to delete Client Certificate Manager profile set using setCCMProfile(CCMProfile). This API deletes the allocated Smart Card token for the caller along with all installed certificates and CSRs in the token.

Returns
  • true if success, else false
Throws
SecurityException If no permission
Usage

Delete the allocated Client Certificate Manager token.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

  boolean result = clientCertificateManager.deleteCCMProfile();

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.deleteCCMProfile();

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 
Permission
Use of this API requires caller to have "com.samsung.android.knox.permission.KNOX_CCM_KEYSTORE" permission which has protection level of signature.
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean deleteCSRProfile (String templateName)

Since: API level 12

API to delete a Certificate Signing Request template set using setCSRProfile(CSRProfile). The template name should be the same as specified with setCSRProfile(CSRProfile)

Parameters
templateName Name of the CSR template to be deleted.
Returns
  • true if success, else false
Usage

API to delete CSR template set using setCSRProfile(CSRProfile).


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.deleteCSRProfile("templateName"});

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.deleteCSRProfile("templateName"});

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 

Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean deleteCertificate (String alias)

Since: API level 12

API to delete an installed certificate from the token. This API deletes the specified certificate from the Smart Card token of the caller,

Returns
  • true if success, else false
Usage

Delete an installed certificate in the allocated Smart Card token.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

  boolean result = clientCertificateManager

          .deleteCertificate("certificateAlias");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.deleteCertificate("certificateAlias");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public byte[] generateCSRUsingTemplate (String templateName, String alias, String challengePassword)

Since: API level 12

API to generate Certificate Signing Request (CSR) using the template set with setCSRProfile(CSRProfile). Certificate SigningRequest is based of the RSA kepair generated in TrustZone and is signed using the generated private key.

Parameters
templateName Name of the template to be used for generating CSR. This should be one of template names set using setCSRProfile(CSRProfile)
challengePassword challengePassword attribute to be included in the generated CSR. challengePassword is optional. It may be required in case of SCEP which requires the generated CSR to include challengePassword attribute.
Returns
  • Generated CSR bytes if operation is successful, null if Client Certificate Manager fails to generate the CSR.
Usage

Generate Certificate Signing Request using a template.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

  byte[] csr = clientCertificateManager.generateCSRUsingTemplate(

          "templateName", "csrAlias", "challengePassword");

  if (csr) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  byte[] csr = clientCertificateManager.generateCSRUsingTemplate(

          "templateName", "csrAlias", "challengePassword");

  if (csr) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public CCMProfile getCCMProfile ()

Since: API level 12

API to get the Client Certificate Manager profile set using setCCMProfile.

Returns

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm.getClientCertificateManagerPolicy(); 

 

 try {

  CCMProfile ccmProfile = clientCertificateManager.getCCMProfile();

  if (null == ccmProfile) {

      // Failed

  } else {

      // Success

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  CCMProfile ccmProfile = clientCertificateManager.getCCMProfile(CCMProfile);

  if (null == ccmProfile) {

      // Failed

  } else {

      // Success

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 

Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public String getCCMVersion ()

Since: API level 12

API to get Client Certificate Manager version. Version is returned in the format "X.Y" where X is major version number and Y is minor version number. Example "3.0".

Returns
  • CCM version if CCM is available on the device, else null
Usage

Get Client Certificate Manager version.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

         .getClientCertificateManagerPolicy();

 

 try {

     String version = clientCertificateManager.getCCMVersion();

     if (null != version) {

         // Obtained CCM version

     } else {

         // CCM is not available on the device

     }

 } catch (Exception e) {

     Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  String version = clientCertificateManager.getCCMVersion();

  if (null != version) {

      // Obtained CCM version

  } else {

      // CCM is not available on the device

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public String getDefaultCertificateAlias ()

Since: API level 12

API to get device default certificate alias. Device Default Certificate is a device unique certificate rooted at Samsung root certificate. It can be used to uniquely identify a Samsung device.

Returns
  • Device default certificate alias if default certificate is available on the device, else null
Usage

Get device default certificate alias.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

  String alias = clientCertificateManager.getDefaultCertificateAlias();

  if (null != alias) {

      // use device default certificate alias

  } else {

      // default certificate is not available on the device

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  String alias = clientCertificateManager.getDefaultCertificateAlias();

  if (null != alias) {

      // use device default certificate alias

  } else {

      // default certificate is not available on the device

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean installCertificate (CertificateProfile profile, byte[] certificateBuffer, String privateKeyPassword)

Since: API level 12

API to install a certificate in the allocated Smart Card token. With CertificateProfile caller can control access to the certificate. Only packges whitelisted using setCCMProfile(CCMProfile) can be allowed access to the certificate being installed. getCCMProfile() retrieves the list of packages allowed access to the token. Certificate installed can be accessed using PKCS11 APIs provided by CCM. Please refer to CCM and PKCS11 API Document for detailed description of CCM APIs and supported PKCS11 APIs.

This API accepts certificate in PKCS12 or PEM format only. CCM can store maximum of 30 certificates (certificate + private key pairs).

Parameters
profile CertificateProfile describing the certificate behavior.
certificateBuffer byte array of the certificate in PKCS12 or PEM format.
privateKeyPassword Certificate password.
Returns
  • true if success, else false
Usage

Install a Certificate in the allocated CCM Smart Card token.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.installCertificate(CertificateProfile, certificateBuffer, "privateKeyPassword");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.installCertificate(CertificateProfile, certificateBuffer, "privateKeyPassword");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 

Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean isCCMPolicyEnabledForPackage (String packageName)

Since: API level 12

API to check whether Client Certificate Manager is enabled for a package.

Parameters
packageName Package name to verify whether CCM is enabled for it .
Returns
  • true if success, else false
Usage

Check whether Client Certificate Manager is enabled for a package.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

  boolean result = clientCertificateManager

          .isCCMPolicyEnabledForPackage("packageName");

  if (result) {

      // true if enabled

  } else {

      // false if not enabled

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.isCCMPolicyEnabledForPackage("packageName");

  if (result) {

      // true if CCM is enable for the package

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean removePackageFromExemptList (String packageName)

Since: API level 12

API to remove a package from access control exempt list. A package exempted from access control using addPackageToExemptList(String) can be removed from the exempt list using this API.

Parameters
packageName Name of the package to be removed from access control exempt list.
Returns
  • true if success, else false
Throws
SecurityException If caller does not have required permissions.
Usage

API to remove a package from access control exempt list.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm

      .getClientCertificateManagerPolicy();

 

 try {

  boolean result = clientCertificateManager

          .removePackageFromExemptList("packageName");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.removePackageFromExemptList("packageName");

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 

Permission
Use of this API requires caller to have "com.samsung.android.knox.permission.KNOX_CCM_KEYSTORE" permission which has protection level of signature.

Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean setCCMProfile (CCMProfile profile)

Since: API level 12

API to setup Client Certificate Manager profile. This API enables Client Certificate Manager and allocates a Smart Card token on the device for the caller. With CCMProfile caller can control access to the token. Certificates can be installed in the token with installCertificate(CertificateProfile, byte[], String)

Returns
  • true if success, else false
Throws
SecurityException If no permission

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.setCCMProfile(CCMProfile profile);

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.setCCMProfile(CCMProfile profile);

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (SecurityException e) {

  Log.w(TAG, "SecurityException: " + e);

 }

 

Permission
Use of this API requires caller to have "com.samsung.android.knox.permission.KNOX_CCM_KEYSTORE" permission which has protection level of signature.
Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope

public boolean setCSRProfile (CSRProfile profile)

Since: API level 12

API to set the Certificate Signing Request (CSR) template. CSR template can be defined with CSRProfile parameters. This API defines the CSR template to be used for generating the CSR. generateCSRUsingTemplate(String, String, String) generates the CSR using the set template.

Parameters
profile CSRProfile object describing the CSR template.
Returns
  • true if success, else false
Usage

API to define CSR template to be used for generating CSRs.


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 ClientCertificateManager clientCertificateManager = ekm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.setCSRProfile(CSRProfile);

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 
For Container:

 // When you create container successfully, containerID will be returned via intent.

 // Use this containerID in below API.

 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);

 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);

 ClientCertificateManager clientCertificateManager = kcm.getClientCertificateManagerPolicy(); 

 

 try {

  boolean result = clientCertificateManager.setCSRProfile(CSRProfile);

  if (result) {

      // Success

  } else {

      // Failed

  }

 } catch (Exception e) {

  Log.w(TAG, "Exception: " + e);

 }

 

Since
API level 12
KNOX 2.1
Multiuser Environment
User Scope