@ohos.security.certManager (Certificate Management)

The certManager module provides system-level certificate management capabilities to implement management and secure use of certificates throughout their lifecycle (installation, storage, use, and destruction).

NOTE

The initial APIs of this module are supported since API version 11. Newly added APIs will be marked with a superscript to indicate their earliest API version.

Modules to Import

import { certificateManager } from '@kit.DeviceCertificateKit';

CmKeyPurpose

Enumerates the purposes of using the key.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
CM_KEY_PURPOSE_SIGN	4	Signs data.
CM_KEY_PURPOSE_VERIFY	8	Verifies a signature.

CmKeyDigest

Enumerates the digest algorithms that can be used for signing and signature verification.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
CM_DIGEST_NONE	0	No digest algorithm is required. If this option is used, the service needs to pass in the data with the digest generated for signing or signature verification.
CM_DIGEST_MD5	1	MD5.
CM_DIGEST_SHA1	2	SHA-1.
CM_DIGEST_SHA224	3	SHA-224.
CM_DIGEST_SHA256	4	SHA-256.
CM_DIGEST_SHA384	5	SHA-384.
CM_DIGEST_SHA512	6	SHA-512.
CM_DIGEST_SM318+	7	SM3.

CmKeyPadding

Enumerates the padding modes that can be used for signing and signature verification.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
CM_PADDING_NONE	0	No padding.
CM_PADDING_PSS	1	PSS.
CM_PADDING_PKCS1_V1_5	2	PKCS1-V1_5.

CMSignatureSpec

Represents a set of parameters used for signing or signature verification, including the key usage purpose, padding mode, and digest algorithm.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
purpose	CmKeyPurpose	No	No	Purpose of using the key.
padding	CmKeyPadding	No	Yes	Padding mode.
digest	CmKeyDigest	No	Yes	Digest algorithm.

CertInfo

Represents detailed information about a certificate.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
uri	string	No	No	Unique identifier of a certificate. The value contains up to 256 bytes.
certAlias	string	No	No	Alias of a certificate. The value contains up to 128 bytes.
state	boolean	No	No	Certificate state. The value true indicates that the certificate is enabled, and false means the opposite.
issuerName	string	No	No	Name of the certificate issuer. The value contains up to 256 bytes.
subjectName	string	No	No	Name of the certificate subject. The value contains up to 1024 bytes.
serial	string	No	No	Serial number of a certificate. The value contains up to 64 bytes. The value is a hexadecimal string, for example, 62C2CB4DE8405E96.
notBefore	string	No	No	Start date of a certificate. The value contains up to 32 bytes.
notAfter	string	No	No	Expiry date of a certificate. The value contains up to 32 bytes.
fingerprintSha256	string	No	No	Fingerprint of a certificate. The value contains up to 128 bytes.
cert	Uint8Array	No	No	Binary data of a certificate. The value contains up to 8196 bytes.

CertAbstract

Represents brief information about a certificate.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
uri	string	No	No	Unique identifier of a certificate. The value contains up to 256 bytes.
certAlias	string	No	No	Alias of a certificate. The value contains up to 128 bytes.
state	boolean	No	No	Certificate state. The value true indicates that the certificate is enabled, and false means the opposite.
subjectName	string	No	No	Name of the certificate subject. The value contains up to 1024 bytes.

Credential

Represents detailed information about a credential.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
type	string	No	No	Type of a credential. The value contains up to 8 bytes.
alias	string	No	No	Alias of a credential. The value contains up to 128 bytes.
keyUri	string	No	No	Unique identifier of a credential. The value contains up to 256 bytes.
certNum	number	No	No	Number of certificates contained in the credential.
keyNum	number	No	No	Number of keys contained in the credential.
credentialData	Uint8Array	No	No	Binary data of a credential. The value contains up to 20480 bytes.
certPurpose22+	CertificatePurpose	No	Yes	Credential usage. The default value is CertificatePurpose.PURPOSE_DEFAULT.

CredentialAbstract

Represents brief information about a credential.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
type	string	No	No	Type of a credential. The value contains up to 8 bytes.
alias	string	No	No	Alias of a credential. The value contains up to 128 bytes.
keyUri	string	No	No	Unique identifier of a credential. The value contains up to 256 bytes.

CMResult

Represents the result returned.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
certList	Array<CertAbstract>	No	Yes	Brief certificate information.
certInfo	CertInfo	No	Yes	Detailed certificate information.
credentialList	Array<CredentialAbstract>	No	Yes	Brief credential information.
credential	Credential	No	Yes	Detailed credential information.
appUidList	Array<string>	No	Yes	List of authorized applications.
uri	string	No	Yes	Unique identifier of a certificate or credential. The value contains up to 256 bytes.
outData	Uint8Array	No	Yes	Signature generated.
credentialDetailList22+	Array<Credential>	No	Yes	Represents detailed information about a credential.
uriList	Array<string>	No	Yes	Certificate URI list. Since: 26.0.0

CMHandle

Represents the handle to a signing or signature verification operation.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
handle	Uint8Array	No	No	Handle of the initialization for signing and signature verification. The value contains up to 8 bytes.

CertBlob

Represents the certificate data in binary format.

System capability: System SystemCapability.Security.CertificateManager

Since: 26.0.0

Name	Type	Read-Only	Optional	Description
certData	Uint8Array	No	No	Certificate file data.
certFormat	CertFileFormat	No	Yes	Certificate file format.
certScope	CertScope	No	Yes	Scope of the CA certificate.

CMErrorCode

Enumerates the error codes used in the certificate management APIs.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
CM_ERROR_NO_PERMISSION	201	The application does not have the permission to call the API.
CM_ERROR_INVALID_PARAMS	401	Invalid input parameter is found.
CM_ERROR_GENERIC	17500001	An internal error occurs when the interface is called.
CM_ERROR_NO_FOUND	17500002	The certificate or credential does not exist.
CM_ERROR_INCORRECT_FORMAT	17500003	The certificate or credential is in invalid format.
CM_ERROR_MAX_CERT_COUNT_REACHED12+	17500004	The number of certificates or credentials has reached the limit.
CM_ERROR_NO_AUTHORIZATION12+	17500005	The application has not obtained user authorization.
CM_ERROR_DEVICE_ENTER_ADVSECMODE18+	17500007	The device enters the advanced security mode.
CM_ERROR_STORE_PATH_NOT_SUPPORTED20+	17500009	The device does not support the specified certificate storage path.
CM_ERROR_ACCESS_UKEY_SERVICE_FAILED22+	17500010	The USB credential service fails to be accessed.
CM_ERROR_PARAMETER_VALIDATION_FAILED22+	17500011	The input parameter validation fails. For example, the parameter format is incorrect or the parameter range is invalid.

CertType¹⁸⁺

Enumerates the certificate types.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
CA_CERT_SYSTEM	0	System CA certificate.
CA_CERT_USER	1	User CA certificate.

CertScope¹⁸⁺

Enumerates the certificate scopes.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
CURRENT_USER	1	The certificate is accessible only to the current user.
GLOBAL_USER	2	The certificate is accessible to all users.

CertAlgorithm²⁰⁺

Enumerates the certificate algorithms.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
INTERNATIONAL	1	International cryptographic algorithm, such as RSA and NIST ECC.
SM	2	Commercial cryptographic algorithm, such as SM2 and SM4.

CertStoreProperty¹⁸⁺

Represents the storage information about a certificate, including the certificate type and location.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
certType	CertType	No	No	Type of the certificate.
certScope	CertScope	No	Yes	Scope of the certificate. This parameter is mandatory when certType is CA_CERT_USER.
certAlg20+	CertAlgorithm	No	Yes	Certificate algorithm. This parameter is valid only when certType is set to CA_CERT_SYSTEM. The default value is INTERNATIONAL.

AuthStorageLevel¹⁸⁺

Enumerates the credential storage levels.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
EL1	1	The credential can be accessed after the device is started.
EL2	2	The credential can be accessed after the device is unlocked for the first time.
EL4	4	The credential can be accessed after the device is unlocked.

CertificatePurpose²²⁺

Enumerates the usage of a credential.

System capability: System SystemCapability.Security.CertificateManager

Name	Value	Description
PURPOSE_DEFAULT	0	Default usage, which is used for credential signing.
PURPOSE_ALL	1	Query of all credentials.
PURPOSE_SIGN	2	Credential signing.
PURPOSE_ENCRYPT	3	Credential encryption.

UkeyInfo²²⁺

Provides USB credential attributes.

System capability: System SystemCapability.Security.CertificateManager

Name	Type	Read-Only	Optional	Description
certPurpose	CertificatePurpose	No	Yes	Credential usage.

CertFileFormat

Represents the certificate file format.

System capability: System SystemCapability.Security.CertificateManager

Since: 26.0.0

Name	Value	Description
PEM_DER	0	The certificate file format is PEM or DER.
P7B	1	The certificate file format is P7B.

certificateManager.installPrivateCertificate

installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, callback: AsyncCallback<CMResult>): void

Installs a private credential. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keystore	Uint8Array	Yes	Keystore file with a key pair and certificate. The value contains up to 20480 bytes.
keystorePwd	string	Yes	Password of the keystore file. The password cannot exceed 32 bytes.
certAlias	string	Yes	Credential alias. Currently, the alias can contain only digits, letters, and underscores (_) and should not exceed 32 bytes.
callback	AsyncCallback<CMResult>	Yes	Callback used to return the result. If the operation is successful, err is null and data is uri in the CMResult object. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500003	The keystore is in an invalid format or the keystore password is incorrect.
17500004	The number of certificates or credentials reaches the maximum allowed.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

/* The credential data to be installed must be assigned by the service. The data in this example is not the real credential data. */
let keystore: Uint8Array = new Uint8Array([
  0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01,
]);
let keystorePwd: string = "123456";
try {
  certificateManager.installPrivateCertificate(keystore, keystorePwd, "test", (err, cmResult) => {
    if (err != null) {
      console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`);
    } else {
      let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri;
      console.info('Succeeded in installing private certificate.');
    }
  });
} catch (error) {
  console.error(`Failed to install private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.installPrivateCertificate

installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string): Promise<CMResult>

Installs a private credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keystore	Uint8Array	Yes	Keystore file with a key pair and certificate. The value contains up to 20480 bytes.
keystorePwd	string	Yes	Password of the keystore file. The password cannot exceed 32 bytes.
certAlias	string	Yes	Credential alias. Currently, the alias can contain only digits, letters, and underscores (_) and should not exceed 32 bytes.

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, uri in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500003	The keystore is in an invalid format or the keystore password is incorrect.
17500004	The number of certificates or credentials reaches the maximum allowed.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

/* The credential data to be installed must be assigned by the service. The data in this example is not the real credential data. */
let keystore: Uint8Array = new Uint8Array([
  0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01,
]);
let keystorePwd: string = "123456";
try {
  certificateManager.installPrivateCertificate(keystore, keystorePwd, 'test').then((cmResult) => {
    let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri;
    console.info('Succeeded in installing private certificate.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to install private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.installPrivateCertificate¹⁸⁺

installPrivateCertificate(keystore: Uint8Array, keystorePwd: string, certAlias: string, level: AuthStorageLevel): Promise<CMResult>

Installs a private credential and specifies its storage level. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keystore	Uint8Array	Yes	Keystore file with a key pair and certificate. The value contains up to 20480 bytes.
keystorePwd	string	Yes	Password of the keystore file. The value contains up to 32 bytes.
certAlias	string	Yes	Alias of the credential entered by the user. Only digits, letters, and underscores (_) are supported. The value should contain up to 32 bytes.
level	AuthStorageLevel	Yes	Credential storage level.

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, uri in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500003	The keystore is in an invalid format or the keystore password is incorrect.
17500004	The number of certificates or credentials reaches the maximum allowed.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

/* The data of the credential to be installed must be assigned based on the service. The data in this example is not the real credential data. */
let keystore: Uint8Array = new Uint8Array([
  0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01,
]);
let keystorePwd: string = "123456";
try {
  /* The credential can be used after the device is unlocked for the first time. */
  let level = certificateManager.AuthStorageLevel.EL2;
  certificateManager.installPrivateCertificate(keystore, keystorePwd, 'test', level).then((cmResult) => {
    let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri;
    console.info('Succeeded in installing private certificate.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to install private certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to install private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getPrivateCertificate

getPrivateCertificate(keyUri: string, callback: AsyncCallback<CMResult>): void

Obtains detailed information about a private credential. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of the credential to be obtained. The value contains up to 256 bytes.
callback	AsyncCallback<CMResult>	Yes	Callback used to return the result. If the operation is successful, err is null and data is credential in the CMResult object. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to obtain the private credential details, which is not elaborated here. */
try {
  certificateManager.getPrivateCertificate(uri, (err, cmResult) => {
    if (err != null) {
      console.error(`Failed to get private certificate. Code: ${err.code}, message: ${err.message}`);
    } else {
      if (cmResult?.credential == undefined) {
        console.info('The result of getting private certificate is undefined.');
      } else {
        let list = cmResult.credential;
        console.info('Succeeded in getting private certificate.');
      }
    }
  });
} catch (error) {
  console.error(`Failed to get private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getPrivateCertificate

getPrivateCertificate(keyUri: string): Promise<CMResult>

Obtains detailed information about a private credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of the credential to be obtained. The value contains up to 256 bytes.

Return value

Type	Description
Promise<CMResult>	Promise used to return the private credential details obtained, that is, credential in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to obtain the private credential details, which is not elaborated here. */
try {
  certificateManager.getPrivateCertificate(uri).then((cmResult) => {
    if (cmResult?.credential == undefined) {
      console.info('The result of getting private certificate is undefined.');
    } else {
      let list = cmResult.credential;
      console.info('Succeeded in getting private certificate.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get private certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.uninstallPrivateCertificate

uninstallPrivateCertificate(keyUri: string, callback: AsyncCallback<void>): void

Uninstalls a private credential. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of the credential to be uninstalled. The value contains up to 256 bytes.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is null. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to delete the private credential, which is not elaborated here. */
try {
  certificateManager.uninstallPrivateCertificate(uri, (err, result) => {
    if (err != null) {
      console.error(`Failed to uninstall private certificate. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in uninstalling private certificate.');
    }
  });
} catch (error) {
  console.error(`Failed to uninstall private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.uninstallPrivateCertificate

uninstallPrivateCertificate(keyUri: string): Promise<void>

Uninstalls a private credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of the credential to be uninstalled. The value contains up to 256 bytes.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to delete the private credential, which is not elaborated here. */
try {
  certificateManager.uninstallPrivateCertificate(uri).then((cmResult) => {
    console.info('Succeeded in uninstalling private certificate.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to uninstall private certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to uninstall private certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.installUserTrustedCertificate

installUserTrustedCertificate(certificate: CertBlob) : Promise<CMResult>

Installs a user CA certificate. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT or ohos.permission.ACCESS_USER_TRUSTED_CERT

System capability: System SystemCapability.Security.CertificateManager

Since: 26.0.0

Parameters

Name	Type	Mandatory	Description
certificate	CertBlob	Yes	Certificate information.

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, uri in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter verification failed. Possible causes: the certData parameter is empty or exceeds the maximum length.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500003	Indicates that the certificate is in an invalid format.
17500004	Indicates that the number of certificates reaches the maximum allowed.
17500007	Indicates that the device enters advanced security mode. In this mode, the user CA certificate cannot be installed.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */
let certData: Uint8Array = new Uint8Array([
    0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01,
]);
try {
    let certBlob: certificateManager.CertBlob = {
        certData: certData,
        certFormat: certificateManager.CertFileFormat.PEM_DER,
        certScope: certificateManager.CertScope.CURRENT_USER
    };
    certificateManager.installUserTrustedCertificate(certBlob).then((cmResult: certificateManager.CMResult) => {
        let uri: string = (cmResult?.uri == undefined) ? '' : cmResult.uri;
        console.info('Succeeded in installing user trusted certificate.');
    }).catch((err: BusinessError) => {
        console.error(`Failed to install user trusted certificate. Code: ${err.code}, message: ${err.message}`);
    })
} catch (error: BusinessError) {
    console.error(`Failed to install user trusted certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.installUserTrustedCertificateSync¹⁸⁺

installUserTrustedCertificateSync(cert: Uint8Array, certScope: CertScope) : CMResult

Installs a user CA certificate.

Required permissions: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT or ohos.permission.ACCESS_USER_TRUSTED_CERT

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
cert	Uint8Array	Yes	CA certificate data. The value contains up to 8196 bytes.
certScope	CertScope	Yes	Scope of the CA certificate.

Return value

Type	Description
CMResult	CA certificate installation result. The uri property in CMResult is returned if the certificate is installed successfully.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500003	Indicates that the certificate is in an invalid format.
17500004	Indicates that the number of certificates reaches the maximum allowed.
17500007	Indicates that the device enters advanced security mode. In this mode, the user CA certificate cannot be installed.

Example

import {certificateManager} from '@kit.DeviceCertificateKit';

/* The CA certificate data must be assigned by the service. In this example, the data is not CA certificate data. */
let certData: Uint8Array = new Uint8Array([
    0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01,
]);
try {
    let result: certificateManager.CMResult = certificateManager.installUserTrustedCertificateSync(certData, certificateManager.CertScope.CURRENT_USER);
    let certUri = result.uri;
    if (certUri === undefined) {
        console.error("The result of install user trusted certificate is undefined.");
    } else {
        console.info("Succeeded to install user trusted certificate.");
    }
} catch (error) {
    console.error(`Failed to install user trusted certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.uninstallUserTrustedCertificateSync¹⁸⁺

uninstallUserTrustedCertificateSync(certUri: string) : void

Uninstalls a user CA certificate.

Required permissions: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT or ohos.permission.ACCESS_USER_TRUSTED_CERT

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
certUri	string	Yes	Unique identifier of the certificate to be uninstalled. The value contains up to 256 bytes.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	Indicates that the certificate does not exist.

Example

import {certificateManager} from '@kit.DeviceCertificateKit';

let certUri: string = "test"; /* The service needs to use the certificate identifier to delete the certificate, which is not elaborated here. */
try {
    certificateManager.uninstallUserTrustedCertificateSync(certUri);
} catch (error) {
    console.error(`Failed to uninstall user trusted certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.init

init(authUri: string, spec: CMSignatureSpec, callback: AsyncCallback<CMHandle>): void

Initializes the signing or signature verification operation using the specified credential. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
authUri	string	Yes	Unique identifier of the credential to be used. The value contains up to 256 bytes.
spec	CMSignatureSpec	Yes	Parameters for the signing or signature verification operation.
callback	AsyncCallback<CMHandle>	Yes	Callback used to return the result. If the operation is successful, err is null and data is the obtained CMHandle. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.
17500005	The application is not authorized by the user.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to initialize signing and signature verification, which is not elaborated here. */
const req: certificateManager.CMSignatureSpec = {
  purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_SIGN,
  padding: certificateManager.CmKeyPadding.CM_PADDING_PSS,
  digest: certificateManager.CmKeyDigest.CM_DIGEST_SHA256
}
try {
  certificateManager.init(uri, req, (err, cmHandle) => {
    if (err != null) {
      console.error(`Failed to init. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in initiating.');
    }
  })
} catch (error) {
  console.error(`Failed to init. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.init

init(authUri: string, spec: CMSignatureSpec): Promise<CMHandle>

Initializes the signing or signature verification operation using the specified credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
authUri	string	Yes	Unique identifier of the credential to be used. The value contains up to 256 bytes.
spec	CMSignatureSpec	Yes	Parameters for the signing or signature verification operation.

Return value

Type	Description
Promise<CMHandle>	Promise used to return the operation result, that is, the CMHandle object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.
17500005	The application is not authorized by the user.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let uri: string = 'test'; /* The service needs to use the unique identifier of the credential to initialize signing and signature verification, which is not elaborated here. */
const req: certificateManager.CMSignatureSpec = {
  purpose: certificateManager.CmKeyPurpose.CM_KEY_PURPOSE_VERIFY,
  padding: certificateManager.CmKeyPadding.CM_PADDING_PSS,
  digest: certificateManager.CmKeyDigest.CM_DIGEST_MD5
}
try {
  certificateManager.init(uri, req).then((handle) => {
    console.info('Succeeded in initiating.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to init. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to init. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.update

update(handle: Uint8Array, data: Uint8Array, callback: AsyncCallback<void>): void

Updates the data for the signing or signature verification operation. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.
data	Uint8Array	Yes	Data to be signed or verified.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is null. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
let srcData: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  certificateManager.update(cmHandle, srcData, (err, result) => {
    if (err != null) {
      console.error(`Failed to update. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in updating.');
    }
  });
} catch (error) {
  console.error(`Failed to update. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.update

update(handle: Uint8Array, data: Uint8Array): Promise<void>

Updates the data for the signing or signature verification operation. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.
data	Uint8Array	Yes	Data to be signed or verified.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
let srcData: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  certificateManager.update(cmHandle, srcData).then((result) => {
    console.info('Succeeded in updating.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to update. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to update. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.finish

finish(handle: Uint8Array, callback: AsyncCallback<CMResult>): void

Finishes the signing operation. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.
callback	AsyncCallback<CMResult>	Yes	Callback used to return the result. If the operation is successful, err is null and data is the signature, that is, outData of the CMResult object. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  certificateManager.finish(cmHandle, (err, cmResult) => {
    if (err != null) {
      console.error(`Failed to finish. Code: ${err.code}, message: ${err.message}`);
    } else {
      if (cmResult?.outData != undefined) {
        let signRes: Uint8Array = cmResult.outData;
        console.info('Succeeded in finishing.');
      } else {
        console.info('The result of finishing is undefined.');
      }
    }
  });
} catch(error) {
  console.error(`Failed to finish. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.finish

finish(handle: Uint8Array, signature: Uint8Array, callback: AsyncCallback<CMResult>): void

Finishes the signature verification operation. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.
signature	Uint8Array	Yes	Data to sign or verify.
callback	AsyncCallback<CMResult>	Yes	Callback used to return the result. If the operation is successful, err is null. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
let signRes: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  certificateManager.finish(cmHandle, signRes, (err, cmResult) => {
    if (err != null) {
      console.error(`Failed to finish. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in finishing.');
    }
  });
} catch(error) {
  console.error(`Failed to finish. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.finish

finish(handle: Uint8Array, signature?: Uint8Array): Promise<CMResult>

Finishes the signing or signature verification operation. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.
signature	Uint8Array	No	Signature data used for signature verification. This parameter needs to be specified only for signature verification.

Return value

Type	Description
Promise<CMResult>	Promise used to return the signature of a signing operation, that is, outData in the CMResult object. For a signature verification operation, the promise returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  /* Finish the signing operation. */
  certificateManager.finish(cmHandle).then((cmResult) => {
    if (cmResult?.outData != undefined) {
      let signRes1: Uint8Array = cmResult.outData;
      console.info('Succeeded in finishing signature.');
    } else {
      console.info('The result of signature is undefined.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to finish signature. Code: ${err.code}, message: ${err.message}`);
  })

  /* Signature generated. */
  let signRes: Uint8Array = new Uint8Array([
    0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
  ]);
  /* Finish the signature verification operation. */
  certificateManager.finish(cmHandle, signRes).then((cmResult) => {
    console.info('Succeeded in finishing verification.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to finish verification. Code: ${err.code}, message: ${err.message}`);
  })
} catch(error) {
  console.error(`Failed to finish. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.abort

abort(handle: Uint8Array, callback: AsyncCallback<void>): void

Aborts the signing or signature verification operation. This API uses an asynchronous callback to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.
callback	AsyncCallback<void>	Yes	Callback used to return the result. If the operation is successful, err is null. Otherwise, err is an error object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  certificateManager.abort(cmHandle, (err, cmResult) => {
    if (err != null) {
      console.error(`Failed to abort. Code: ${err.code}, message: ${err.message}`);
    } else {
      console.info('Succeeded in aborting.');
    }
  });
} catch(error) {
  console.error(`Failed to abort. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.abort

abort(handle: Uint8Array): Promise<void>

Aborts the signing or signature verification operation. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
handle	Uint8Array	Yes	Handle of initialization. The value contains up to 8 bytes.

Return value

Type	Description
Promise<void>	Promise that returns no value.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

/* cmHandle is the value returned by init(). The value here is only an example. */
let cmHandle: Uint8Array = new Uint8Array([
  0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08
]);
try {
  certificateManager.abort(cmHandle).then((result) => {
    console.info('Succeeded in aborting.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to abort. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to abort. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getPublicCertificate¹²⁺

getPublicCertificate(keyUri: string): Promise<CMResult>

Obtains detailed information about a public credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of a user's public credential. The value contains up to 256 bytes.

Return value

Type	Description
Promise<CMResult>	Promise used to return the detailed information about the user's public credential obtained, that is, credential in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.
17500005	The application is not authorized by the user.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let uri: string = 'test'; /* The user needs to use the unique identifier of the credential to obtain the public credential details, which is not elaborated here. */
try {
  certificateManager.getPublicCertificate(uri).then((cmResult) => {
    if (cmResult?.credential == undefined) {
      console.info('The result of getting public certificate is undefined.');
    } else {
      let cred = cmResult.credential;
      console.info('Succeeded in getting Public certificate.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get Public certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get Public certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.isAuthorizedApp¹²⁺

isAuthorizedApp(keyUri: string): Promise<boolean>

Checks whether this application is authorized by the specified user credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of the credential authorized by the user to the application. The value contains up to 256 bytes.

Return value

Type	Description
Promise<boolean>	Promise used to return whether the application is authorized. The value true means authorized; the value false means the opposite.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let uri: string = 'test'; /* Unique identifier of the credential. The process for authorizing the credential to the application is omitted here. */
try {
  certificateManager.isAuthorizedApp(uri).then((res) => {
    if (res) {
      console.info('The application is authorized by the user.');
    } else {
      console.info('The application is not authorized by the user.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to check if the application is authorized. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to check if the application is authorized. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getAllUserTrustedCertificates¹²⁺

getAllUserTrustedCertificates(): Promise<CMResult>

Obtains all user trusted root CA certificates of the device. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, certList in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  certificateManager.getAllUserTrustedCertificates().then((cmResult) => {
    if (cmResult === undefined) { // If the number of root CA certificates is 0, the returned cmResult is undefined.
      console.info('The count of the user trusted certificates is 0.');
    } else if (cmResult.certList == undefined) {
      console.info('The result of getting all user trusted certificates is undefined.');
    } else {
      let list = cmResult.certList;
      console.info('Succeeded in getting all user trusted certificates.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get all user trusted certificates. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get all user trusted certificates. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getAllUserTrustedCertificates¹⁸⁺

getAllUserTrustedCertificates(scope: CertScope): Promise<CMResult>

Obtains the user root CA certificates based on the certificate scope. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
scope	CertScope	Yes	Scope of the certificates to obtain.

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, certList in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  /* Obtain the user root CA certificates of the current user. To obtain the user root CA certificates accessible to all users, pass in GLOBAL_USER. */
  let scope: certificateManager.CertScope = certificateManager.CertScope.CURRENT_USER;
  certificateManager.getAllUserTrustedCertificates(scope).then((cmResult) => {
    if (cmResult === undefined) { // If the number of root CA certificates is 0, the returned cmResult is undefined.
      console.info('The count of the user trusted certificates is 0.');
    } else if (cmResult.certList == undefined) {
      console.info('The result of getting current user trusted certificates is undefined.');
    } else {
      let list = cmResult.certList;
      console.info('Succeeded in getting current user trusted certificates.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get current user trusted certificates. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get current user trusted certificates. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getUserTrustedCertificate¹²⁺

getUserTrustedCertificate(certUri: string): Promise<CMResult>

Obtains the detailed information about a user root CA certificate. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
certUri	string	Yes	Unique identifier of a user's root CA certificate. The value contains up to 256 bytes.

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, certInfo in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	The certificate does not exist.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let certUri: string = 'testUserCert'; /* The user needs to use the unique identifier of the CA certificate to obtain the user root CA certificate details, which is not elaborated here. */
try {
  certificateManager.getUserTrustedCertificate(certUri).then((cmResult) => {
    if (cmResult?.certInfo == undefined) {
      console.info('The result of getting user trusted certificate is undefined.');
    } else {
      let cert = cmResult.certInfo;
      console.info('Succeeded in getting user trusted certificate.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get user trusted certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get user trusted certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getPrivateCertificates¹³⁺

getPrivateCertificates(): Promise<CMResult>

Obtains the credentials for installing the application. This API uses a promise to return the result asynchronously.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Return value

Type	Description
Promise<CMResult>	Promise used to return credentials obtained, which is credentialList in CMResult.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

try {
  certificateManager.getPrivateCertificates().then((cmResult) => {
    if (cmResult === undefined) { // If the number of certificate credentials is 0, the returned cmResult is undefined.
      console.info('The count of the private certificates is 0.');
    } else if (cmResult.credentialList == undefined) {
      console.info('The result of getting all private certificates installed by the application is undefined.');
    } else {
      let list = cmResult.credentialList;
      console.info('Succeeded in getting all private certificates installed by the application.');
    }
  }).catch((err: BusinessError) => {
    console.error(`Failed to get all private certificates installed by the application. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get all private certificates installed by the application. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getCertificateStorePath¹⁸⁺

getCertificateStorePath(property: CertStoreProperty): string;

Obtains the certificate storage path.

System capability: System SystemCapability.Security.CertificateManager

Parameters

Name	Type	Mandatory	Description
property	CertStoreProperty	Yes	Storage information about the target certificate.

Return value

Type	Description
string	Certificate storage path.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
401	Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed. For example, CertStoreProperty.certType is set to CA_CERT_USER, but CertStoreProperty.certScope is not specified.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500009	The device does not support the specified certificate storage path, For example, the device outside China does not support the certificate that uses SM algorithm.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';

try {
  /* Obtain the storage path of the system CA certificates. */
  let property1: certificateManager.CertStoreProperty = {
    certType: certificateManager.CertType.CA_CERT_SYSTEM,
  }
  let systemCAPath = certificateManager.getCertificateStorePath(property1);
  console.info(`Success to get system ca path: ${systemCAPath}`);

  /* Obtain the storage path of the CA certificates for the current user. */
  let property2: certificateManager.CertStoreProperty = {
    certType: certificateManager.CertType.CA_CERT_USER,
    certScope: certificateManager.CertScope.CURRENT_USER,
  }
  let userCACurrentPath = certificateManager.getCertificateStorePath(property2);
  console.info(`Success to get current user's user ca path: ${userCACurrentPath}`);

  /* Obtain the storage path of the CA certificates for all users. */
  let property3: certificateManager.CertStoreProperty = {
    certType: certificateManager.CertType.CA_CERT_USER,
    certScope: certificateManager.CertScope.GLOBAL_USER,
  }
  let globalCACurrentPath = certificateManager.getCertificateStorePath(property3);
  console.info(`Success to get global user's user ca path: ${globalCACurrentPath}`);

  /* Obtain the storage path of the system CA certificates of the SM algorithm. */
  let property4: certificateManager.CertStoreProperty = {
    certType: certificateManager.CertType.CA_CERT_SYSTEM,
    certAlg: certificateManager.CertAlgorithm.SM,
  }
  let smSystemCAPath = certificateManager.getCertificateStorePath(property4);
  console.info(`Success to get SM system ca path: ${smSystemCAPath}`);
} catch (error) {
  console.error(`Failed to get store path. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getUkeyCertificate²²⁺

getUkeyCertificate(keyUri: string, ukeyInfo: UkeyInfo): Promise<CMResult>

Obtains the details of a USB credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Device behavior differences: This API can be properly called on PCs. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
keyUri	string	Yes	Unique identifier of a USB credential. The value contains up to 256 bytes.
ukeyInfo	UkeyInfo	Yes	Attributes of a USB credential.

Return value

Type	Description
Promise<CMResult>	Promise used to return the obtained USB credential details.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed.
801	Capability not supported. The application does not have the permission required to call the API.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002	Indicates that the certificate does not exist.
17500010	Indicates that access USB key service failed.
17500011	Indicates that the input parameters validation failed. For example, the parameter format is incorrect or the value range is invalid.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let keyUri: string = 'test'; /* Unique identifier of the USB credential. The value is omitted here. */
let ukeyInfo: certificateManager.UkeyInfo = { /* USB credential attributes. The value is omitted here. */
    certPurpose: certificateManager.CertificatePurpose.PURPOSE_DEFAULT,
  }
try {
  certificateManager.getUkeyCertificate(keyUri, ukeyInfo).then((cmResult) => {
      let list = cmResult.credentialDetailList;
      console.info('Succeeded in getting detail of USB key certificate.');
  }).catch((err: BusinessError) => {
    console.error(`Failed to get detail of USB key certificate. Code: ${err.code}, message: ${err.message}`);
  })
} catch (error) {
  console.error(`Failed to get detail of USB key certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getUkeyCertificateList

getUkeyCertificateList(ukeyProvider: string, ukeyInfo: UkeyInfo): Promise<CMResult>

Obtains the list of USB credential certificates. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: System SystemCapability.Security.CertificateManager

Since: 26.0.0

Device behavior differences: This API can be properly called on PCs. If it is called on other device types, error code 801 is returned.

Parameters

Name	Type	Mandatory	Description
ukeyProvider	string	Yes	USB credential provider.
ukeyInfo	UkeyInfo	Yes	Attributes of a USB credential.

Return value

Type	Description
Promise<CMResult>	Promise used to return the operation result, that is, credentialDetailList in the CMResult object.

Error codes

For details about the error codes, see Universal Error Codes and Certificate Management Error Codes.

ID	Error Message
201	Permission verification failed. The application does not have the permission required to call the API.
801	Capability not supported.
17500001	Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error.
17500010	Indicates that access USB key service failed.
17500011	Parameter verification failed. Possible causes: the ukeyInfo parameter is invalid. For example, the parameter format is incorrect or the value range is invalid.

Example

import { certificateManager } from '@kit.DeviceCertificateKit';
import { BusinessError } from '@kit.BasicServicesKit';

let ukeyProvider: string = 'testProvider'; /* USB credential provider, which is omitted here. */
let ukeyInfo: certificateManager.UkeyInfo = { /* USB credential attributes. The value is omitted here. */
    certPurpose: certificateManager.CertificatePurpose.PURPOSE_DEFAULT,
}
try {
    certificateManager.getUkeyCertificateList(ukeyProvider, ukeyInfo).then((cmResult: certificateManager.CMResult) => {
        let list: Array<certificateManager.Credential> = cmResult.credentialDetailList ?? [];
        console.info('Succeeded in getting USB key certificate list.');
    }).catch((err: BusinessError) => {
        console.error(`Failed to get USB key certificate list. Code: ${err.code}, message: ${err.message}`);
    })
} catch (error: BusinessError) {
    console.error(`Failed to get USB key certificate list. Code: ${error.code}, message: ${error.message}`);
}