• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.net.eap (扩展认证)
2
3<!--Kit: Network Kit-->
4<!--Subsystem: Communication-->
5<!--Owner: @foredward-->
6<!--Designer: @h00918518-->
7<!--Tester: @WIFIroam-test-->
8<!--Adviser: @zhang_yixin13-->
9
10该模块提供了第三方客户端介入802.1X认证（一种基于端口的网络接入控制协议）流程的机制，支撑客户端的定制认证等功能。
11
12> **说明：**
13>
14> 本模块首批接口从API version 20开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
15
16## 导入模块
17
18```js
19import {eap} from '@kit.NetworkKit';
20```
21
22## eap.regCustomEapHandler
23
24regCustomEapHandler(netType: number, eapCode: number, eapType: number, callback: Callback\<EapData\>): void
25
26用于指定需要定制化处理的EAP报文类型和对应的处理callback。使用callback异步回调。
27
28系统会将符合条件的EAP报文送入callback函数中供企业应用获取。
29
30**需要权限**：ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
31
32**系统能力**：SystemCapability.Communication.NetManager.Eap
33
34**参数：**
35
36| 参数名                              | 类型|必填|说明|
37| ----------------------------- | ---------- |---------- |---------- |
38| netType| number|是|网络类型，取值为1或2。<br>netType=1表示WLAN，netType=2表示以太网。|
39| eapCode|number |是|需要进行定制的EAP code，取值为1、2、3、4 。<br>code=1 Request、 code=2 Response、 code=3 Success、 code=4 Failure。|
40| eapType| number |是|需要进行定制处理的EAP method类型，取值范围[0, 255]。<br>常用取值包括：eapType=1 Identity，eapType=2 Notification，eapType=3 NAK，eapType=4 MD5-Challenge，eapType=5 OTP（One-Time Password），eapType=6 GTC（Generic Token Card），eapType=13 EAP-TLS，eapType=21 EAP-TTLS，eapType=25 EAP-PEAP，eapType=254 Expanded Types，eapType=255 Experimental use。|
41| callback| Callback\<[EapData](#eapdata)\> |是|对指定的code+type的报文进行回调处理。|
42
43**错误码**：
44
45以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[扩展认证错误码](errorcode-net-eap.md)。
46
47| 错误码ID | 错误信息 |
48| -------- | ---------------------------- |
49|201 | Permission denied.          |
50|33200006 | Invalid net type.          |
51|33200007 | Invalid eap code.          |
52|33200008 | Invalid eap type.          |
53|33200009 | netmanager stop.          |
54|33200099 | internal error.          |
55
56**示例：**
57
58```js
59import {eap} from '@kit.NetworkKit';
60let netType = 1;
61let eapCode = 1;
62let eapType = 25;
63let  eapData = (eapData:eap.EapData):void => {
64  console.info("rsp result",JSON.stringify(eapData))
65}
66
67try {
68  eap.regCustomEapHandler(netType, eapCode, eapType, eapData);
69  console.info('regCustomEapHandler success');
70} catch (err) {
71  console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
72}
73```
74
75## eap.unregCustomEapHandler
76
77unregCustomEapHandler(netType:number, eapCode: number, eapType: number, callback: Callback\<EapData\>): void
78
79用于指定需要取消定制化处理的EAP报文类型和对应的处理callback。使用callback异步回调。
80
81**需要权限**：ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
82
83**系统能力**：SystemCapability.Communication.NetManager.Eap
84
85**参数：**
86
87| 参数名                            | 类型|必填|说明|
88| ----------------------------- | ---------- |---------- |---------- |
89| netType| number|是|网络类型，取值为1或2。<br>netType=1表示WLAN，netType=2表示以太网。|
90| eapCode|number |是|需要进行定制的EAP code，取值为1、2、3、4 。<br>code=1 Request、 code=2 Response、 code=3 Success、 code=4 Failure。|
91| eapType| number |是|需要进行定制处理的EAP method类型，取值范围[0, 255]。<br>常用取值包括：eapType=1 Identity，eapType=2 Notification，eapType=3 NAK，eapType=4 MD5-Challenge，eapType=5 OTP（One-Time Password），eapType=6 GTC（Generic Token Card），eapType=13 EAP-TLS，eapType=21 EAP-TTLS，eapType=25 EAP-PEAP，eapType=254 Expanded Types，eapType=255 Experimental use。|
92| callback| Callback\<[EapData](#eapdata)\> |是|对指定的code+type的报文进行回调处理。|
93
94**错误码**：
95
96以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[扩展认证错误码](errorcode-net-eap.md)。
97
98| 错误码ID | 错误信息 |
99| -------- | ---------------------------- |
100|201 | Permission denied.          |
101|33200006 | Invalid net type.          |
102|33200007 | Invalid eap code.          |
103|33200008 | Invalid eap type.          |
104|33200009 | netmanager stop.          |
105|33200099 | internal error.          |
106
107**示例：**
108
109```js
110import {eap} from '@kit.NetworkKit';
111let netType = 1;
112let eapCode = 1;
113let eapType = 25;
114let  eapData = (eapData:eap.EapData):void => {
115  console.info("rsp result",JSON.stringify(eapData))
116}
117
118try {
119  eap.unregCustomEapHandler(netType, eapCode, eapType, eapData);
120  console.info('unregCustomEapHandler success');
121} catch (err) {
122  console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
123}
124```
125
126## eap.replyCustomEapData
127
128replyCustomEapData(result: CustomResult, data: EapData): void
129
130该接口用于通知系统已完成该步定制化处理。
131
132 > **说明**:
133 >
134 >- 若用于处理收EAP数据包(rx)时的callback，传给系统的EAP数据需要剥离服务器添加的定制部分。
135 >- 若用于处理发EAP数据包(tx)时的callback，传给系统的EAP数据为经过添加定制部分后的EAP数据。
136
137**需要权限**：ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
138
139**系统能力**：SystemCapability.Communication.NetManager.Eap
140
141**参数：**
142
143| 参数名                            | 类型|必填|说明|
144| ----------------------------- | ---------- |---------- |---------- |
145| result | [CustomResult](#customresult)|是|定制化判定结果。|
146| data | [EapData](#eapdata) |是|经过定制化的EAP数据。|
147
148**错误码**：
149
150以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[扩展认证错误码](errorcode-net-eap.md)。
151
152| 错误码ID | 错误信息 |
153| -------- | ---------------------------- |
154|201 | Permission denied.          |
155|33200004 | Invalid result.          |
156|33200005 | Invalid size of eap data.          |
157|33200009 | netmanager stop.          |
158|33200099 | internal error.          |
159
160```js
161import {eap} from '@kit.NetworkKit';
162let eapData:eap.EapData= {
163  msgId: 1,
164  eapBuffer: new Uint8Array([1, 2, 3, 4, 5]),
165  bufferLen: 5,
166};
167let result = 1;
168
169try {
170  eap.replyCustomEapData(result, eapData);
171  console.info('replyCustomEapData success');
172} catch (err) {
173  console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
174}
175```
176
177## eap.startEthEap
178
179startEthEap(netId: number, profile: EthEapProfile): void
180
181该接口用于指定一个以太网卡发起EAP认证。
182
183**需要权限**：ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
184
185**系统能力**：SystemCapability.Communication.NetManager.Eap
186
187**参数：**
188
189| 参数名                            | 类型|必填|说明|
190| ----------------------------- | ---------- |---------- |---------- |
191| netId| number|是|以太网卡Id。|
192| profile|[EthEapProfile](#etheapprofile) |是|EAP配置信息。|
193
194**错误码**：
195
196以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[扩展认证错误码](errorcode-net-eap.md)。
197
198| 错误码ID | 错误信息 |
199| -------- | ---------------------------- |
200|201 | Permission denied.          |
201|33200001 | Invalid netId.          |
202|33200003 | Invalid profile.          |
203|33200009 | netmanager stop.          |
204|33200010 | invalid eth state.          |
205|33200099 | internal error.          |
206
207**示例：**
208
209```js
210import {eap} from '@kit.NetworkKit';
211let netId = 100;
212let profile: eap.EthEapProfile = {
213  eapMethod: eap.EapMethod.EAP_TTLS,
214  phase2Method: eap.Phase2Method.PHASE2_AKA_PRIME,
215  identity: "identity",
216  anonymousIdentity: "anonymousIdentity",
217  password: "password",
218  caCertAliases: "caCertAliases",
219  caPath: "caPath",
220  clientCertAliases: "clientCertAliases",
221  certEntry: new Uint8Array([5,6,7,8,9,10]),
222  certPassword: "certPassword",
223  altSubjectMatch: "altSubjectMatch",
224  domainSuffixMatch: "domainSuffixMatch",
225  realm: "realm",
226  plmn: "plmn",
227  eapSubId: 1
228};
229
230try {
231  eap.startEthEap(netId, profile);
232  console.info('startEthEap success');
233} catch (err) {
234  console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
235}
236```
237
238## eap.logOffEthEap
239
240logOffEthEap(netId: number): void
241
242该接口用于指定一个以太网卡从EAP已认证状态退出。
243
244**需要权限**：ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
245
246**系统能力**：SystemCapability.Communication.NetManager.Eap
247
248**参数：**
249
250| 参数名                            | 类型|必填|说明|
251| ----------------------------- | ---------- |---------- |---------- |
252| netId | number|是|以太网卡Id。|
253
254**错误码**：
255
256以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[扩展认证错误码](errorcode-net-eap.md)。
257
258| 错误码ID | 错误信息 |
259| -------- | ---------------------------- |
260|201 | Permission denied.          |
261|33200001 | Invalid netId.          |
262|33200002 | Log off fail.          |
263|33200009 | netmanager stop.          |
264|33200010 | invalid eth state.          |
265|33200099 | internal error.          |
266
267**示例：**
268
269```js
270import {eap} from '@kit.NetworkKit';
271let netId = 100;
272try{
273  eap.logOffEthEap(netId);
274  console.info("logOffEthEap succes");
275} catch (err) {
276  console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
277}
278```
279
280## EapData
281
282EAP信息。
283
284​**系统能力**​：SystemCapability.Communication.NetManager.Eap
285
286| **名称** | **类型** | **只读** | **可选** | **说明** |
287| -------- | -------- | -------- | -------- | -------- |
288| msgId | number | 否 | 否 | 伪随机数，用于关联处理前后的EAP数据。 |
289| eapBuffer | Uint8Array | 否 | 否 | 从EAP header开始的EAP原始数据，未加密。|
290| bufferLen| number | 否 | 否 | 数据长度。 |
291
292## CustomResult
293
294表示EAP认证处理结果的枚举。
295
296​**系统能力**​：SystemCapability.Communication.NetManager.Eap
297
298| **名称** | **值** | **说明** |
299| -------- | -------- | -------- |
300| RESULT_FAIL | 0 | 认证流程结束，结果失败。 |
301| RESULT_NEXT | 1 | 认证当前流程成功，跳转到下一步。 |
302| RESULT_FINISH | 2 | 认证流程结束，结果成功。 |
303
304## EapMethod
305
306表示EAP认证方式的枚举。
307
308**系统能力：** SystemCapability.Communication.NetManager.Eap
309
310| 名称 | 值 | 说明 |
311| -------- | -------- | -------- |
312| EAP_NONE | 0 | 不指定。 |
313| EAP_PEAP | 1 | PEAP类型。 |
314| EAP_TLS | 2 | TLS类型。 |
315| EAP_TTLS | 3 | TTLS类型。 |
316| EAP_PWD | 4 | PWD类型。 |
317| EAP_SIM | 5 | SIM类型。 |
318| EAP_AKA | 6 | AKA类型。 |
319| EAP_AKA_PRIME | 7 | AKA Prime类型。 |
320| EAP_UNAUTH_TLS | 8 | UNAUTH TLS类型。 |
321
322## Phase2Method
323
324表示第二阶段认证方式的枚举。
325
326**系统能力：** SystemCapability.Communication.NetManager.Eap
327
328| 名称 | 值 | 说明 |
329| -------- | -------- | -------- |
330| PHASE2_NONE | 0 | 不指定。 |
331| PHASE2_PAP | 1 | PAP类型。 |
332| PHASE2_MSCHAP | 2 | MSCHAP类型。 |
333| PHASE2_MSCHAPV2 | 3 | MSCHAPV2类型。 |
334| PHASE2_GTC | 4 | GTC类型。 |
335| PHASE2_SIM | 5 | SIM类型。 |
336| PHASE2_AKA | 6 | AKA类型。 |
337| PHASE2_AKA_PRIME | 7 | AKA Prime类型。 |
338
339## EthEapProfile
340
341可扩展身份验证协议配置信息。
342
343**系统能力：** SystemCapability.Communication.NetManager.Eap
344
345| 名称              | 类型                          | 只读 | 可选 | 说明                             |
346| ----------------- | ----------------------------- | ---- |----| -------------------------------- |
347| eapMethod         | [EapMethod](#eapmethod)      | 否   | 否 | AP认证方式。                     |
348| phase2Method      | [Phase2Method](#phase2method)| 否   | 否 | 第二阶段认证方式。               |
349| identity          | string                        | 否   | 否 | 身份信息。                       |
350| anonymousIdentity | string                        | 否   | 否 | 匿名身份。                       |
351| password          | string                        | 否   | 否 | 密码。                           |
352| caCertAliases     | string                        | 否   | 否 | CA证书别名。                    |
353| caPath            | string                        | 否   | 否 | CA证书路径。                    |
354| clientCertAliases | string                        | 否   | 否 | 客户端证书别名。                 |
355| certEntry         | Uint8Array                    | 否   | 否 | CA证书内容。                    |
356| certPassword      | string                        | 否   | 否 | CA证书密码。                     |
357| altSubjectMatch   | string                        | 否   | 否 | 替代主题匹配。                   |
358| domainSuffixMatch | string                        | 否   | 否 | 域后缀匹配。                     |
359| realm             | string                        | 否   | 否 | 通行证凭证的领域。               |
360| plmn              | string                        | 否   | 否 | 公共陆地移动网的直通凭证提供商。 |
361| eapSubId          | number                        | 否   | 否 | SIM卡的子ID。                    |
362