安全地理位置场景
========

#### 场景介绍

在安全地理位置场景中，通过创建证明密钥、打开证明会话的方式，对从GPS硬件或网络位置获取到的地理位置信息进行签名，确保地理位置信息的真实性和完整性。

#### 约束与限制

该特性需要设备支持安全地理位置功能。

开发者在调用[initializeAttestContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#initializeattestcontext)接口成功初始化安全地理位置的证明会话后，通过调用[getCurrentSecureLocation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#getcurrentsecurelocation)接口尝试获取安全地理位置，当接口异常并返回[ATTEST\_ERROR\_LOCATION\_SERVICE\_UNAVAILABLE](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/errorcode-devicesecurity-taas#section1011500014-位置服务不可用)时，当前设备不支持安全地理位置。具体判断方法参考如下示例：

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

// 初始化安全地理位置证明会话后，获取安全地理位置信息，以精度优先为例
const timeout = 5000; // 获取安全地理位置的超时时间，单位为毫秒
const priority = trustedAppService.LocatingPriority.PRIORITY\_ACCURACY; // 采用精度优先策略
let secureLocation: trustedAppService.SecureLocation;
// 获取当前安全地理位置信息
try {
  secureLocation = await trustedAppService.getCurrentSecureLocation(timeout, priority);
} catch (err) {
  const error = err as BusinessError;
  if (error.code == trustedAppService.AttestExceptionErrCode.ATTEST\_ERROR\_LOCATION\_SERVICE\_UNAVAILABLE) {
      console.error(\`current device not support secure location\`);
  } else {
      console.error(\`Failed to get current secure location, message:${error.message}, code:${error.code}\`);
  }
}

#### 业务流程

![](https://contentcenter-vali-drcn.dbankcdn.cn/pvt_2/DeveloperAlliance_scene_100_1/2e/v3/WT91uvYxRwe_VNtXaIaTDg/zh-cn_image_0000002594668618.jpg?HW-CC-KV=V1&HW-CC-Date=20260612T073410Z&HW-CC-Expire=86400&HW-CC-Sign=CA93CDB8CD22587FC6485C8DD127C382073AC82A75BCC5B04293BE4A19B212EA)

应用获取安全地理位置的优先级策略有两种，分别是精度优先和速度优先。如果选择精度优先策略，可信应用服务会优先返回GPS的结果，GPS获取超时后返回网络地理位置；而如果选择速度优先策略，可信应用服务会返回从二者中最先获取到的结果。

#### 接口说明

接口及使用方法请参见[API参考](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api)。

| 接口名 | 描述 |
| :-- | :-- |
| [createAttestKey](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#createattestkey)(options: AttestOptions): Promise<void> | 创建证明密钥。 |
| [initializeAttestContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#initializeattestcontext)(userData: string, options: AttestOptions): Promise<AttestReturnResult> | 初始化证明会话。 |
| [finalizeAttestContext](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#finalizeattestcontext)(options: AttestOptions): Promise<void> | 结束证明会话。 |
| [destroyAttestKey](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#destroyattestkey)(): Promise<void> | 销毁证明密钥。 |
| [getCurrentSecureLocation](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#getcurrentsecurelocation)(timeout: number, priority: LocatingPriority): Promise<SecureLocation> | 获取安全地理位置信息。 |

#### 开发步骤

1.  申请位置权限，权限名称为“[ohos.permission.APPROXIMATELY\_LOCATION](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all-user#ohospermissionapproximately_location)”和“[ohos.permission.LOCATION](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/permissions-for-all-user#ohospermissionlocation)”，具体请参考[向用户申请授权](https://developer.huawei.com/consumer/cn/doc/harmonyos-guides/request-user-authorization)。
    
2.  导入可信应用服务模块。
    
    import { trustedAppService } from '@kit.DeviceSecurityKit';
    import { BusinessError } from '@kit.BasicServicesKit';
    
3.  创建证明密钥并初始化证明会话。
    
    // 创建证明密钥的参数
    const createProperties: 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
      }
    \];
    const createOptions: trustedAppService.AttestOptions = {
      properties: createProperties
    };
    // 初始化证明会话的参数
    const userData = "trusted\_app\_service\_demo" // 示例值，实际值请自行生成，长度在16到127 Bytes之间
    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(0) // 此参数在安全地理位置场景下不生效
      }
    \];
    const initOptions: trustedAppService.AttestOptions = {
      properties: initProperties
    };
    // 创建证明密钥并打开证明会话
    let certChainList: Array<string>;
    try {
      await trustedAppService.createAttestKey(createOptions);
      const result = await trustedAppService.initializeAttestContext(userData, initOptions);
      certChainList = result.certChains;
    } catch (err) {
      const error = err as BusinessError;
      console.error(\`Failed to initialize attest context, message:${error.message}, code:${error.code}\`);
    }
    
4.  获取安全地理位置信息，以精度优先为例。
    
    const timeout = 5000; // 获取安全地理位置的超时时间，单位为毫秒
    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, message:${error.message}, code:${error.code}\`);
    }
    
5.  结束证明会话。
    
    // 结束证明会话的参数
    const finalProperties: Array<trustedAppService.AttestParam> = \[
      {
        tag: trustedAppService.AttestTag.ATTEST\_TAG\_DEVICE\_TYPE,
        value: trustedAppService.AttestType.ATTEST\_TYPE\_LOCATION
      }
    \];
    const finalOptions: trustedAppService.AttestOptions = {
      properties: finalProperties,
    };
    // 结束证明会话
    try {
      await trustedAppService.finalizeAttestContext(finalOptions);
    } catch (err) {
      const error = err as BusinessError;
      console.error(\`Failed to finalize attest context, message:${error.message}, code:${error.code}\`);
    }
    
    如果需要销毁证明密钥，请在结束证明会话后，调用[destroyAttestKey](https://developer.huawei.com/consumer/cn/doc/harmonyos-references/devicesecurity-taas-api#destroyattestkey)接口。