Use Tree Navigation
Summary: Ctors | Methods | Inherited Methods | [Expand All]
Since: API level 12
public class

EnterpriseCertEnrollPolicy

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

Deprecated in API level 30

Class Overview

This class provides certificate enrollment related APIs which can be used to provision certificates inside or outside the containers. Using this policy user can do certificate enrollment, renewal and deletion operations with different protocols like SCEP, EST-CMC and CMP. For sample API flow please refer Certificate Enrollment Policy API flow

1. Instantiation of EnterpriseCertEnrollPolicy policy object and Binding to Certificate Enrollment Service:
The caller can get an instance of EnterpriseCertEnrollPolicy from EnterpriseKnoxManager. This will give an instance of EnterpriseCertEnrollPolicy which can be used to connect and perform certificate enrollment functionality with the Certificate Enrollment Service present in the same user space as the caller. 



  String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


  EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


  EnterpriseCertEnrollPolicy cep = ekm.getEnterpriseCertEnrollPolicy(Context, cepProtocol);


 

The caller can get an instance of EnterpriseCertEnrollPolicy from KnoxContainerManager by providing the container Id explicitly. This will give an instance of EnterpriseCertEnrollPolicy which can be used to connect and perform certificate enrollment functionality with the Certificate Enrollment Service present in the container space that is mentioned in the argument. 



  String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


  EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context); 


  KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID); // When you create container successfully, containerID will be returned via intent.


  EnterpriseCertEnrollPolicy cep = kcm.getEnterpriseCertEnrollPolicy(cepProtocol);


 

NOTE: Binding of Certificate Enrollment Service happens together with the initialization of EnterpriseCertEnrollPolicy object.

2. Registering the receiver for broadcast reception from Certificate enrollment policy:
The caller must register a receiver and listen for the following actions
CEP_ACTION_CERT_ENROLL_STATUS
CEP_ACTION_SERVICE_DISCONNECTED 



  public class EnterpriseCEPpolicyReciever extends BroadcastReceiver {     


          public void onReceive(Context context, Intent intent) {


           if(intent.getAction().equalsIgnoreCase(CEPConstants.CEP_ACTION_SERVICE_DISCONNECTED)) {


              String serviceUserId = intent.getExtra(CEPConstants.EXTRA_SERVICE_USERID);// User Id of the Certificate Enrollment Service.


              String servicePkgName = intent.getExtra(CEPConstants.EXTRA_SERVICE_PROTOCOL);// Protocol supported by Certificate Enrollment Service.


           }else if( intent.getAction().equalsIgnoreCase(CEPConstants.CEP_ACTION_CERT_ENROLL_STATUS)){


              int status = intent.getIntExtra(CEPConstants.EXTRA_ENROLL_STATUS, -1); // tells about the status of the request.


           }


          }


  }


 

3. Performing Certificate Enrollment operations: Once the instance of Certificate Enrollment policy is obtained, following operations can be done:
enrollUserCertificate(EnrollmentProfile, List, String)
renewUserCertificate(String, List)
deleteUserCertificate(String)
getCertEnrollmentStatus(String)

Since
API level 12
KNOX 2.1

Summary

Public Constructors
EnterpriseCertEnrollPolicy()
Public Methods
int deleteUserCertificate(String certificateHash)
Deprecated in API level 30
String enrollUserCertificate(EnrollmentProfile enrollmentProfile, List<String> allowedPackages, String caCertHash)
Deprecated in API level 30
int getCertEnrollmentStatus(String transactionId)
Deprecated in API level 30
String renewUserCertificate(String certificateHash, List<String> allowedPackages)
Deprecated in API level 30
[Expand]
Inherited Methods
From class java.lang.Object

Public Constructors

public EnterpriseCertEnrollPolicy ()

Since: API level 12

Public Methods

public int deleteUserCertificate (String certificateHash)

Since: API level 12

Deprecated in API level 30

API to delete user certificate.

Returns
Throws
SecurityException If caller does not have required permissions.
Usage

Locally deletes the X.509 certificate specified by the certificate hash value. This is NOT equivalent to certificate revocation. Certificate revocation in the CA server and MDM registry clean up have to be done out-of-band. 



 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 try {


     int status = ekm.getEnterpriseCertEnrollPolicy(Context, cepProtocol).deleteUserCertificate(certHash);


 } catch (SecurityException 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.


 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);


 EnterpriseCertEnrollPolicy mEnterpriseCertEnrollPolicy = kcm.getEnterpriseCertEnrollPolicy(cepProtocol);


 try {


     int status = mEnterpriseCertEnrollPolicy.deleteUserCertificate(certHash);


 } catch (SecurityException e) {


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


 }


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

Multiuser Environment
User Scope
Since
API level 12
KNOX 2.1

public String enrollUserCertificate (EnrollmentProfile enrollmentProfile, List<String> allowedPackages, String caCertHash)

Since: API level 12

Deprecated in API level 30

API to initiate enrollment with Certificate Enrollment service with the Enrollment Profile.

Parameters
enrollmentProfile Profile containing protocol specific inputs. Respective Profile has to be passed for each protocols. This can be of type SCEP, CMP or EST-CMC
allowedPackages List of applications that can access the certificate received from CA server.
For CEP_KEYSTORETYPE_CCM -- List can contain string "ALL" for all the packages, "WIFI" for wifi and Individual package names for each package.
For CEP_KEYSTORETYPE_ANDROID -- List can contain string "ALL" for all the packages, "WIFI" for wifi.
caCertHash MD5 hash/fingerprint (HEX format) of the CA certificate(DER format). This is not a mandatory parameter. Although it can be used as an added security check to verify the authenticity of CA certificate received.
NOTE: From KNOX 2.7, 'caCertHash' supports SHA-256 hash type. If sending this param, then set the corresponding hash algorithm type in hashAlgorithmType
Returns
Throws
SecurityException If caller does not have required permissions.
Usage

Issues a public key X.509 certificate by sending a self-signed CSR to the CA server for enrolling in a PKI represented by the CA server. A broadcast action CEP_ACTION_CERT_ENROLL_STATUS is sent out including the MD5 hash/fingerprint(Hex format) of the received user certificate(DER format) in success case. Client is expected to listen for this broadcast to receive the status of the enrollment request. 



 public class CertEnrolBindReciever extends BroadcastReceiver {


     public void onReceive(Context context, Intent intent) {


     if (intent.getAction().equalsIgnoreCase(CEPConstants.CEP_ACTION_CERT_ENROLL_STATUS)) {


     String certHash = intent.getStringExtra(CEPConstants.EXTRA_ENROLL_CERT_HASH);


     String transactionId  = intent.getStringExtra(CEPConstants.EXTRA_ENROLL_TRANSACTION_ID);


     String alias = intent.getStringExtra(CEPConstants.EXTRA_ENROLL_ALIAS);


     int status = intent.getIntExtra(CEPConstants.EXTRA_ENROLL_STATUS, -1);


     String refNum = intent.getStringExtra(CEPConstants.EXTRA_ENROLL_REFERENCE_NUMBER);


     //Store the values in DB against the Alias.


     }


 }


 

Below is snippet of Enrolment Profile object for SCEP Protocol, which is passed as profile information for enrolling a certificate. 



  EnrollmentProfile enrollmentProfile = new SCEPProfile();


  enrollmentProfile.scepUrl = "http://host:port/uri";


  enrollmentProfile.challengePassword = ""; // challenge password from CEP Server


  enrollmentProfile.scepProfileName = "emailprofile"; //SCEP Profile name


  enrollmentProfile.validitytimeForChallenge = 60; //validaty time for the challenge in minutes.


  enrollmentProfile.challengeLength = 16; // Challenge byte length


  enrollmentProfile.setProfileType(CEPConstants.CERT_PROFILE_TYPE_SCEP); // SCEP Protocol is used for Enrolment.


  enrollmentProfile.subjectName = "CN=admin";  // Subject name for the user certificate.


  enrollmentProfile.subjectAlterNativeName="user.name@samsung.com"; // Client Account's email address.


  enrollmentProfile.setKeystoreType(CEPConstants.CEP_KEYSTORETYPE_CCM); // Keystore Type SCEP or CCM.


  enrollmentProfile.setKeySize(2048);


  enrollmentProfile.setKeyPairAlgorithm(CEPConstants.CEP_KEYALGO_TYPE_RSA); //Only algorithm supported now.


  enrollmentProfile.setCertificateAlias("cert");


 
 


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 try {


     List  allowedPackages = new ArrayList();


     allowedPackages.add("com.android.email");


     String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


     String refNum = ekm.getEnterpriseCertEnrollPolicy(Context, cepProtocol).enrollUserCertificate(enrollmentProfile,allowedPackages, hashCACert);


 } catch (SecurityException 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.


 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);


 EnterpriseCertEnrollPolicy mEnterpriseCertEnrollPolicy = kcm.getEnterpriseCertEnrollPolicy(cepProtocol);


 try {


     List  allowedPackages = new ArrayList(); 


     allowedPackages.add("com.android.email");


  String refNum = mEnterpriseCertEnrollPolicy.enrollUserCertificate(enrollmentProfile,allowedPackages, caCertHash);


 } catch (SecurityException e) {


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


 }


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

Multiuser Environment
User Scope
Since
API level 12
KNOX 2.1

public int getCertEnrollmentStatus (String transactionId)

Since: API level 12

Deprecated in API level 30

API to get status of certificate enrollment or renewal.

Parameters
transactionId Unique transaction id returned through broadcast by enrollUserCertificate(EnrollmentProfile, List, String) or renewUserCertificate(String, List)
Returns
Throws
SecurityException If caller does not have required permissions.
Usage

The method returns the certificate enrollment status for the given Transaction Id. 



 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 try {


     int status = ekm.getEnterpriseCertEnrollPolicy(Context, cepProtocol).getCertEnrollmentStatus(transactionId);


 } catch (SecurityException 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.


 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);


 EnterpriseCertEnrollPolicy mEnterpriseCertEnrollPolicy = kcm.getEnterpriseCertEnrollPolicy(cepProtocol);


 try {


     int status = mEnterpriseCertEnrollPolicy.getCertEnrollmentStatus(transactionId);


 } catch (SecurityException e) {


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


 }


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

Multiuser Environment
User Scope
Since
API level 12
KNOX 2.1

public String renewUserCertificate (String certificateHash, List<String> allowedPackages)

Since: API level 12

Deprecated in API level 30

API to renew enrolled user certificate.

Parameters
allowedPackages List of applications that can access the certificate received from CA server.
For CEP_KEYSTORETYPE_CCM -- List can contain string "ALL" for all the packages, "WIFI" for wifi and Individual package names for each package.
For CEP_KEYSTORETYPE_ANDROID -- List can contain string "ALL" for all the packages, "WIFI" for wifi.
Returns
Throws
SecurityException If caller does not have required permissions.
Usage

Renews an X.509 certificate by sending a CSR to the CA server. The CSR is signed using the old certificate. A broadcast action CEP_ACTION_CERT_ENROLL_STATUS is sent out to notify the caller regarding the status of the request. 



 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 try {


     List  allowedPackages = new ArrayList();


     allowedPackages.add("com.android.email");


    String refNum = ekm.getEnterpriseCertEnrollPolicy(Context, cepProtocol).renewUserCertificate(certHash, allowedPackages);


 } catch (SecurityException 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.


 String cepProtocol = CEPConstants.CERT_PROFILE_TYPE_SCEP //for SCEP


 EnterpriseKnoxManager ekm = EnterpriseKnoxManager.getInstance(context);


 KnoxContainerManager kcm = ekm.getKnoxContainerManager(containerID);


 EnterpriseCertEnrollPolicy mEnterpriseCertEnrollPolicy = kcm.getEnterpriseCertEnrollPolicy(cepProtocol);


 try {


     List  allowedPackages = new ArrayList();


     allowedPackages.add("com.android.email");


     String refNum = mEnterpriseCertEnrollPolicy.renewUserCertificate(certHash, allowedPackages);


 } catch (SecurityException e) {


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


 }


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

Multiuser Environment
User Scope
Since
API level 12
KNOX 2.1