目录

@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).

This module can be used to verify the HTTPS certificate chain of an application server and log in to a website or application server through two-way HTTPS authentication.

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: 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: SystemCapability.Security.CertificateManager

Name Value Description
CM_DIGEST_NONE 0 No digest algorithm is required. If this option is used, the application 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: 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: SystemCapability.Security.CertificateManager

Name Type Read-Only Optional Description
purpose CmKeyPurpose No No Purpose of using the key.
padding CmKeyPadding No Yes Padding mode. The default value is CM_PADDING_PSS, indicating that PSS padding is used.
digest CmKeyDigest No Yes Digest algorithm. The default value is CM_DIGEST_SHA256, indicating that SHA256 is used.

CertInfo

Represents detailed information about a certificate.

System capability: 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: 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: 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: 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: 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

Model restriction: This API can be used only in the stage model.

CMHandle

Represents the handle to a signing or signature verification operation.

System capability: 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

Certificate file data.

Since: 26.0.0

System capability: SystemCapability.Security.CertificateManager

Model restriction: This API can be used only in the stage model.

Name Type Read-Only Optional Description
certData Uint8Array No No Certificate file data. If certFormat is set to PEM_DER, the maximum length of this parameter is 8 KB. If certFormat is set to P7B, the maximum length of this parameter is 300 KB.
certFormat CertFileFormat No Yes Certificate file format. The default value is PEM_DER.
certScope CertScope No Yes Scope of the CA certificate. The default value is CURRENT_USER.

CMErrorCode

Enumerates the error codes used in the certificate management APIs.

System capability: 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. In this mode, installation of the CA certificate is restricted.
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 key 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.

CertType18+

Enumerates the certificate types.

System capability: SystemCapability.Security.CertificateManager

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

CertScope18+

Enumerates the certificate scopes.

System capability: 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.

CertAlgorithm20+

Enumerates the certificate algorithms.

System capability: 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. Devices outside China do not support certificates using this algorithm.

CertStoreProperty18+

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

System capability: 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. Devices outside China do not support the SM algorithm.

AuthStorageLevel18+

Enumerates the credential storage levels.

System capability: 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.

CertificatePurpose22+

Enumerates the usage of a credential.

System capability: 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.

UkeyInfo22+

Provides USB Key certificate credential attributes.

System capability: SystemCapability.Security.CertificateManager

Name Type Read-Only Optional Description
certPurpose CertificatePurpose No Yes Credential usage. The default value is PURPOSE_DEFAULT.

CertFileFormat

Represents the certificate file format.

Since: 26.0.0

System capability: SystemCapability.Security.CertificateManager

Model restriction: This API can be used only in the stage model.

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 returns the result asynchronously through a callback.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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.

Applicable versions: 12 and later

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 ?? '';
      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: 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.

Applicable versions: 12 and later

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 ?? '';
    console.info('Succeeded in installing private certificate.');
  }).catch((error: Error) => {
    let err = error as 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.installPrivateCertificate18+

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: 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 Credential alias. Currently, the alias can contain only digits, letters, and underscores (_) and should not exceed 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 ?? '';
    console.info('Succeeded in installing private certificate.');
  }).catch((error: Error) => {
    let err = error as 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: 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. Possible causes: 1. The certificate URI is incorrect; 2. The certificate has been uninstalled. Please check the certificate URI.

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 details about a private credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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((error: Error) => {
    let err = error as 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: 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) => {
    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 specified private credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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(() => {
    console.info('Succeeded in uninstalling private certificate.');
  }).catch((error: Error) => {
    let err = error as 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.

Since: 26.0.0

Required permissions: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT

System capability: SystemCapability.Security.CertificateManager

Model restriction: This API can be used only in the stage model.

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) => {
    let uri: string = cmResult.uri ?? '';
    console.info('Succeeded in installing user trusted certificate.');
  }).catch((error: Error) => {
    let err = error as BusinessError;
    console.error(`Failed to install user trusted certificate. Code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`Failed to install user trusted certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.installUserTrustedCertificateSync18+

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

Installs a user CA certificate.

Required permissions: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT

System capability: 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 in installing user trusted certificate.');
  }
} catch (error) {
  console.error(`Failed to install user trusted certificate. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.uninstallUserTrustedCertificateSync18+

uninstallUserTrustedCertificateSync(certUri: string) : void

Uninstalls a user CA certificate.

Required permissions: ohos.permission.ACCESS_ENTERPRISE_USER_TRUSTED_CERT

System capability: 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 is the first step in the signing or signature verification process. Call the update and finish APIs in sequence to complete the operation. This API returns the result asynchronously through a callback.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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. Please call openAuthorizeDialog method to request user authorization for the certificate or credential.

Applicable versions: 12 and later

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: 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.

Applicable versions: 12 and later

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((error: Error) => {
    let err = error as 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 must be called after the init operation. This API returns the result asynchronously through a callback.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Parameters

Name Type Mandatory Description
handle Uint8Array Yes Operation handle, which needs to be obtained by calling init.
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) => {
    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: SystemCapability.Security.CertificateManager

Parameters

Name Type Mandatory Description
handle Uint8Array Yes Operation handle, which needs to be obtained by calling init.
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(() => {
    console.info('Succeeded in updating.');
  }).catch((error: Error) => {
    let err = error as 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, which is the last step in the signing process. You need to call the init and update APIs before using this API. This API returns the result asynchronously through a callback.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Parameters

Name Type Mandatory Description
handle Uint8Array Yes Operation handle, which needs to be obtained by calling init.
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 = 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, which is the last step in the signature verification process. You need to call the init and update APIs before using this API. This API returns the result asynchronously through a callback.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Parameters

Name Type Mandatory Description
handle Uint8Array Yes Operation handle, which needs to be obtained by calling init.
signature Uint8Array Yes Data to sign or verify.
callback AsyncCallback<CMResult> Yes Callback used to return the result. If the signature verification is successful, err is null and data is the outData attribute in the CMResult object. The outData attribute is null during signature verification. 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 signing or signature verification. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Parameters

Name Type Mandatory Description
handle Uint8Array Yes Operation handle, which needs to be obtained by calling init.
signature Uint8Array No Signature data used for signature verification. This parameter does not need to be passed for signing.

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 = cmResult?.outData;
      console.info('Succeeded in finishing signature.');
    } else {
      console.info('The result of signature is undefined.');
    }
  }).catch((error: Error) => {
    let err = error as 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((error: Error) => {
    let err = error as 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 method is mutually exclusive with the finish method. Only one of them can be called in a signature verification process. This API returns the result asynchronously through a callback.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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) => {
    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 method is mutually exclusive with the finish method. Only one of them can be called in a signature verification process. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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(() => {
    console.info('Succeeded in aborting.');
  }).catch((error: Error) => {
    let err = error as 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.getPublicCertificate12+

getPublicCertificate(keyUri: string): Promise<CMResult>

Obtains the details about a user public credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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((error: Error) => {
    let err = error as 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.isAuthorizedApp12+

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: 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((error: Error) => {
    let err = error as 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.getAllUserTrustedCertificates12+

getAllUserTrustedCertificates(): Promise<CMResult>

Obtains the list of all user root CA certificates in the current user and device public directories. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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((error: Error) => {
    let err = error as 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.getAllUserTrustedCertificates18+

getAllUserTrustedCertificates(scope: CertScope): Promise<CMResult>

Obtains the list of user root CA certificates based on the certificate storage path. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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((error: Error) => {
    let err = error as 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.getUserTrustedCertificate12+

getUserTrustedCertificate(certUri: string): Promise<CMResult>

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

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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((error: Error) => {
    let err = error as 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.getPrivateCertificates13+

getPrivateCertificates(): Promise<CMResult>

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

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: 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((error: Error) => {
    let err = error as 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.getCertificateStorePath18+

getCertificateStorePath(property: CertStoreProperty): string

Obtains the storage path of a certificate.

System capability: 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.

Applicable versions: 20 and later

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(`Succeeded in getting 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(`Succeeded in getting 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(`Succeeded in getting 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(`Succeeded in getting SM system CA path: ${smSystemCAPath}`);
} catch (error) {
  console.error(`Failed to get store path. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.getUkeyCertificate22+

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

Obtains details about a USB Key certificate credential. This API uses a promise to return the result.

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Device behavior differences:

Parameters

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

Return value

Type Description
Promise<CMResult> Promise used to return details about the USB Key certificate credential, that is, credentialDetailList 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.
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) => {
    if (cmResult?.credentialDetailList === undefined) {
      console.info('The result of getting detail of USB Key certificate is undefined.');
    } else {
      let list = cmResult.credentialDetailList;
      console.info('Succeeded in getting detail of USB Key certificate.');
    }
  }).catch((error: Error) => {
    let err = error as 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 a USB Key certificate credential list. This API uses a promise to return the result.

Since: 26.0.0

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Device behavior differences: This API is supported on phones, PCs/2-in-1 devices, and tablets. On other devices, it returns error code 801.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
ukeyProvider string Yes USB key provider.
ukeyInfo UkeyInfo Yes Attributes of the USB Key certificate credential.

Return value

Type Description
Promise<CMResult> Promise used to return the USB Key certificate credential list, that is, credentialDetailList 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.
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) => {
    let list: Array<certificateManager.Credential> = cmResult.credentialDetailList ?? [];
    console.info('Succeeded in getting USB Key certificate list.');
  }).catch((error: Error) => {
    let err = error as BusinessError;
    console.error(`Failed to get USB Key certificate list. Code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`Failed to get USB Key certificate list. Code: ${error.code}, message: ${error.message}`);
}

certificateManager.importUkeyCertificate

importUkeyCertificate(keyUri: string, cert: Uint8Array, ukeyInfo: UkeyInfo): Promise<void>

Imports a certificate to the USB key. This API uses a promise to return the result.

Since: 26.0.0

Required permissions: ohos.permission.ACCESS_CERT_MANAGER

System capability: SystemCapability.Security.CertificateManager

Device behavior differences: This API is supported on phones, PCs/2-in-1 devices, and tablets. On other devices, it returns error code 801.

Model restriction: This API can be used only in the stage model.

Parameters

Name Type Mandatory Description
keyUri string Yes

URI of the USB key certificate credential.

The keyUri parameter is used to identify a certificate entity. It can be obtained by calling getUkeyCertificateList. The maximum length is 256 bytes.
cert Uint8Array Yes

Certificate data to be imported. The maximum length is 10 KB.

The certificate data format complies with the SKF specifications.
ukeyInfo UkeyInfo Yes

Attributes of the USB Key certificate credential.

The value of UkeyInfo.CertificatePurpose can only be PURPOSE_SIGN, PURPOSE_ENCRYPT, or PURPOSE_DEFAULT.

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.
801 Capability not supported.
17500001 Internal error. Possible causes: 1. IPC communication failed; 2. Memory operation error; 3. File operation error. Please try again.
17500002 The certificate identified by keyUri 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';

/* keyUri and cert must be assigned based on the service. The data in this example is for reference only. */
let keyUri: string = 'test'; /* URI of the USB key certificate, which can be obtained through the getUkeyCertificateList API. */
let certData: Uint8Array = new Uint8Array([
  0x30, 0x82, 0x0b, 0xc1, 0x02, 0x01
]);
let ukeyInfo: certificateManager.UkeyInfo = {
  certPurpose: certificateManager.CertificatePurpose.PURPOSE_SIGN
};
try {
  certificateManager.importUkeyCertificate(keyUri, certData, ukeyInfo).then(() => {
    console.info('Succeeded in importing USB Key certificate.');
  }).catch((error: Error) => {
    let err = error as BusinessError;
    console.error(`Failed to import USB Key certificate. Code: ${err.code}, message: ${err.message}`);
  });
} catch (error) {
  console.error(`Failed to import USB Key certificate. Code: ${error.code}, message: ${error.message}`);
}