Deprecated
in API level 33
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.
Summary
[Expand]
Inherited Methods |
From class
java.lang.Object
Object
|
clone()
|
boolean
|
equals(Object arg0)
|
void
|
finalize()
|
final
Class<?>
|
getClass()
|
int
|
hashCode()
|
final
void
|
notify()
|
final
void
|
notifyAll()
|
String
|
toString()
|
final
void
|
wait(long arg0, int arg1)
|
final
void
|
wait(long arg0)
|
final
void
|
wait()
|
|
Public Methods
public
boolean
addPackageToExemptList
(String packageName)
Deprecated
in API level 33
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
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.
|
public
boolean
deleteCCMProfile
()
Deprecated
in API level 33
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
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. |
public
boolean
deleteCSRProfile
(String templateName)
Deprecated
in API level 33
Parameters
templateName
| Name of the CSR template to be deleted. |
Returns
true
if success, else false
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);
}
|
public
boolean
deleteCertificate
(String alias)
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);
}
|
public
byte[]
generateCSRUsingTemplate
(String templateName, String alias, String challengePassword)
Deprecated
in API level 33
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);
}
|
public
CCMProfile
getCCMProfile
()
Deprecated
in API level 33
API to get the Client Certificate Manager profile set using
setCCMProfile.
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);
}
|
public
String
getCCMVersion
()
Deprecated
in API level 33
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);
}
|
public
String
getDefaultCertificateAlias
()
Deprecated
in API level 33
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);
}
|
public
boolean
installCertificate
(CertificateProfile profile, byte[] certificateBuffer, String privateKeyPassword)
Deprecated
in API level 33
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);
}
|
public
boolean
isCCMPolicyEnabledForPackage
(String packageName)
Deprecated
in API level 33
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);
}
|
public
boolean
removePackageFromExemptList
(String packageName)
Deprecated
in API level 33
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
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.
|
public
boolean
setCCMProfile
(CCMProfile profile)
Deprecated
in API level 33
Returns
true
if success, else false
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. |
public
boolean
setCSRProfile
(CSRProfile profile)
Deprecated
in API level 33
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);
}
|