• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 安全单元访问开发指南
2
3## 简介
4安全单元（SecureElement，简称SE），电子设备上可能存在一个或多个安全单元，比如有eSE(Embedded SE)和SIM卡。能够充当安全单元的SIM卡，要求具备NFC功能。
5
6## 场景介绍
7应用程序可以通过接口访问安全单元，比如往安全单元里面写入数据，实现在电子设备上模拟一张NFC卡片的目的。该卡片数据可能存储在eSE安全单元，或在SIM卡安全单元上。安全单元上一般会预置有访问控制规则，应用程序需要具备对应的权限，也就是通过安全单元的访问控制权限校验之后，才能正常访问安全单元。
8
9## 接口说明
10完整的JS API说明以及实例代码请参考：[安全单元接口](../../reference/apis-connectivity-kit/js-apis-secureElement.md)。
11实现安全单元的访问，可能使用到下面的接口。
12
13| 接口名                             | 功能描述                                                                       |
14| ---------------------------------- | ------------------------------------------------------------------------------ |
15| newSEService(type: 'serviceState', callback: Callback\<ServiceState>): SEService                    | 建立一个可用于连接到系统中所有可用SE的新连接。                                                               |
16| getReaders(): Reader[]                      | 返回可用SE Reader的数组，包含该设备上支持的所有的安全单元。                                                                |
17| openSession(): Session                 | 在SE Reader实例上创建连接会话，返回Session实例。                                                                |
18| openLogicalChannel(aid: number[]): Promise\<Channel>                  | 打开逻辑通道，返回逻辑Channel实例对象。                                                                |
19| transmit(command: number[]): Promise\<number[]> | 向SE发送APDU数据                                                                |
20| close(): void | 关闭Channel。                                                            |
21
22
23## 主要场景开发步骤
24
25### 应用程序访问安全单元
261. import需要的安全单元模块。
272. 判断设备是否支持安全单元能力。
283. 访问安全单元，实现数据的读取或写入。
29
30```ts
31import { omapi } from '@kit.ConnectivityKit';
32import { BusinessError } from '@kit.BasicServicesKit';
33import { hilog } from '@kit.PerformanceAnalysisKit';
34import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
35
36
37let seService : omapi.SEService;
38let seReaders : omapi.Reader[];
39let seSession : omapi.Session;
40let seChannel : omapi.Channel;
41let aidArray : number[] = [0xA0, 0x00, 0x00, 0x00, 0x03, 0x10, 0x10];
42let p2 : number = 0x00;
43
44export default class EntryAbility extends UIAbility {
45  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
46    hilog.info(0x0000, 'testTag', '%{public}s', 'Ability onCreate');
47
48    // 判断设备是否支持安全单元能力
49    if (!canIUse("SystemCapability.Communication.SecureElement")) {
50      hilog.error(0x0000, 'testTag', 'secure element unavailable.');
51      return;
52    }
53
54    // get the service
55    try {
56      seService = omapi.newSEService("serviceState", (state) => {
57        hilog.info(0x0000, 'testTag', 'se service state = %{public}s', JSON.stringify(state));
58      });
59    } catch (error) {
60      hilog.error(0x0000, 'testTag', 'newSEService error %{public}s', JSON.stringify(error));
61    }
62    if (seService == undefined || !seService.isConnected()) {
63      hilog.error(0x0000, 'testTag', 'secure element service disconnected.');
64      return;
65    }
66
67    // get readers
68    try {
69      seReaders = seService.getReaders();
70    } catch (error) {
71      hilog.error(0x0000, 'testTag', 'getReaders error %{public}s', JSON.stringify(error));
72    }
73    if (seReaders == undefined || seReaders.length == 0) {
74      hilog.error(0x0000, 'testTag', 'no valid reader found.');
75      return;
76    }
77
78    // get session
79    try {
80      let reader = seReaders[0]; // change it to the selected reader, ese or sim.
81      seSession = reader.openSession();
82    } catch (error) {
83      hilog.error(0x0000, 'testTag', 'openSession error %{public}s', JSON.stringify(error));
84    }
85    if (seSession == undefined) {
86      hilog.error(0x0000, 'testTag', 'seSession invalid.');
87      return;
88    }
89
90    // get channel
91    try {
92      // change the aid value for open logical channel.
93      seSession.openLogicalChannel(aidArray, p2, (error, data) => {
94        if (error) {
95          hilog.error(0x0000, 'testTag', 'openLogicalChannel error %{public}s', JSON.stringify(error));
96        } else {
97          seChannel = data;
98        }
99      });
100    } catch (exception) {
101      hilog.error(0x0000, 'testTag', 'openLogicalChannel exception %{public}s', JSON.stringify(exception));
102    }
103    if (seChannel == undefined) {
104      hilog.error(0x0000, 'testTag', 'seChannel invalid.');
105      return;
106    }
107
108    // transmit data
109    let cmdData = [0x01, 0x02, 0x03, 0x04]; // please change the raw data to be correct.
110    try {
111      seChannel.transmit(cmdData).then((response) => {
112        hilog.info(0x0000, 'testTag', 'seChannel.transmit() response = %{public}s.', JSON.stringify(response));
113      }).catch((error : BusinessError) => {
114        hilog.error(0x0000, 'testTag', 'seChannel.transmit() error = %{public}s.', JSON.stringify(error));
115      });
116    } catch (exception) {
117      hilog.error(0x0000, 'testTag', 'seChannel.transmit() exception = %{public}s.', JSON.stringify(exception));
118    }
119
120    // close channel. must make sure the channel is closed at last.
121    try {
122      seChannel.close();
123    } catch (exception) {
124      hilog.error(0x0000, 'testTag', 'seChannel.close() exception = %{public}s.', JSON.stringify(exception));
125    }
126  }
127}
128```