• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 扩展认证
2
3<!--Kit: Network Kit-->
4<!--Subsystem: Communication-->
5<!--Owner: @foredward-->
6<!--Designer: @h00918518-->
7<!--Tester: @WIFIroam-test-->
8<!--Adviser: @zhang_yixin13-->
9
10## 简介
11
12部分企业用户的PC网络接入认证使用802.1X认证方式，认证客户端由第三方厂商提供。
13
14> **说明：**
15>
16> 扩展认证能力从API version 20开始支持。
17
18认证客户端有以下定制行为：
19
201. 在EAP协议报文内封装私有数据，该私有数据遵循客户端与认证服务器约定的数据结构。
212. 在认证过程中，客户端在本地进行安检扫描等定制动作，定制动作结束后，客户端向接入设备回复认证消息。
22   在这种机制下，需要操作系统提供三方客户端介入802.1X认证流程的机制，支撑客户端的定制认证。
23
24
25为满足以上需求场景，定制化802.1X认证提供如下功能：
26
271. 定制化监听与修改802.1X报文交互流程的能力。
282. 对eth网口发起802.1X认证和去认证的能力。
29
30## 场景介绍
31
32定制化802.1X认证流程的典型场景如下：
33
341. 企业网管应用，需要在企业Wi-Fi的802.1X认证流程中加入自定义的安全校验，来接入企业内网。
35
36   - 支持指定要进行定制化处理的报文类型和EAP类型。
37   - 支持根据自定义的安全校验结果来指定标准认证流程的结果。
38
392. 企业网管应用，需要支持使用eth网口进行802.1X安全认证流程来接入企业内网。
40
41   - 支持标准802.1X认证流程。
42   - 支持定制化802.1X认证流程。
43
44具体开发方式介绍如下。
45
46## 802.1X认证流程中加入自定义的安全校验
47
481. 从@kit.NetworkKit中导入eap命名空间。
49
50   ```ts
51   import {eap} from '@kit.NetworkKit';
52   ```
532. 调用[regCustomEapHandler](../reference/apis-network-kit/js-apis-net-eap.md#eapregcustomeaphandler)方法，注册所需监听的EAP报文类型。在802.1X认证过程中，系统会将符合条件的EAP报文传递至callback函数中，供企业应用获取。
54
55   ```ts
56   import {eap} from '@kit.NetworkKit';
57   let netType = 1;
58   let eapCode = 1;
59   let eapType = 25;
60   let eapData = (eapData:eap.EapData):void => {
61       console.info("rsp result",JSON.stringify(eapData));
62   }
63
64   try {
65       eap.regCustomEapHandler(netType, eapCode, eapType, eapData);
66       console.info('regCustomEapHandler success');
67   } catch (err) {
68       console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
69   }
70   ```
713. 报文传递至callback函数后，802.1X认证流程会阻塞等待, 用户能够获取到完整的报文内容。
724. 若注册的是由服务器发送给客户端的报文类型，则此时可以从报文中看到由服务器加入的自定义内容。应用根据自定义内容，判断认证是否应该继续往后续步骤进行，并调用[replyCustomEapData](../reference/apis-network-kit/js-apis-net-eap.md#eapreplycustomeapdata)方法通知系统。
73
74   ```ts
75    import {eap} from '@kit.NetworkKit';
76    let netType = 1;
77    let eapCode= 1; // eap request
78    let eapType= 25; // EAP_PEAP
79    let result = 1;
80    let eapData = (eapData:eap.EapData):void => {
81        try{
82        eap.replyCustomEapData(result, eapData);
83        console.info('replyCustomEapData success');
84        } catch (err) {
85        console.error('errCode: ' + err.code + ' , errMessage: ' + err.message);
86        }
87    }
88
89   try{
90       eap.regCustomEapHandler(netType, eapCode, eapType, eapData);
91   	   console.info('regCustomEapHandler success');
92   } catch (err) {
93       console.error('errCode: ' + err.code + 'errMessage: ' + err.message);
94   }
95   ```
965. 若注册的报文类型是由客户端发给服务器的，则此时获取到的是原始的802.1X认证报文，应用需要在原始报文内容中加入自己的自定义内容，并将加入自定义内容后的报文内容调用[replyCustomEapData](../reference/apis-network-kit/js-apis-net-eap.md#eapreplycustomeapdata)方法通知系统。
97
98   ```ts
99   import {eap} from '@kit.NetworkKit';
100   let netType = 1;
101   let eapCode= 2; // eap response
102   let eapType= 25; // EAP_PEAP
103   let result = 1;
104   let eapData = (eapData:eap.EapData):void => {
105        try{
106            eap.replyCustomEapData(result, eapData);
107            console.info('replyCustomEapData success');
108        } catch (err) {
109            console.error('errCode: ' + err.code + ' , errMessage: ' + err.message);
110        }
111   }
112
113   try{
114       eap.regCustomEapHandler(netType, eapCode, eapType, eapData);
115       console.info('regCustomEapHandler success');
116   } catch (err) {
117       console.error('errCode: ' + err.code + 'errMessage: ' + err.message);
118   }
119   ```
1206. 如此便从发送/接收两个方向上实现了对标准802.1X流程的定制化。需要取消定制化时，调用[unregCustomEapHandler](../reference/apis-network-kit/js-apis-net-eap.md#eapunregcustomeaphandler)方法。
121
122   ```ts
123   import {eap} from '@kit.NetworkKit';
124   let netType = 1;
125   let eapCode = 1;
126   let eapType = 25;
127   let eapData = (eapData:eap.EapData):void => {
128       console.info("rsp result",JSON.stringify(eapData));
129   }
130
131   try {
132       eap.unregCustomEapHandler(netType, eapCode, eapType, eapData);
133       console.info('unregCustomEapHandler success');
134   } catch (err) {
135       console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
136   }
137
138   ```
139
140## 使用eth接口发起802.1X认证流程
141
1421. 设备通过硬件接口，插入网线。
1432. 从@kit.NetworkKit中导入eap命名空间。
144
145   ```ts
146   import {eap} from '@kit.NetworkKit';
147   ```
1483. 当企业管理软件需要进行认证，调用[startEthEap](../reference/apis-network-kit/js-apis-net-eap.md#eapstartetheap)方法时，会发起802.1X认证流程。
149
150   ```ts
151   import {eap} from '@kit.NetworkKit';
152   let netId = 100;
153   let profile: eap.EthEapProfile = {
154       eapMethod: eap.EapMethod.EAP_TTLS,
155       phase2Method: eap.Phase2Method.PHASE2_AKA_PRIME,
156       identity: "identity",
157    	   anonymousIdentity: "anonymousIdentity",
158    	   password: "password",
159    	   caCertAliases: "caCertAliases",
160    	   caPath: "caPath",
161    	   clientCertAliases: "clientCertAliases",
162    	   certEntry: new Uint8Array([5,6,7,8,9,10]),
163    	   certPassword: "certPassword",
164    	   altSubjectMatch: "altSubjectMatch",
165    	   domainSuffixMatch: "domainSuffixMatch",
166    	   realm: "realm",
167    	   plmn: "plmn",
168    	   eapSubId: 1
169   };
170
171   try {
172    	   eap.startEthEap(netId, profile);
173    	   console.info('startEthEap success');
174   } catch (err) {
175   	    console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
176   }
177   ```
1784. 当企业管理软件需要退出认证状态，调用[logOffEthEap](../reference/apis-network-kit/js-apis-net-eap.md#eaplogoffetheap)方法，即会发起802.1X去认证流程。
179
180   ```ts
181   import {eap} from '@kit.NetworkKit';
182   let netId = 100;
183   try{
184     	   eap.logOffEthEap(netId);
185     	   console.error("logOffEthEap success");
186   } catch (err) {
187          console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
188   }
189   ```