Since: API level 27
public class

CertificateProvisioning

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

Class Overview

This class provides APIs to manage certificates and keystores.

Summary

Constants
String CA_CERTIFICATE Key prefix for CA certificates.
int ERROR_KEYSTORE_KEY_NOT_FOUND KeyStore error code
int ERROR_KEYSTORE_LOCKED KeyStore error code
int ERROR_KEYSTORE_NONE KeyStore error code
int ERROR_KEYSTORE_PERMISSION_DENIED KeyStore error code
int ERROR_KEYSTORE_PROTOCOL KeyStore error code
int ERROR_KEYSTORE_SYSTEM KeyStore error code
int ERROR_KEYSTORE_UNDEFINED_ACTION KeyStore error code
int ERROR_KEYSTORE_UNINITIALIZED KeyStore error code
int ERROR_KEYSTORE_VALUE_CORRUPTED KeyStore error code
int ERROR_KEYSTORE_WRONG_PASSWORD KeyStore error code
int KEYSTORE_DEFAULT Flag to indicate Android Default keystore.
int KEYSTORE_FOR_VPN_AND_APPS Flag to indicate VPN and applications keystore.
int KEYSTORE_FOR_WIFI Flag to indicate Wifi keystore.
String TYPE_CERTIFICATE Type for CA certificates.
String TYPE_PKCS12 Type for user certificates.
String USER_CERTIFICATE Key prefix for user certificates.
Public Methods
boolean addPackagesToCertificateWhiteList(List<AppIdentity> packageList)
API to configure packages without MDM permissions to manage certificates in the device.
boolean deleteCertificateFromKeystore(CertificateInfo certInfo, int keystore)
API to remove or disable a certificate from the given keystore(s).
List<CertificateInfo> getCertificatesFromKeystore(int keystore)
API to get the list of certificates kept by the given keystore(s).
int getCredentialStorageStatus()
API to get the current credential storage (Default, Wifi and VPN and applications keystores) state.
List<AppIdentity> getPackagesFromCertificateWhiteList()
API to get a list of trusted applications that are whitelisted for using MDM certificate management APIs.
List<CertificateInfo> getSystemCertificates()
API to get the list of system pre-loaded certificates in the device.
boolean installCertificateToKeystore(String type, byte[] value, String name, String password, int keystore)
API to install a certificate into the given keystore(s) silently.
void installCertificateWithType(String type, byte[] value)
API to install certificates on the device.
void installCertificatesFromSdCard()
API to install all certificates found on the SD card of types TYPE_CERTIFICATE and TYPE_PKCS12.
boolean removePackagesFromCertificateWhiteList(List<AppIdentity> packageList)
API to remove applications from certificate white list.
boolean resetCredentialStorage()
API to reset credential storage.
boolean unlockCredentialStorage(String password)
API to unlock the credential storage.
[Expand]
Inherited Methods
From class java.lang.Object

Constants

public static final String CA_CERTIFICATE

Since: API level 27

Key prefix for CA certificates.

Since
API level 2
MDM 2.0
Constant Value: "CACERT_"

public static final int ERROR_KEYSTORE_KEY_NOT_FOUND

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 7 (0x00000007)

public static final int ERROR_KEYSTORE_LOCKED

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 2 (0x00000002)

public static final int ERROR_KEYSTORE_NONE

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 1 (0x00000001)

public static final int ERROR_KEYSTORE_PERMISSION_DENIED

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 6 (0x00000006)

public static final int ERROR_KEYSTORE_PROTOCOL

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 5 (0x00000005)

public static final int ERROR_KEYSTORE_SYSTEM

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 4 (0x00000004)

public static final int ERROR_KEYSTORE_UNDEFINED_ACTION

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 9 (0x00000009)

public static final int ERROR_KEYSTORE_UNINITIALIZED

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 3 (0x00000003)

public static final int ERROR_KEYSTORE_VALUE_CORRUPTED

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 8 (0x00000008)

public static final int ERROR_KEYSTORE_WRONG_PASSWORD

Since: API level 27

KeyStore error code

Since
API level 2
MDM 2.0
Constant Value: 10 (0x0000000a)

public static final int KEYSTORE_DEFAULT

Since: API level 27

Flag to indicate Android Default keystore. This keystore keeps CA certificates and it is used by Browser and Email to verify if a certain entity is trusted or not. For Wifi connection certificates, see KEYSTORE_FOR_WIFI

Since
API level 11
MDM 5.0
Multiuser Environment
User Scope

NOTE: Since MDM 5.3, default keystore is considered as User scope.
Constant Value: 1 (0x00000001)

public static final int KEYSTORE_FOR_VPN_AND_APPS

Since: API level 27

Flag to indicate VPN and applications keystore. Certificates installed into this keystore are used for VPN connections and by some applications such as Browser. It keeps both CA and user certificates and works as a complement of Android Default keystore.

Since
API level 11
MDM 5.0
Multiuser Environment
User Scope

NOTE: Since MDM 5.1, VPN and Apps keystore is considered as User scope.
Constant Value: 4 (0x00000004)

public static final int KEYSTORE_FOR_WIFI

Since: API level 27

Flag to indicate Wifi keystore. Certificates installed into this keystore are used for Wifi authentication. It keeps both CA and user certificates.

Since
API level 11
MDM 5.0
Multiuser Environment
Global Scope
Constant Value: 2 (0x00000002)

public static final String TYPE_CERTIFICATE

Since: API level 27

Type for CA certificates.

Since
API level 2
MDM 2.0
Constant Value: "CERT"

public static final String TYPE_PKCS12

Since: API level 27

Type for user certificates.

Since
API level 2
MDM 2.0
Constant Value: "PKCS12"

public static final String USER_CERTIFICATE

Since: API level 27

Key prefix for user certificates.

Since
API level 2
MDM 2.0
Constant Value: "USRCERT_"

Public Methods

public boolean addPackagesToCertificateWhiteList (List<AppIdentity> packageList)

Since: API level 27

API to configure packages without MDM permissions to manage certificates in the device.

Parameters
packageList List of AppIdentity containing applications that shall be able to call MDM APIs to manage certificates.
Returns
  • True if the list of applications have been successfully added to the whitelist, false if at least one application has failed to be added to the whitelist.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to provide permissions to a trusted application to use certificate management APIs without being an active admin nor having MDM permissions.
A package whitelisted with this policy will be able to call the set of APIs listed below.

Standard SDK:

Premium SDK:

Please refer to Certificate Enrollment APIs in com.samsung.android.knox.keystore package. The whitelisted application will be able to do certificate enrollment under SCEP and EST protocol without any MDM permissions. As the APIs related to this feature are only available in Premium SDK, the administrator that has whitelisted the application must have been activated with KLM license. Otherwise, the whitelisted application will not be able to use such feature.

 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

 try {
     // In order to validate the application's signature, fill this variable with the desired
     // signature.
     String signature = null;
 
     // List of packages that shall be able to use certificate management APIs
     List<AppIdentity> packageList = new ArrayList<AppIdentity>();
     packageList.add(new AppIdentity("com.trusted.app", signature));
 
     boolean result = certProvisioning.addPackagesToCertificateWhiteList(packageList);
     if (result == true) {
         // List of packages successfully added to certificate management whitelist
     }
 } 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);
 CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();

 try {
     // In order to validate the application's signature, fill this variable with the desired
     // signature.
     String signature = null;
 
     // List of packages that shall be able to use certificate management APIs
     List<AppIdentity> packageList = new ArrayList<AppIdentity>();
     packageList.add(new AppIdentity("com.trusted.app", signature));
 
     boolean result = certProvisioning.addPackagesToCertificateWhiteList(packageList);
     if(result == true) {
         // List of packages successfully added to certificate management whitelist
     }
 } catch(SecurityException e) {
     Log.w(TAG, "SecurityException: "+ e);
 }
 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 24
Multiuser Environment
User Scope

public boolean deleteCertificateFromKeystore (CertificateInfo certInfo, int keystore)

Since: API level 27

API to remove or disable a certificate from the given keystore(s).

Parameters
certInfo Certificate wrapper containing the certificate object (X509Certificate) to be removed from keystore(s).
keystore Keystore(s) from where certificates must be removed or disabled. Possible values are KEYSTORE_DEFAULT, KEYSTORE_FOR_WIFI and KEYSTORE_FOR_VPN_AND_APPS if caller is on owner scope. If caller is in an user, KEYSTORE_FOR_WIFI keystore cannot be used, otherwise the API will throw a SecurityException. These values are bitwise and can be combined with logical OR.
Returns
  • true if certificate was removed from keystore(s) successfully, false otherwise.
Throws
SecurityException If caller does not have required permissions or caller is in a guest user or container trying to iterate with a global keystore, e.g. KEYSTORE_FOR_WIFI)
Usage
An administrator can use this API to silently uninstall a certificate from certain keystore(s) or disable system pre-loaded ones (as this kind of certificate cannot be deleted).

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  String filePath = "/sdcard/class2.crt";
  byte[] certData = getByteArray(filePath); //internal function to retrieve
                                            //byte array from file.

  try {
      boolean result1, result2;
      CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
      X509Certificate cert = (X509Certificate) certFactory
              .generateCertificate(new ByteArrayInputStream(certData));

      CertificateInfo certInfo = new CertificateInfo(cert);

      // uninstalling certificate from Android Default keystore
      // if certInfo is a system certificate, then it will only be disabled in system.
      result1 = certProvisioning.deleteCertificateFromKeystore(certInfo,
               CertificateProvisioning.KEYSTORE_DEFAULT);

      if(CertificateProvisioning.ERROR_KEYSTORE_NONE ==
           certProvisioning.getCredentialStorageStatus()) {
           // uninstalling certificate from Wifi and VPN and Apps keystores (it will only work for owner space)
           result2 = certProvisioning.deleteCertificateFromKeystore(certInfo,
              CertificateProvisioning.KEYSTORE_FOR_WIFI | CertificateProvisioning.KEYSTORE_FOR_VPN_AND_APPS);
      }

      if(result1 == true) {
          // certificate successfully removed/disabled from Android Default keystore
      }

      if(result2 == true) {
          // certificate successfully removed from WiFi and VPN and Apps keystores
      }
  } catch(SecurityException e) {
      Log.w(TAG, "SecurityException: "+ e);
  } catch (CertificateException e) {
      Log.w(TAG, "CertificateException: " + 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);
  CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();

  String filePath = "/sdcard/class2.crt";
  byte[] certData = getByteArray(filePath); //internal function to retrieve
                                            //byte array from file.

  try {
      boolean result = false;
      CertificateFactory certFactory = CertificateFactory.getInstance("X.509");
      X509Certificate cert = (X509Certificate) certFactory
              .generateCertificate(new ByteArrayInputStream(certData));

      CertificateInfo certInfo = new CertificateInfo(cert);

      // uninstalling certificate from VPN and applications keystore
      result = certProvisioning.deleteCertificateFromKeystore(certInfo,
              CertificateProvisioning.KEYSTORE_FOR_VPN_AND_APPS);

      if(result == true) {
          // certificate successfully removed from VPN and Apps keystore of container
      }
  } catch(SecurityException e) {
      Log.w(TAG, "SecurityException: "+ e);
  } catch (CertificateException e) {
      Log.w(TAG, "CertificateException: " + e);
  }
 
NOTE: This API will return false if KEYSTORE_DEFAULT is used as keystore parameter and container is in locked state.

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 11
MDM 5.0
Multiuser Environment
User Scope

public List<CertificateInfo> getCertificatesFromKeystore (int keystore)

Since: API level 27

API to get the list of certificates kept by the given keystore(s).

Parameters
keystore Keystore(s) from where certificates must be retrieved. Possible values are KEYSTORE_DEFAULT, KEYSTORE_FOR_WIFI, and KEYSTORE_FOR_VPN_AND_APPS if caller is on owner scope. If caller is in an user, KEYSTORE_FOR_WIFI keystore cannot be used, otherwise the API will throw a SecurityException. These values are bitwise and can be combined with logical OR.
Returns
  • list of certificates kept by the given keystore(s) or an empty list if none are found or null if some error occurred.
Throws
SecurityException If caller does not have required permissions or caller is in a guest user or container trying to iterate with a global keystore, e.g. KEYSTORE_FOR_WIFI)
Usage
An administrator can use this API to get a list containing all certificates stored in certain keystore(s). This API returns a list containing CertificateInfo objects, which are wrappers to Certificate type objects; cast to X509Certificate in order to read them in a detailed manner.

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  try {

     //retrieving certificates from all keystores (this call will work only on owner space):
     List<CertificateInfo> list = certProvisioning.getCertificatesFromKeystore
             (CertificateProvisioning.KEYSTORE_DEFAULT |
             CertificateProvisioning.KEYSTORE_FOR_WIFI |
             CertificateProvisioning.KEYSTORE_FOR_VPN_AND_APPS);

     if (list != null && !list.isEmpty()) {
         X509Certificate cert;

         for(CertificateInfo certInfo : list) {
             Log.d(TAG, "Preloaded : " + certInfo.getSystemPreloaded()
                     + ". Enabled : " + certInfo.getEnabled());

             cert = (X509Certificate)certInfo.getCertificate();
             Log.d(TAG, "Version :" + cert.getVersion()
                     + ". Serial no.: " + cert.getSerialNumber().toString());
         }
     }
  } 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);
  CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();

  try {

     // retrieving certificates from VPN and Apps keystore
     List<CertificateInfo> list = certProvisioning.getCertificatesFromKeystore
             (CertificateProvisioning.KEYSTORE_FOR_VPN_AND_APPS);

     if (list != null && !list.isEmpty()) {
         X509Certificate cert;

         for(CertificateInfo certInfo : list) {
             cert = (X509Certificate)certInfo.getCertificate();
             Log.d(TAG, "Version :" + cert.getVersion()
                     + ". Serial no.: " + cert.getSerialNumber().toString());
         }
     }
  } catch(SecurityException e) {
     Log.w(TAG,"SecurityException: "+e);
  }
 
NOTE: This API will return an empty list if KEYSTORE_DEFAULT is used as keystore parameter and container is in locked state.

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.
Since
API level 11
MDM 5.0
Multiuser Environment
User Scope

public int getCredentialStorageStatus ()

Since: API level 27

API to get the current credential storage (Default, Wifi and VPN and applications keystores) state.

Returns
Throws
SecurityException If caller does not have required permissions
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.
Usage
An administrator can use this API to check whether a password has already been set to a credential storage, thus if it is ready to be used or not. Certificates can only be installed, listed or deleted from Default, Wifi or VPN and applications keystores when credential storage is in ERROR_KEYSTORE_NONE state.

Since
API level 2
MDM 2.0
Multiuser Environment
User Scope

public List<AppIdentity> getPackagesFromCertificateWhiteList ()

Since: API level 27

API to get a list of trusted applications that are whitelisted for using MDM certificate management APIs.

Returns
  • List of AppIdentity containing all applications that have been trusted to use certificate management APIs or null if some failed has occurred to get whitelisted packages.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to get the list of whitelisted applications that have been trusted to call MDM certificate management APIs without requiring any special permissions.
 EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();
 
 try {
     // Retrieving all whitelisted trusted applications that are able to call
     // MDM APIs to manage certificates
     List<AppIdentity> packageList = certProvisioning.getPackagesFromCertificateWhiteList();
 } 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);
 CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();

 try {
     // Retrieving all trusted applications that are able to call
     // MDM APIs to manage certificates
     List<AppIdentity> packageList = certProvisioning.getPackagesFromCertificateWhiteList();
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }
 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 24
Multiuser Environment
User Scope

public List<CertificateInfo> getSystemCertificates ()

Since: API level 27

API to get the list of system pre-loaded certificates in the device.

Returns
  • A list containing the certificates or an empty list if none are found when successful, else null on failure.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to get the list of system pre-loaded certificates for a specific user. These certificates are used by Email and Browser applications to identify trusted entities. This API returns a list containing CertificateInfo objects, which are wrappers to Certificate type objects; cast to X509Certificate in order to read them in a detailed manner.

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  try {
      List<CertificateInfo> list = certProvisioning.getSystemCertificates();
      if (!list.isEmpty()) {
         X509Certificate cert;

         for(CertificateInfo certInfo : list) {
             Log.d(TAG, "Enabled : " + certInfo.getEnabled());

             cert = (X509Certificate)certInfo.getCertificate();
             Log.d(TAG, "Version :" + cert.getVersion()
                     + ". Serial no." + cert.getSerialNumber().toString())
         }
      }
  } 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);
       CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();
       try {
           List<CertificateInfo> list = certProvisioning.getSystemCertificates();
           if (!list.isEmpty()) {
               X509Certificate cert;

               for(CertificateInfo certInfo : list) {
                   Log.d(TAG, "Enabled : " + certInfo.getEnabled());

                   cert = (X509Certificate)certInfo.getCertificate();
                   Log.d(TAG, "Version :" + cert.getVersion()
                         + ". Serial no." + cert.getSerialNumber().toString())
               }
           }
       } catch(SecurityException e) {
           Log.w(TAG,"SecurityException: "+e);
       }
       

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.
Since
API level 2
MDM 2.0
Multiuser Environment
User Scope

public boolean installCertificateToKeystore (String type, byte[] value, String name, String password, int keystore)

Since: API level 27

API to install a certificate into the given keystore(s) silently.

Parameters
type TYPE_CERTIFICATE or TYPE_PKCS12.
value A non-empty byte array containing the certificate data.
name A non-empty String with the alias to identify the certificate in KeyStore.
password A non-null String with the password to decrypt the input
keystore Target keystore for certificate installation. Possible values are KEYSTORE_DEFAULT, KEYSTORE_FOR_WIFI and KEYSTORE_FOR_VPN_AND_APPS if caller is on owner scope. If caller is in an user, KEYSTORE_FOR_WIFI keystore cannot be used, otherwise the API will throw a SecurityException. These values are bitwise and can be combined with logical OR.
Returns
  • true if certificate is installed successfully to all selected keystores, false if it failed installing to at least one keystore (even if it successfully installed on other keystores).
Throws
SecurityException If caller does not have required permissions or caller is in a guest user or container trying to iterate with a global keystore, e.g. KEYSTORE_FOR_WIFI)
Usage
An administrator can use this API to install certificates of type TYPE_CERTIFICATE or TYPE_PKCS12 silently without user interaction. Possible target keystores are KEYSTORE_DEFAULT, KEYSTORE_FOR_WIFI and KEYSTORE_FOR_VPN_AND_APPS when caller is on owner space. If caller is in an user, KEYSTORE_FOR_WIFI keystore cannot be used, otherwise the API will throw a SecurityException. The credential storage must be in ERROR_KEYSTORE_NONE state (screen lock set with a Password or PIN), otherwise this API will fail. In order to get the credential storage state, please consider using getCredentialStorageStatus() API.

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  String filePath = "/sdcard/class3.crt";
  byte[] certData = getByteArray(filePath); //internal function to retrieve
                                            //byte array from file.
  try {
      boolean result1, result2;

      //installing into Wifi keystore (it will only work for owner space):
      result1 = certProvisioning.installCertificateToKeystore
              (CertificateProvisioning.TYPE_CERTIFICATE, certData, "mycert", "123456",
              CertificateProvisioning.KEYSTORE_FOR_WIFI);

      //installing into Wifi and VPN and Apps keystores (it will only work for owner space):
      if(CertificateProvisioning.ERROR_KEYSTORE_NONE ==
           certProvisioning.getCredentialStorageStatus()) {
           result2 = certProvisioning.installCertificateToKeystore
               (CertificateProvisioning.TYPE_CERTIFICATE, certData, "mycert", "123456",
               CertificateProvisioning.KEYSTORE_FOR_WIFI | CertificateProvisioning.KEYSTORE_FOR_VPN_AND_APPS);
      }

      if(true == result1) {
          //certificate installed to Wifi keystore successfully
      }

      if(true == result2) {
          //certificate installed to Wifi and VPN and Apps keystores successfully
      }
  } 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);
  CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();
  String filePath = "/sdcard/class3.crt";
  byte[] certData = getByteArray(filePath); //internal function to retrieve
                                            //byte array from file.
  try {
      boolean result = false;

      //installing into VPN and Applications Keystore:
      result = certProvisioning.installCertificateToKeystore
              (CertificateProvisioning.TYPE_CERTIFICATE, certData, "mycert", "123456",
              CertificateProvisioning.KEYSTORE_FOR_VPN_AND_APPS);
      }

      if(result == true) {
          //certificate successfully installed to VPN and Apps keystore of container
      }
  } catch(SecurityException e) {
      Log.w(TAG,"SecurityException: "+e);
  }
 
NOTE: This API will return false if KEYSTORE_DEFAULT is used as keystore parameter and container is in locked state.

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 11
MDM 5.0
Multiuser Environment
User Scope

public void installCertificateWithType (String type, byte[] value)

Since: API level 27

API to install certificates on the device.

Parameters
type TYPE_CERTIFICATE or TYPE_PKCS12
value The certificate data in the form byte[]
Throws
SecurityException If caller does not have required permissions
Usage

An administrator can use this API to install certificates of the type TYPE_CERTIFICATE or TYPE_PKCS12 along with data in form of byte[].

If the certificate is being installed for the first time or the credentials storage is locked, the user is asked to set a new password and certificate name. If keystore is unlocked, the user is asked to enter the certificate name and the destiny keystore (Wifi keystore or VPN and applications keystore). If the certificate is a CA, it will be duplicated to Android Default keystore.

If the administrator does not want user interaction, the recommendation is to use installCertificateToKeystore(String, byte[], String, String, int).

NOTE:

The credential storage must be in ERROR_KEYSTORE_NONE state, otherwise the user will be prompted to set a lock screen password. In order to get the credential storage state, please consider using getCredentialStorageStatus() API.

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();
  String filePath = "/data/system/class3.crt";
  byte[] bytes = getByteArray(filePath);//internal function to retrieve
                                         //byte array from file.
  try {
      certProvisioning.installCertificateWithType(CertificateProvisioning.TYPE_CERTIFICATE, bytes);
  } catch(SecurityException e) {
      Log.w(TAG,"SecurityException: "+e);
  }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.
Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope

public void installCertificatesFromSdCard ()

Since: API level 27

API to install all certificates found on the SD card of types TYPE_CERTIFICATE and TYPE_PKCS12.

Throws
SecurityException If caller does not have required permissions
Usage

If the certificate is being installed for first time or the credentials storage is locked, the user is asked to set a new password and certificate name for each certificate. If keystore is unlocked, the user is asked to enter a certificate name and the destiny keystore (Wifi keystore or VPN and applications keystore) for each certificate.

If the administrator does not want user interaction, the recommendation is to use installCertificateToKeystore(String, byte[], String, String, int)

NOTE:

The credential storage must be in ERROR_KEYSTORE_NONE state, otherwise the user will be prompted to set a lock screen password. In order to get the credential storage state, please consider using getCredentialStorageStatus() API.

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  try {
      certProvisioning.installCertificatesFromSdCard();
  } catch(SecurityException e) {
      Log.w(TAG,"SecurityException: "+e);
  }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.
Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope

public boolean removePackagesFromCertificateWhiteList (List<AppIdentity> packageList)

Since: API level 27

API to remove applications from certificate white list.

Returns
  • True if the list of applications have been successfully removed from the whitelist, false if at least one application from the given list has failed to be removed from the whitelist.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to remove a list of applications from certificate white list.
 EEnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
 CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();
 
 try {
     // In order to validate the application's signature, fill this variable with the desired
     // signature.
     String signature = null;
 
     // List of packages to be removed from certificate whitelist
     List<AppIdentity> packageList = new ArrayList<AppIdentity>();
     packageList.add(new AppIdentity("com.trusted.app", signature));
 
     boolean result = certProvisioning.removePackagesFromCertificateWhiteList(packageList);
     if(result == true) {
         // List of packages successfully removed from certificate management white list
     }
 } 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);
 CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();

 try {
     // In order to validate the application's signature, fill this variable with the desired
     // signature.
     String signature = null;
 
     // List of packages to be removed from certificate white list
     List<AppIdentity> packageList = new ArrayList<AppIdentity>();
     packageList.add(new AppIdentity("com.trusted.app", signature));
 
     boolean result = certProvisioning.removePackagesFromCertificateWhiteList(packageList);
     if(result == true) {
         // List of packages successfully removed from certificate management whitelist
     }
 } catch (SecurityException e) {
     Log.w(TAG, "SecurityException: " + e);
 }
 
Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 24
Multiuser Environment
User Scope

public boolean resetCredentialStorage ()

Since: API level 27

API to reset credential storage.

Returns
  • true if resetting credential storage was successful, else false.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to reset the credential storage under user scope. The behavior of this API is the same as the button "Clear Credentials" in Settings application.

After call this API all certificates installed at VPN and Apps Keystore and Default keystore will be deleted. If administrator call this API when installed in owner space, the certificates installed by admin or user at Wifi Keystore will be deleted as well.
  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  try {
      boolean result = certProvisioning.resetCredentialStorage();
      if(true == result) {
          //credential storage is cleared
      }
  } 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);
  CertificateProvisioning certProvisioning = kcm.getCertificateProvisioning();

  try {
      boolean result = certProvisioning.resetCredentialStorage();
      if(true == result) {
          //credential storage is cleared
      }
  } catch(SecurityException e) {
      Log.w(TAG,"SecurityException: "+e);
  }
  
NOTE: This API will return false if container is in locked state.

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 2
MDM 2.0
Multiuser Environment
User Scope

public boolean unlockCredentialStorage (String password)

Since: API level 27

API to unlock the credential storage.

Parameters
password Storage password. From Android 4.0 on, this parameter is ignored.

Returns
  • true if dialog for unlocking credential storage was successfully displayed to the user, false otherwise.
Throws
SecurityException If caller does not have required permissions
Usage
An administrator can use this API to unlock Wifi keystore and VPN and applications keystore before retrieving information about installed certificates. For Android version 4.0 onward, the user is prompted to enter a screen lock password if storage is locked.

NOTE:

After the device boots up and the user unlocks the device for the first time, credential storage remains unlocked until the next reboot.

  EnterpriseDeviceManager edm = EnterpriseDeviceManager.getInstance(context);
  CertificateProvisioning certProvisioning = edm.getCertificateProvisioning();

  try {
      boolean result = certProvisioning.unlockCredentialStorage("abc34567");
      if(true == result) {
          // dialog to set a screen lock was prompted correctly.
      }
  } catch(SecurityException e) {
      Log.w(TAG,"SecurityException: "+e);
  }

Permission
The use of this API requires the caller to have the "com.samsung.android.knox.permission.KNOX_CERT_PROVISIONING" permission which has a protection level of signature.

Since
API level 2
MDM 2.0
Multiuser Environment
Global Scope