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)
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 | 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}`);
}); 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. |
Parameters in AttestOptions.
System capability: SystemCapability.Security.TrustedAppService.Core
Start version: 5.0.0(12)
Parameter | Type | Read-only | Optional | Description |
|---|---|---|---|---|
tag | 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. |
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. |
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. |
Attestation key algorithm.
System capability: SystemCapability.Security.TrustedAppService.Core
Start version: 5.0.0(12)
Parameter | Value | Description |
|---|---|---|
ATTEST_ALG_ECC | 1 | ECC algorithm. |
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(): 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(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 | 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. |
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. |
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(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 | 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(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 | Yes | Timeout interval of a single location obtaining request, in milliseconds. | |
priority | 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. |
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. |
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 | Yes | No | Geographical location information. | |
userData | String | Yes | No | User data. |
signature | String | Yes | No | Signature result. |
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}`);
}