目录

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.

Start version: 5.0.0(12)

Module Import

import { trustedAppService } 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 returns the result asynchronously through a promise.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameters:

Parameter

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.

Error Code

Message

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 proprities: 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: proprities,
};
await trustedAppService.createAttestKey(options)
  .then(
    (): void => {
      hilog.info(0x0000, 'testTag', 'Successed 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 parameter of the createAttestKey API.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

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.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

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.

AttestTag

Attestation configuration tag, whose definition is extended by AttestTagType.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

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.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

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.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

Value

Description

ATTEST_ALG_ECC

1

ECC algorithm.

AttestKeySize

Attestation key length.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

Value

Description

ATTEST_ECC_KEY_SIZE_256

256

Indicates that the attestation key length is 256 bytes.

ATTEST_ECC_KEY_SIZE_384

384

Indicates that the attestation key length is 384 bytes.

destroyAttestKey

destroyAttestKey(): Promise<void>

Destroys an attestation key. This API returns the result asynchronously through a promise.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Error codes:

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

Error Code

Message

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', 'Successed 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 returns the result asynchronously through a promise.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameters:

Parameter

Type

Mandatory

Description

userData

string

Yes

User data passed for initializing an attestation session. The value contains 16 to 128 characters.

options

AttestOptions

Yes

Parameters for initializing an attestation session. You need to specify the device type and device ID.

Returns:

Type

Description

Promise<AttestReturnResult>

Generated anonymous certificate chain.

Error codes:

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

Error Code

Message

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.

AttestType

Attestation session type.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

Value

Description

ATTEST_TYPE_LOCATION

1

Location security attestation session.

ATTEST_TYPE_CAMERA

2

Image security attestation session.

AttestReturnResult

Return value of the initializeAttestContext API.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameter

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 user data length must be greater than 16 characters and not exceed 128 characters.
let user_data = "test_user_data_0000"
let proprities2: 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: proprities2,
};
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}`);
  }
);

finalizeAttestContext

finalizeAttestContext(options: AttestOptions): Promise<void>

Ends an attestation session. This API is called after the security attestation service is ended. This API returns the result asynchronously through a promise.

System capability: SystemCapability.Security.TrustedAppService.Core

Start version: 5.0.0(12)

Parameters:

Parameter

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.

Error Code

Message

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 proprities: Array<trustedAppService.AttestParam> = [
  {
    tag: trustedAppService.AttestTag.ATTEST_TAG_DEVICE_TYPE,
    value: trustedAppService.AttestType.ATTEST_TYPE_CAMERA
  }
];
let options: trustedAppService.AttestOptions = {
  properties: proprities,
};
await trustedAppService.finalizeAttestContext(options).then(
  (): void => {
    hilog.info(0x0000, 'testTag', 'Successed 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 returns the result asynchronously through a promise.

System capability: SystemCapability.Security.TrustedAppService.Location

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

Start version: 5.0.0(12)

Parameters:

Parameter

Type

Mandatory

Description

timeout

AttestOptions

Yes

Timeout interval of a single location obtaining request, in milliseconds.

priority

LocatingPriority

Yes

Priority policy for obtaining the data to verify location security.

Returns:

Type

Description

Promise<SecureLocation>

Data obtained to verify location security.

Error codes:

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

Error Code

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.

LocatingPriority

Priority policy for obtaining the data to verify location security.

System capability: SystemCapability.Security.TrustedAppService.Location

Start version: 5.0.0(12)

Parameter

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.

System capability: SystemCapability.Security.TrustedAppService.Location

Start version: 5.0.0(12)

Parameter

Type

Read-only

Optional

Description

originalLocation

Location

Yes

No

Geographical location information.

userData

String

Yes

No

User data.

signature

String

Yes

No

Signature result.

Location

Geographical location information.

System capability: SystemCapability.Security.TrustedAppService.Location

Start version: 5.0.0(12)

Parameter

Type

Read-only

Optional

Description

latitude

number

Yes

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

Yes

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

Yes

No

Height, in meters.

accuracy

number

Yes

No

Accuracy.

timestamp

number

Yes

No

Timestamp, in milliseconds.

Example:

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

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