• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# @ohos.net.eap (Extensible Authentication)
2
3<!--Kit: Network Kit-->
4<!--Subsystem: Communication-->
5<!--Owner: @foredward-->
6<!--Designer: @h00918518-->
7<!--Tester: @WIFIroam-test-->
8<!--Adviser: @zhang_yixin13-->
9
10The **eap** module provides the extensible authentication mechanism to enable third-party clients to participate in custom 802.1X (a port-based network access control protocol) authentication, such as Extensible Authentication Protocol (EAP) authentication.
11
12> **NOTE**
13>
14> The initial APIs of this module are supported since API version 20. Newly added APIs will be marked with a superscript to indicate their earliest API version.
15
16## Module to Import
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
26Registers a custom handler of Extensible Authentication Protocol (EAP) packets for extensible authentication. This API returns the result asynchronously through a callback.
27
28The system will encapsulate the eligible EAP packets into the callback function for enterprise applications to retrieve.
29
30**Required permissions**: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
31
32**System capability**: SystemCapability.Communication.NetManager.Eap
33
34**Parameters**
35
36| Name                             | Type|Mandatory|Description|
37| ----------------------------- | ---------- |---------- |---------- |
38| netType| number|Yes|Network type. The value can be **1** or **2**.<br>The value **1** indicates WLAN, and the value **2** indicates Ethernet.|
39| eapCode|number |Yes|EAP code. The value can be any of the following:<br>code=1 Request, code=2 Response, code=3 Success, code=4 Failure.|
40| eapType| number |Yes|EAP method. The value range is [0, 255].<br>Common values include the following: 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, and eapType=255 Experimental use.|
41| callback| Callback\<[EapData](#eapdata)\> |Yes|Callback used to process EAP packets with the specified code and type.|
42
43**Error codes**
44
45For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Extensible Authentication Error Codes](errorcode-net-eap.md).
46
47| Error Code| Error Message|
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**Example**
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
79Unregisters the custom handler of EAP packets for extensible authentication. This API returns the result asynchronously through a callback.
80
81**Required permissions**: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
82
83**System capability**: SystemCapability.Communication.NetManager.Eap
84
85**Parameters**
86
87| Name                           | Type|Mandatory|Description|
88| ----------------------------- | ---------- |---------- |---------- |
89| netType| number|Yes|Network type. The value can be **1** or **2**.<br>The value **1** indicates WLAN, and the value **2** indicates Ethernet.|
90| eapCode|number |Yes|EAP code. The value can be any of the following:<br>code=1 Request, code=2 Response, code=3 Success, code=4 Failure.|
91| eapType| number |Yes|EAP method. The value range is [0, 255].<br>Common values include the following: 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, and eapType=255 Experimental use.|
92| callback| Callback\<[EapData](#eapdata)\> |Yes|Callback used to process EAP packets with the specified code and type.|
93
94**Error codes**
95
96For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Extensible Authentication Error Codes](errorcode-net-eap.md).
97
98| Error Code| Error Message|
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**Example**
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
130Notifies the system of the extensible authentication result.
131
132 > **NOTE**
133 >
134 >- If this callback is used to process received EAP data packets, the customized portion added by the server must be removed from the EAP data transmitted to the system.
135 >- If this callback is used to process sent EAP data packets, the EAP data transmitted to the system is the EAP data with the customized portion added by the server.
136
137**Required permissions**: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
138
139**System capability**: SystemCapability.Communication.NetManager.Eap
140
141**Parameters**
142
143| Name                           | Type|Mandatory|Description|
144| ----------------------------- | ---------- |---------- |---------- |
145| result | [CustomResult](#customresult)|Yes|Extensible authentication result.|
146| data | [EapData](#eapdata) |Yes|EAP data.|
147
148**Error codes**
149
150For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Extensible Authentication Error Codes](errorcode-net-eap.md).
151
152| Error Code| Error Message|
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
181Starts EAP authentication on an Ethernet NIC.
182
183**Required permissions**: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
184
185**System capability**: SystemCapability.Communication.NetManager.Eap
186
187**Parameters**
188
189| Name                           | Type|Mandatory|Description|
190| ----------------------------- | ---------- |---------- |---------- |
191| netId| number|Yes|ID of the Ethernet NIC.|
192| profile|[EthEapProfile](#etheapprofile) |Yes|EAP profile.|
193
194**Error codes**
195
196For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Extensible Authentication Error Codes](errorcode-net-eap.md).
197
198| Error Code| Error Message|
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**Example**
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
242Revokes the EAP-authenticated state of an Ethernet NIC.
243
244**Required permissions**: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
245
246**System capability**: SystemCapability.Communication.NetManager.Eap
247
248**Parameters**
249
250| Name                           | Type|Mandatory|Description|
251| ----------------------------- | ---------- |---------- |---------- |
252| netId | number|Yes|ID of the Ethernet NIC.|
253
254**Error codes**
255
256For details about the error codes, see [Universal Error Codes](../errorcode-universal.md) and [Extensible Authentication Error Codes](errorcode-net-eap.md).
257
258| Error Code| Error Message|
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**Example**
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
282Defines the EAP data.
283
284​**System capability**: SystemCapability.Communication.NetManager.Eap
285
286| **Name**| **Type**| **Read-Only**| **Optional**| **Description**|
287| -------- | -------- | -------- | -------- | -------- |
288| msgId | number | No| No| Pseudo random number used to associate the EAP data before and after processing.|
289| eapBuffer | Uint8Array | No| No| Raw EAP data starting from the EAP header, which is not encrypted.|
290| bufferLen| number | No| No| Data length.|
291
292## CustomResult
293
294Enumerates the EAP authentication results.
295
296​**System capability**: SystemCapability.Communication.NetManager.Eap
297
298| **Name**| **Value**| **Description**|
299| -------- | -------- | -------- |
300| RESULT_FAIL | 0 | The authentication process ends with a failed result.|
301| RESULT_NEXT | 1 | The authentication is successful, and the process proceeds to the next step.|
302| RESULT_FINISH | 2 | The authentication process ends with a successful result.|
303
304## EapMethod
305
306Enumerates the EAP authentication methods.
307
308**System capability**: SystemCapability.Communication.NetManager.Eap
309
310| Name| Value| Description|
311| -------- | -------- | -------- |
312| EAP_NONE | 0 | Not specified.|
313| EAP_PEAP | 1 | PEAP.|
314| EAP_TLS | 2 | TLS.|
315| EAP_TTLS | 3 | TTLS.|
316| EAP_PWD | 4 | Password.|
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
324Enumerates the Phase 2 authentication methods.
325
326**System capability**: SystemCapability.Communication.NetManager.Eap
327
328| Name| Value| Description|
329| -------- | -------- | -------- |
330| PHASE2_NONE | 0 | Not specified.|
331| PHASE2_PAP | 1 | PAP.|
332| PHASE2_MSCHAP | 2 | MS-CHAP.|
333| PHASE2_MSCHAPV2 | 3 | MS-CHAPv2.|
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
341Represents the EAP profile information.
342
343**System capability**: SystemCapability.Communication.NetManager.Eap
344
345| Name             | Type                         | Read-Only| Optional| Description                            |
346| ----------------- | ----------------------------- | ---- |----| -------------------------------- |
347| eapMethod         | [EapMethod](#eapmethod)      | No  | No| EAP authentication method.                    |
348| phase2Method      | [Phase2Method](#phase2method)| No  | No| Phase 2 authentication method.              |
349| identity          | string                        | No  | No| Identity information.                      |
350| anonymousIdentity | string                        | No  | No| Anonymous identity.                      |
351| password          | string                        | No  | No| Password.                          |
352| caCertAliases     | string                        | No  | No| CA certificate alias.                   |
353| caPath            | string                        | No  | No| CA certificate path.                   |
354| clientCertAliases | string                        | No  | No| Client certificate alias.                |
355| certEntry         | Uint8Array                    | No  | No| CA certificate content.                   |
356| certPassword      | string                        | No  | No| CA certificate password.                    |
357| altSubjectMatch   | string                        | No  | No| A string to match the alternate subject.                  |
358| domainSuffixMatch | string                        | No  | No| A string to match the domain suffix.                    |
359| realm             | string                        | No  | No| Realm for the passpoint credential.              |
360| plmn              | string                        | No  | No| Public land mobile network (PLMN) of the passpoint credential provider.|
361| eapSubId          | number                        | No  | No| Sub-ID of the SIM card.                   |
362