目录

TrustedAppService

This module provides the security attestation service for app data, including creating attestation keys, destroying attestation keys, initializing attestation sessions, ending attestation sessions, and obtaining the data to verify location security. This module provides security attestation for image security verification and location security verification, ensuring that the image or location data is not tampered with.

Since: 5.0.0(12)

Modules to Import

import { trustedAppService, mediaAuthVerify } from '@kit.DeviceSecurityKit';

createAttestKey

createAttestKey(options: AttestOptions): Promise<void>

Creates an attestation key. This API is called when the attestation key does not exist or is unavailable. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
options AttestOptions Yes Parameters for generating an attestation key. You need to specify the key type and key size.

Returns:

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

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 The app profile does not have the required permission. Please refer to the "Enabling Device Security Service" section in the Device Security Kit development guide.
401 argument is invalid.
1011500001 algorithm param is invalid.
1011500002 algorithm param is missing.
1011500003 create attestation key failed.
1011500004 create anonymous certificate failed.
1011500005 operating file failed.
1011500006 IPC communication failed.

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let properties: Array<trustedAppService.AttestParam> = [
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_ALGORITHM,
    value: trustedAppService.AttestKeyAlg.ATTEST_ALG_ECC
  },
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_KEY_SIZE,
    value: trustedAppService.AttestKeySize.ATTEST_ECC_KEY_SIZE_256
  }
];
let options: trustedAppService.AttestOptions = {
  properties: properties,
};
await trustedAppService.createAttestKey(options)
  .then(
    (): void => {
      hilog.info(0x0000, 'testTag', 'Succeeded in creating attest key');
    }
  ).catch(
    (error: BusinessError): void => {
      let err = error as BusinessError;
      hilog.error(0x0000, 'testTag', `Failed to create attest key, code:${err.code}, message:${err.message}`);
    });

AttestOptions

Request parameters of the createAttestKey API.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
properties Array<AttestParam> No No Data passed by your app for generating the attestation key configuration.

AttestParam

Parameters in AttestOptions.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
tag AttestTag No No Tag passed by your app for generating the attestation key configuration.
value boolean | number | bigint | Uint8Array No No

Value of the tag passed by your app for generating the attestation key configuration.

boolean:

This parameter is reserved and not used currently.

number:

1. When tag is ATTEST_TAG_ALGORITHM, its value is of the AttestKeyAlg type.

2. When tag is ATTEST_TAG_KEY_SIZE, its value is of the AttestKeySize type.

3. When tag is ATTEST_TAG_DEVICE_TYPE, its value is of the AttestType type.

bigint:

When tag is ATTEST_TAG_DEVICE_ID, its value is a device ID, which is a random value of the int64 type.

Uint8Array:

This parameter is reserved and not used currently.

AttestTag

Attestation configuration tag types, expanded and defined using AttestTagType.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Value Description
ATTEST_TAG_INVALID AttestTagType.ATTEST_TAG_TYPE_INVALID | 0 Invalid tag.
ATTEST_TAG_ALGORITHM AttestTagType.ATTEST_TAG_TYPE_UINT | 1 Algorithm tag.
ATTEST_TAG_KEY_SIZE AttestTagType.ATTEST_TAG_TYPE_UINT | 2 Key size tag.
ATTEST_TAG_DEVICE_TYPE AttestTagType.ATTEST_TAG_TYPE_UINT | 3 Device type tag.
ATTEST_TAG_DEVICE_ID AttestTagType.ATTEST_TAG_TYPE_UINT | 4 Device serial number tag.

AttestTagType

Tag's data type definition.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Value Description
ATTEST_TAG_TYPE_INVALID 0<<28 Invalid tag type.
ATTEST_TAG_TYPE_INT 1<<28 INT data type.
ATTEST_TAG_TYPE_UINT 2<<28 UINT data type.
ATTEST_TAG_TYPE_ULONG 3<<28 ULONG data type.
ATTEST_TAG_TYPE_BOOL 4<<28 Bool data type.
ATTEST_TAG_TYPE_BYTES 5<<28 Bytes data type.

AttestKeyAlg

Attestation key algorithm.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Value Description
ATTEST_ALG_ECC 1 ECC algorithm.

AttestKeySize

Attestation key length.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Value Description
ATTEST_ECC_KEY_SIZE_256 256 Indicates that the attestation key length is 256 bits.
ATTEST_ECC_KEY_SIZE_384 384 Indicates that the attestation key length is 384 bits.

destroyAttestKey

destroyAttestKey(): Promise<void>

Destroys an attestation key. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 The app profile does not have the required permission. Please refer to the "Enabling Device Security Service" section in the Device Security Kit development guide.
1011500005 operating file failed.
1011500006 IPC communication failed.
1011500007 item not found.

Returns:

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

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

await trustedAppService.destroyAttestKey().then(
  (): void => {
    hilog.info(0x0000, 'testTag', 'Succeeded in destroying attest key');
  }
).catch(
  (error: BusinessError): void => {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to destroy attest key, code:${err.code}, message:${err.message}`);
  }
);

initializeAttestContext

initializeAttestContext(userData: string, options: AttestOptions): Promise<AttestReturnResult>

Initializes an attestation session, which is used after the attestation key is successfully created. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
userData string Yes User data passed for initializing an attestation session. The value contains 16 to 127 bytes.
options AttestOptions Yes Parameters for initializing an attestation session. You need to specify the device type and device ID.

Returns:

Type Description
Promise<AttestReturnResult> Promise used to return the generated anonymous certificate chain.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 The app profile does not have the required permission. Please refer to the "Enabling Device Security Service" section in the Device Security Kit development guide.
401 argument is invalid.
1011500002 param is missing.
1011500005 operating file failed.
1011500006 IPC communication failed.
1011500007 item not found.
1011500008 anonymous certificate verify failed.
1011500009 anonymous certificate has expired.
1011500010 get attestation key failed.
1011500011 initialize secure camera failed.

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// The following uses the location security verification scenario as an example.
const deviceId = 0;
const initProperties: Array<trustedAppService.AttestParam> = [
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_DEVICE_TYPE,
    value: trustedAppService.AttestType.ATTEST_TYPE_LOCATION
  },
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_DEVICE_ID,
    value: BigInt(deviceId) // This parameter does not take effect in secure location scenarios.
  }
];
const initOptions: trustedAppService.AttestOptions = {
  properties: initProperties
};
let userData = 'trusted_app_service_default_userdata'; // Example value. Generate a value on your own, which contains 16 to 127 bytes.
// Initialize an attestation session.
try {
  const certChainResult = await trustedAppService.initializeAttestContext(userData, initOptions);
} catch (err) {
  const error = err as BusinessError;
  console.error(`Failed to initialize attest context, code:${error.code}, message:${error.message}`);
}

AttestType

Attestation session type.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Value Description
ATTEST_TYPE_LOCATION 1

Location security attestation session.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_TYPE_CAMERA 2 Image security attestation session.
ATTEST_TYPE_SECIMAGE_PROCESS 3 Attestation session for secure image processing. Since: 5.1.0(18).

AttestReturnResult

Return value of the initializeAttestContext API.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Type Read-Only Optional Description
certChains Array<string> No No Anonymous certificate chain returned after an attestation session is successfully initialized.

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// device_id must be set to the Bigint type.
let device_id_tt = 12581;
// The userdata length must be greater than 16 bytes and not exceed 127 bytes.
let user_data = "test_user_data_0000"
let properties2: Array<trustedAppService.AttestParam> = [
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_DEVICE_TYPE,
    value: trustedAppService.AttestType.ATTEST_TYPE_LOCATION
  },
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_DEVICE_ID,
    value: BigInt(device_id_tt)
  },
];
let options2: trustedAppService.AttestOptions = {
  properties: properties2,
};
await trustedAppService.initializeAttestContext(user_data, options2).then(
  (returnResult: trustedAppService.AttestReturnResult): void => {
    let chains = returnResult.certChains as Array<string>;
    for (const item of chains) {
      hilog.info(0x0000, 'testTag', 'item: ' + item);
    };
  }
).catch(
  (error: BusinessError): void => {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to initialize attest context, code:${err.code}, message:${err.message}`);
  }
);

AttestExceptionErrCode

Error codes of the APIs provided by the TrustedAppService for creating an attestation key, destroying an attestation key, initializing an attestation session, ending an attestation session, and obtaining the data to verify location security.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Name Value Description
ATTEST_ERROR_NO_PERMISSION 201

Permission verification failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_ILLEGAL_ARGUMENT 401

Parameter check failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_INVALID_ALG_ARGUMENT 1011500001

Invalid algorithm parameter.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_MISSING_ARGUMENT 1011500002

Some parameters are missing.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_KEY_GENERATOR_FAILED 1011500003

Key generation failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_CERTS_CREATION_FAILED 1011500004

Certificate creation failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_FILE_OPERATION_FAILED 1011500005

File operation failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_COMMUNICATION_FAILED 1011500006

IPC failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_ITEM_NOT_FOUND 1011500007

The key does not exist.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_CERTS_VERIFICATION_FAILED 1011500008

Certificate verification failed.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_CERTS_EXPIRED 1011500009

The certificate has expired.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_KEY_NOT_MATCHED 1011500010

The key does not match.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_SECURE_CAMERA_INITIALIZATION_FAILED 1011500011

Failed to initialize the camera in secure mode.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_CONTEXT_BAD_STATE 1011500012

The attestation session context is abnormal.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_KEY_EXPIRED 1011500013

The key has expired.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_LOCATION_SERVICE_UNAVAILABLE 1011500014

The location service is not available.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_LOCATION_SWITCH_OFF 1011500015

The location service is disabled.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_LOCATION_FAILED 1011500016

Failed to obtain the location information.

Atomic service API: This API can be used in atomic services since version 5.0.2(14).
ATTEST_ERROR_SIGNATURE_VERIFICATION_FAILED 1011500017

Signature verification failed.

Since: 5.1.0(18)
ATTEST_ERROR_SECIMAGE_PROCESS_FAILED 1011500018

Failed to process the secure image.

Since: 5.1.0(18)

finalizeAttestContext

finalizeAttestContext(options: AttestOptions): Promise<void>

Ends an attestation session. This API is called after the security attestation service is ended. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
options AttestOptions Yes Parameters for ending an attestation session. You need to specify the device type.

Returns:

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

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 The app profile does not have the required permission. Please refer to the "Enabling Device Security Service" section in the Device Security Kit development guide.
401 argument is invalid.
1011500002 param is missing.
1011500006 IPC communication failed.
1011500007 item not found.

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

let properties: Array<trustedAppService.AttestParam> = [
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_DEVICE_TYPE,
    value: trustedAppService.AttestType.ATTEST_TYPE_CAMERA
  }
];
let options: trustedAppService.AttestOptions = {
  properties: properties,
};
await trustedAppService.finalizeAttestContext(options).then(
  (): void => {
    hilog.info(0x0000, 'testTag', 'Succeeded in finalizing attest context');
  }
).catch(
  (error: BusinessError): void => {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to finalize attest context, code:${err.code}, message:${err.message}`);
  }
);

getCurrentSecureLocation

getCurrentSecureLocation(timeout : number, priority: LocatingPriority): Promise<SecureLocation>

Obtains the data to verify location security. This API uses a promise to return the result.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Location

Required permissions: ohos.permission.LOCATION and ohos.permission.APPROXIMATELY_LOCATION

Since: 5.0.0(12)

Parameters:

Name Type Mandatory Description
timeout number Yes Timeout interval for a single location obtaining request, in milliseconds. The minimum value is 1000. The value must be greater than or equal to 1000.
priority LocatingPriority Yes Priority policy for obtaining the data to verify location security.

Returns:

Type Description
Promise<SecureLocation> Promise used to return the obtained secure location.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 has no permission.
401 argument is invalid.
1011500012 attestation context not initialized.
1011500013 attestation key has expired.
1011500014 location service is unavailable.
1011500015 The location switch is off.
1011500016 Failed to obtain the secure geographical location.

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

// The accuracy-first mode is used as an example.
const timeout = 5000; // Timeout interval for obtaining the data to verify location security, in milliseconds.
const priority = trustedAppService.LocatingPriority.PRIORITY_ACCURACY;
let secureLocation: trustedAppService.SecureLocation;
try {
  secureLocation = await trustedAppService.getCurrentSecureLocation(timeout, priority);
} catch (err) {
  const error = err as BusinessError;
  console.error(`Failed to get current secure location, code:${error.code},  message:${error.message}`);
}

LocatingPriority

Priority policy for obtaining the data to verify location security.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Location

Since: 5.0.0(12)

Name Value Description
PRIORITY_ACCURACY 0 Accuracy first. The location data accuracy takes precedence.
PRIORITY_LOCATING_SPEED 1 Speed first. The location obtaining speed takes precedence.

SecureLocation

Data obtained to verify location security.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Location

Since: 5.0.0(12)

Name Type Read-Only Optional Description
originalLocation Location No No Geographical location information.
userData String No No User data. The value contains 16 to 127 bytes.
signature String No No

Signature result.

When the attestation key length is 256 bits, the signature length is 96 bytes.

When the attestation key length is 384 bits, the signature length is 136 or 140 bytes.

Location

Geographical location information.

Atomic service API: This API can be used in atomic services since API version 5.0.2(14).

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

System capability: SystemCapability.Security.TrustedAppService.Location

Since: 5.0.0(12)

Name Type Read-Only Optional Description
latitude number No No Latitude. A positive value indicates north latitude, and a negative value indicates south latitude. The value ranges from –90 to 90. Only the WGS84 coordinate system is supported.
longitude number No No Longitude. A positive value indicates east longitude, and a negative value indicates west longitude. The value ranges from -180 to 180. Only the WGS84 coordinate system is supported.
altitude number No No Height, in meters.
accuracy number No No Accuracy, in meters. The value must be greater than or equal to 0.
timestamp number No No Timestamp, in milliseconds. The value must be greater than or equal to 0.

Example:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

try {
  const secureLocation = await trustedAppService.getCurrentSecureLocation(3000, trustedAppService.LocatingPriority.PRIORITY_LOCATING_SPEED);
  hilog.info(0x0000, 'testTag', 'Succeeded in getting secure location, result = ${JSON.stringify(secureLocation)}');
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to get secure location, code:${err.code}, message:${err.message}`);
}

procSecImageTransform

procSecImageTransform(srcSecImage: ArrayBuffer, procParams: SecImageProcParamsArray): Promise<SecImageBuffer>

Compresses and crops a secure image. This API uses a promise to return the result.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Device behavior differences: This API is supported on phones, tablets, and PCs/2-in-1 devices that support the secure camera capability. On phones, tablets, and PCs/2-in-1 devices that do not support the secure camera capability, as well as on other device types, this API returns service error code 1011500011.

Since: 5.1.0(18)

Parameters:

Name Type Mandatory Description
srcSecImage ArrayBuffer Yes Signed secure image returned by the camera in secure mode.
procParams SecImageProcParamsArray Yes Secure image compression and cropping parameters.

Returns:

Type Description
Promise<SecImageBuffer> Promise used to return the signed secure image after compression and cropping.

Error codes:

For details about the error codes, please refer to ArkTS API Error Codes.

ID Error Message
201 The app profile does not have the required permission. Please refer to the "Enabling Device Security Service" section in the Device Security Kit development guide.
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified. 2. Incorrect parameter types. 3.Parameter verification failed.
1011500011 secure image processing is not supported.
1011500012 attestation context not initialized.
1011500013 attestation key has expired.
1011500017 signature verification failed.
1011500018 secure image process failed.

Example of secure image compression:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const srcSecImageBuffer = new ArrayBuffer(461844);// Replace it with the secure image buffer obtained from Camera Kit.

let properties: Array<trustedAppService.SecImageProcParams> = [
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_PROC_OPERATION,
    value: trustedAppService.SecImageProcOperation.SECIMAGE_COMPRESSION,
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_SRC_IMAGE_FORMAT,
    value: trustedAppService.SecImageProcFormat.SECIMAGE_FORMAT_YUV_NV21, // The input image format is YUV420 NV21 for both the secure image compression and cropping commands.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_DEST_IMAGE_FORMAT,
    value: trustedAppService.SecImageProcFormat.SECIMAGE_FORMAT_JPEG, // The image format returned by the secure image compression command is JPEG.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_COMPRESSION_QUALITY,
    value: 90, // Replace it with the compression quality required by the service scenario.
  },
];
let procParams: trustedAppService.SecImageProcParamsArray = {
  properties: properties,
};
await trustedAppService.procSecImageTransform(srcSecImageBuffer, procParams).then(
  (returnResult: trustedAppService.SecImageBuffer): void => {
    let returnSecImageBuffer = returnResult.secImage;
  }
).catch(
  (error: BusinessError): void => {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to process secureImage compression, code:${err.code}, message:${err.message}`);
  }
);

Example of secure image cropping:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const srcSecImageBuffer = new ArrayBuffer(461844);// Replace it with the secure image buffer obtained from Camera Kit.

let properties: Array<trustedAppService.SecImageProcParams> = [
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_PROC_OPERATION,
    value: trustedAppService.SecImageProcOperation.SECIMAGE_CROPPING,
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_SRC_IMAGE_FORMAT,
    value: trustedAppService.SecImageProcFormat.SECIMAGE_FORMAT_YUV_NV21, // The input image format is YUV420 NV21 for both the secure image compression and cropping commands.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_DEST_IMAGE_FORMAT,
    value: trustedAppService.SecImageProcFormat.SECIMAGE_FORMAT_YUV_NV21, // The image format returned by the secure image cropping command is YUV420 NV21.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_CROP_REGION,
    value: { x : 0, y : 0, width : 320, height : 240 }, // Replace the value with the cropping area range required by the service scenario.
  },
];
let procParams: trustedAppService.SecImageProcParamsArray = {
  properties: properties,
};
await trustedAppService.procSecImageTransform(srcSecImageBuffer, procParams).then(
  (returnResult: trustedAppService.SecImageBuffer): void => {
    let returnSecImageBuffer = returnResult.secImage;
  }
).catch(
  (error: BusinessError): void => {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to process secureImage cropping, code:${err.code}, message:${err.message}`);
  }
);

Example of secure image compression and cropping:

import { trustedAppService } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const srcSecImageBuffer = new ArrayBuffer(461844);// Replace it with the secure image buffer obtained from Camera Kit.

let properties: Array<trustedAppService.SecImageProcParams> = [
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_PROC_OPERATION,
    value: trustedAppService.SecImageProcOperation.SECIMAGE_COMPRESSION_AND_CROPPING,
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_SRC_IMAGE_FORMAT,
    value: trustedAppService.SecImageProcFormat.SECIMAGE_FORMAT_YUV_NV21, // The input image format is YUV420 NV21 for both the secure image compression and cropping commands.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_DEST_IMAGE_FORMAT,
    value: trustedAppService.SecImageProcFormat.SECIMAGE_FORMAT_JPEG, // The image format returned by the secure image compression and cropping command is JPEG.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_COMPRESSION_QUALITY,
    value: 90, // Replace it with the compression quality required by the service scenario.
  },
  {
    tag: trustedAppService.SecImageProcTag.SECIMAGE_TAG_CROP_REGION,
    value: { x : 0, y : 0, width : 320, height : 240 }, // Replace the value with the cropping area range required by the service scenario.
  },
];
let procParams: trustedAppService.SecImageProcParamsArray = {
  properties: properties,
};
await trustedAppService.procSecImageTransform(srcSecImageBuffer, procParams).then(
  (returnResult: trustedAppService.SecImageBuffer): void => {
    let returnSecImageBuffer = returnResult.secImage;
  }
).catch(
  (error: BusinessError): void => {
    let err = error as BusinessError;
    hilog.error(0x0000, 'testTag', `Failed to process secureImage compression and cropping, code:${err.code}, message:${err.message}`);
  }
);

SecImageProcParamsArray

Request parameters of the procSecImageTransform API.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Type Read-Only Optional Description
properties Array<SecImageProcParams> No No Configuration passed by your app for secure image compression and cropping.

SecImageProcParams

Parameters in SecImageProcParamsArray.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Type Read-Only Optional Description
tag SecImageProcTag No No Tag passed by your app for secure image compression and cropping.
value number | CropRegion No No

Value of the tag passed by your app for secure image compression and cropping.

number:

(1) When tag is SECIMAGE_TAG_SRC_IMAGE_FORMAT or

SECIMAGE_TAG_DEST_IMAGE_FORMAT,

its value is of the SecImageProcParamsArray type.

(2) When tag is SECIMAGE_TAG_PROC_OPERATION, its value is of the SecImageProcOperation type.

(3) When tag is SECIMAGE_TAG_COMPRESSION_QUALITY, its value ranges from 1 to 100.

CropRegion:

When tag is SECIMAGE_TAG_CROP_REGION, its value is of the CropRegion type.

SecImageProcTag

Configuration tag for secure image compression and cropping, expanded and defined using AttestTagType.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Value Description
SECIMAGE_TAG_INVALID AttestTagType.ATTEST_TAG_TYPE_INVALID | 0 Invalid tag.
SECIMAGE_TAG_SRC_IMAGE_FORMAT AttestTagType.ATTEST_TAG_TYPE_UINT | 1 Format of the input secure image.
SECIMAGE_TAG_DEST_IMAGE_FORMAT, AttestTagType.ATTEST_TAG_TYPE_UINT | 2 Format of the secure image after compression and cropping.
SECIMAGE_TAG_PROC_OPERATION AttestTagType.ATTEST_TAG_TYPE_UINT | 3 Secure image processing command, including compression, cropping, and compression + cropping.
SECIMAGE_TAG_COMPRESSION_QUALITY AttestTagType.ATTEST_TAG_TYPE_UINT | 4 Compression quality for secure image compression.
SECIMAGE_TAG_CROP_REGION AttestTagType.ATTEST_TAG_TYPE_UINT | 5 Cropping area for secure image cropping.

SecImageProcOperation

Secure image processing command.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Value Description
SECIMAGE_COMPRESSION 0 Secure image compression command.
SECIMAGE_CROPPING 1 Secure image cropping command.
SECIMAGE_COMPRESSION_AND_CROPPING 2 Secure image compression and cropping command.

SecImageProcFormat

Secure image format.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Value Description
SECIMAGE_FORMAT_INVALID 0 Invalid secure image format.
SECIMAGE_FORMAT_YUV_NV21 1 YUV420 NV21. The input secure image format and the secure image format returned by the cropping command are both SECIMAGE_FORMAT_YUV_NV21.
SECIMAGE_FORMAT_JPEG 2 JPEG. The secure image format returned by the compression command and the compression + cropping command is SECIMAGE_FORMAT_JPEG.

CropRegion

Cropping area for secure image cropping. The following figure shows the cropping area parameters.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Type Read-Only Optional Description
x number No No Horizontal offset of the top-left corner of the cropping area relative to the left edge of the entire image. The value is an even number ranging from 0 to 640. The unit is pixels.
y number No No Vertical offset of the top-left corner of the cropping area relative to the upper edge of the entire image. The value is an even number ranging from 0 to 480. The unit is pixels.
width number No No Width of the cropping area (horizontal length). The value is an even number ranging from 0 to 640. The sum of x and width must be less than or equal to 640. The unit is pixels.
height number No No Height of the cropping area (vertical length). The value is an even number ranging from 0 to 480. The sum of y and height must be less than or equal to 480. The unit is pixels.

SecImageBuffer

Obtains the signed secure image after compression and cropping.

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

System capability: SystemCapability.Security.TrustedAppService.Core

Since: 5.1.0(18)

Name Type Read-Only Optional Description
secImage ArrayBuffer No No Signed secure image after compression and cropping.

ImageAuthData

Image data to be verified.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Name Type Read-Only Optional Description
buffer Uint8Array No No Image data array or image URL.
imageSize number No No Image data size.
bufferType BufferType Yes No Image data format.
imageFormat ImageFormat Yes No Image format.

ImageBufferFormat

Image array type.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Name Value Description
IMAGE_DATA_TYPE_DATAFLOW 0 The image type is data stream.
IMAGE_DATA_TYPE_URL 1 The image type is URL.

BufferType

Image data format, one of the struct parameters in ImageAuthData.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Name Value Description
BUFFER_TYPE_DATA 0 Image in array format.
BUFFER_TYPE_URL 1 Image in URL string format.

ImageFormat

Image format, one of the struct parameters in ImageAuthData.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Name Value Description
IMAGE_TYPE_JPEG 0 JPEG.
IMAGE_TYPE_DNG 1 DNG.
IMAGE_TYPE_HEIF 2 HEIF.

ContentTrustCredentialsErrorCode

Error codes of the content authenticity capability.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Name Value Description
CONTENT_TRUST_CREDENTIAL_ERROR_BAD_IMAGE_TYPE 1027200001 Incorrect image type.
CONTENT_TRUST_CREDENTIAL_ERROR_OUT_OF_STORE 1027200002 Insufficient storage space.
CONTENT_TRUST_CREDENTIAL_ERROR_WRONG_SIGN_CERT_PARAM 1027200003 Incorrect signing certificate information.
CONTENT_TRUST_CREDENTIAL_ERROR_CHECK_IMAGE_HASH_FAILED 1027200004 Image hash detection failed.
CONTENT_TRUST_CREDENTIAL_ERROR_SIGN_FAILED 1027200005 Image signature calculation failed.
CONTENT_TRUST_CREDENTIAL_ERROR_VERIFY_FAILED 1027200006 Signature verification failed.
CONTENT_TRUST_CREDENTIAL_ERROR_NO_SIGN_ASSERTION 1027200007 No signature assertion found in the image signature.
CONTENT_TRUST_CREDENTIAL_ERROR_NO_SIGN_MANIFEST 1027200008 No signature manifest found in the image signature.
CONTENT_TRUST_CREDENTIAL_ERROR_WRONG_CERT_CHAINS 1027200009 Certificate chain verification failed or the root certificate of the certificate chain is invalid in the signature information.
CONTENT_TRUST_CREDENTIAL_ERROR_PLATFORM_NOT_SUPPORTED 1027200010 This API is not supported on this platform.
CONTENT_TRUST_CREDENTIAL_ERROR_BAD_METADATA 1027200011 The metadata information of the signature is invalid.
CONTENT_TRUST_CREDENTIAL_ERROR_CLAIM_INVALID 1027200012 The signature claim information is invalid.
CONTENT_TRUST_CREDENTIAL_ERROR_FILE_OPERATION_FAILED 1027200013 The file operation failed.
CONTENT_TRUST_CREDENTIAL_ERROR_ILLEGAL_ARGUMENT 1027200014 The input parameter of the function is invalid.

hasImageSignature

hasImageSignature(data: ImageAuthData): Promise<boolean>

Checks whether a content authenticity signature exists in an image. This API uses a promise to return the result.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Parameters:

Name Type Mandatory Description
data ImageAuthData Yes Image data structure.

Returns:

Type Description
Promise<boolean> Promise used to return the result. If true is returned, an attestation signature exists. If false is returned, no attestation signature exists.

Error codes:

For details about the error codes, please refer to Universal Error Codes and TrustedAppService Error Codes.

ID Error Message
401 invalid params type.
1027200001 Incorrect image format.
1027200007 No signature assertion found in the image.
1027200008 No signature manifest found in the image signature.
1027200010 APIs not supported on the platform.
1027200013 File operation failed.
1027200014 argument is invalid.

Example:

import { mediaAuthVerify } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const imageBuffer = new Uint8Array([0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x01, 0x00, 0x60, 0x00, 0x60, 0x00, 0x00, 0xFF, 0xDB, 0x00, 0x43, 0x00, 0x08, 0x06, 0x06, 0x07, 0x06, 0x05, 0x08, 0x07, 0x07, 0x07, 0x09, 0x09, 0x08, 0x0A, 0x0C, 0x14, 0x0D, 0x0C, 0x0B, 0x0B, 0x0C, 0x19, 0x12, 0x13, 0x0F, 0x14, 0x1D, 0x1A, 0x1F, 0x1E, 0x1D, 0x1A, 0x1C, 0x1C, 0x20, 0x24, 0x2E, 0x27, 0x20, 0x22, 0x2C, 0x23, 0x1C, 0x1C, 0x28, 0x37, 0x29, 0x2C, 0x30, 0x31, 0x34, 0x34, 0x34, 0x1F, 0x27, 0x39, 0x3D, 0x38, 0x32, 0x3C, 0x2E, 0x33, 0x34, 0x32, 0xFF, 0xC0, 0x00, 0x0B, 0x08, 0x00, 0x01, 0x00, 0x01, 0x01, 0x01, 0x11, 0x00, 0xFF, 0xC4, 0x00, 0x14, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xC4, 0x00, 0x14, 0x10, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01, 0x01, 0x00, 0x00, 0x3F, 0x00, 0x37, 0xFF, 0xD9]); // The data provided is for illustrative purposes only to demonstrate how to check for signatures. For actual implementation, please use images signed by the camera.
const data:mediaAuthVerify.ImageAuthData = {
  buffer: imageBuffer,
  imageSize: imageBuffer.length,
  bufferType: mediaAuthVerify.BufferType.BUFFER_TYPE_DATA,
  imageFormat: mediaAuthVerify.ImageFormat.IMAGE_TYPE_JPEG,
};
try {
  const result = await mediaAuthVerify.hasImageSignature(data);
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to check image signature, code:${err.code}, message:${err.message}`);
}

verifyImageSignature

verifyImageSignature(data: ImageAuthData): Promise<Uint8Array>

Verifies the attestation signature of the image content. Upon successful execution, this API returns the manifest data of the attestation content. This API uses a promise to return the result.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Parameters:

Name Type Mandatory Description
data ImageAuthData Yes Image data.

Returns:

Type Description
Promise<Uint8Array> Promise used to return the manifest data object after signature verification.

Error codes:

For details about the error codes, please refer to Universal Error Codes and TrustedAppService Error Codes.

ID Error Message
401 invalid params type.
1027200001 Incorrect image format.
1027200004 Image data hash check failed.
1027200006 Signature verification failed.
1027200007 No signature assertion found in the image signature.
1027200008 No signature manifest found in the image signature.
1027200009 Certificate chain verification failed or the root certificate is invalid in the signature information.
1027200010 APIs not supported on the platform.
1027200012 Invalid claim information during signature verification.
1027200013 File operation failed.
1027200014 argument is invalid.

Example:

import { mediaAuthVerify } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const imageBuffer = new Uint8Array([0xFF, 0xD8, 0xFF, 0xE0, 0x00, 0x10, 0x4A, 0x46, 0x49, 0x46, 0x00, 0x01, 0x01, 0x01, 0x00, 0x60, 0x00, 0x60, 0x00, 0x00, 0xFF, 0xDB, 0x00, 0x43, 0x00, 0x08, 0x06, 0x06, 0x07, 0x06, 0x05, 0x08, 0x07, 0x07, 0x07, 0x09, 0x09, 0x08, 0x0A, 0x0C, 0x14, 0x0D, 0x0C, 0x0B, 0x0B, 0x0C, 0x19, 0x12, 0x13, 0x0F, 0x14, 0x1D, 0x1A, 0x1F, 0x1E, 0x1D, 0x1A, 0x1C, 0x1C, 0x20, 0x24, 0x2E, 0x27, 0x20, 0x22, 0x2C, 0x23, 0x1C, 0x1C, 0x28, 0x37, 0x29, 0x2C, 0x30, 0x31, 0x34, 0x34, 0x34, 0x1F, 0x27, 0x39, 0x3D, 0x38, 0x32, 0x3C, 0x2E, 0x33, 0x34, 0x32, 0xFF, 0xC0, 0x00, 0x0B, 0x08, 0x00, 0x01, 0x00, 0x01, 0x01, 0x01, 0x11, 0x00, 0xFF, 0xC4, 0x00, 0x14, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xC4, 0x00, 0x14, 0x10, 0x01, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xFF, 0xDA, 0x00, 0x08, 0x01, 0x01, 0x00, 0x00, 0x3F, 0x00, 0x37, 0xFF, 0xD9]); // The data provided is for illustrative purposes only to demonstrate how to check for signatures. For actual implementation, please use images signed by the camera.
const data:mediaAuthVerify.ImageAuthData = {
  buffer: imageBuffer,
  imageSize: imageBuffer.length,
  bufferType: mediaAuthVerify.BufferType.BUFFER_TYPE_DATA,
  imageFormat: mediaAuthVerify.ImageFormat.IMAGE_TYPE_JPEG,
};
try {
  const result = await mediaAuthVerify.verifyImageSignature(data);
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to verify image signature, code:${err.code}, message:${err.message}`);
}

parseImageMetadata

parseImageMetadata(manifests: Uint8Array): Promise<string>

Parses the manifest data obtained from signature verification to obtain the result in JSON format. This API must be called after verifyImageSignature is successfully called. This API uses a promise to return the result.

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

System capability: SystemCapability.Security.TrustedAppService.ContentTrustCredentials

Since: 26.0.0

Parameters:

Name Type Mandatory Description
manifests Uint8Array Yes Manifest information after the image signature is verified.

Returns:

Type Description
Promise<string> Promise used to return the JSON-formatted string of the manifest after signature verification.

Error codes:

For details about the error codes, please refer to Universal Error Codes and TrustedAppService Error Codes.

ID Error Message
401 The input argument is invalid.
1027200002 Insufficient storage space for the service.
1027200010 APIs not supported on the platform.
1027200014 argument is invalid.

Example:

import { mediaAuthVerify } from '@kit.DeviceSecurityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { util } from '@kit.ArkTS';

const file = "/data/local/testpic/pics/jpgpic.jpg";// This path is an example and is used only to demonstrate how to pass the URL. Use the correct image URL in actual scenarios.
let encoder = new util.TextEncoder();
let imageBuffer = encoder.encodeInto(file);
const data:mediaAuthVerify.ImageAuthData = {
  buffer: imageBuffer,
  imageSize: imageBuffer.length,
  bufferType: mediaAuthVerify.BufferType.BUFFER_TYPE_DATA,
  imageFormat: mediaAuthVerify.ImageFormat.IMAGE_TYPE_JPEG,
};
try {
  let manifest = await mediaAuthVerify.verifyImageSignature(data);
  let stringResult = await mediaAuthVerify.parseImageMetadata(manifest);
} catch (error) {
  let err = error as BusinessError;
  hilog.error(0x0000, 'testTag', `Failed to verify image signature, code:${err.code}, message:${err.message}`);
}