@ohos.net.eap (Extensible Authentication)
The eap module provides the extensible authentication mechanism to enable third-party clients to access custom 802.1X (a port-based network access control protocol) authentication, such as Extensible Authentication Protocol (EAP) authentication.
NOTE
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.
Module to Import
import {eap} from '@kit.NetworkKit';
eap.regCustomEapHandler
regCustomEapHandler(netType: number, eapCode: number, eapType: number, callback: Callback<EapData>): void
Registers a custom handler of Extensible Authentication Protocol (EAP) packets for extensible authentication. This API returns the result asynchronously through a callback.
The system will encapsulate the eligible EAP packets into the callback function for enterprise applications to retrieve.
Required permissions: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
System capability: SystemCapability.Communication.NetManager.Eap
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| netType | number | Yes | Network type. The value can be 1 or 2. The value 1 indicates WLAN, and the value 2 indicates Ethernet. |
| eapCode | number | Yes | EAP code. The value can be any of the following: code=1 Request, code=2 Response, code=3 Success, code=4 Failure. |
| eapType | number | Yes | EAP method. The value range is [0, 255]. 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. |
| callback | Callback<EapData> | Yes | Callback function, which returns the packet of the specified eapCode+eapType. |
Error codes
For details about the error codes, see Universal Error Codes and Extensible Authentication Error Codes.
| Error Code | Error Message |
|---|---|
| 201 | Permission denied. |
| 33200006 | Invalid net type. |
| 33200007 | Invalid eap code. |
| 33200008 | Invalid eap type. |
| 33200009 | netmanager stop. |
| 33200099 | internal error. |
Example
import {eap} from '@kit.NetworkKit';
let netType = 1;
let eapCode = 1;
let eapType = 25;
let eapData = (eapData:eap.EapData):void => {
console.info("rsp result",JSON.stringify(eapData))
}
try {
eap.regCustomEapHandler(netType, eapCode, eapType, eapData);
console.info('regCustomEapHandler success');
} catch (err) {
console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}
eap.unregCustomEapHandler
unregCustomEapHandler(netType:number, eapCode: number, eapType: number, callback: Callback<EapData>): void
Unregisters the custom handler of EAP packets for extensible authentication. This API returns the result asynchronously through a callback.
Required permissions: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
System capability: SystemCapability.Communication.NetManager.Eap
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| netType | number | Yes | Network type. The value can be 1 or 2. The value 1 indicates WLAN, and the value 2 indicates Ethernet. |
| eapCode | number | Yes | EAP code. The value can be any of the following: code=1 Request, code=2 Response, code=3 Success, code=4 Failure. |
| eapType | number | Yes | EAP method. The value range is [0, 255]. 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. |
| callback | Callback<EapData> | Yes | Callback function, which returns the packet of the specified eapCode+eapType. |
Error codes
For details about the error codes, see Universal Error Codes and Extensible Authentication Error Codes.
| Error Code | Error Message |
|---|---|
| 201 | Permission denied. |
| 33200006 | Invalid net type. |
| 33200007 | Invalid eap code. |
| 33200008 | Invalid eap type. |
| 33200009 | netmanager stop. |
| 33200099 | internal error. |
Example
import {eap} from '@kit.NetworkKit';
let netType = 1;
let eapCode = 1;
let eapType = 25;
let eapData = (eapData:eap.EapData):void => {
console.info("rsp result",JSON.stringify(eapData))
}
try {
eap.unregCustomEapHandler(netType, eapCode, eapType, eapData);
console.info('unregCustomEapHandler success');
} catch (err) {
console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}
eap.replyCustomEapData
replyCustomEapData(result: CustomResult, data: EapData): void
Notifies the system of the extensible authentication result.
NOTE
- 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.
- 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.
Required permissions: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
System capability: SystemCapability.Communication.NetManager.Eap
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| result | CustomResult | Yes | Extensible authentication result. |
| data | EapData | Yes | EAP data. |
Error codes
For details about the error codes, see Universal Error Codes and Extensible Authentication Error Codes.
| Error Code | Error Message |
|---|---|
| 201 | Permission denied. |
| 33200004 | Invalid result. |
| 33200005 | Invalid size of eap data. |
| 33200009 | netmanager stop. |
| 33200099 | internal error. |
import {eap} from '@kit.NetworkKit';
let eapData:eap.EapData= {
msgId: 1,
eapBuffer: new Uint8Array([1, 2, 3, 4, 5]),
bufferLen: 5,
};
let result = 1;
try {
eap.replyCustomEapData(result, eapData);
console.info('replyCustomEapData success');
} catch (err) {
console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}
eap.startEthEap
startEthEap(netId: number, profile: EthEapProfile): void
Starts EAP authentication on an Ethernet NIC.
Required permissions: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
System capability: SystemCapability.Communication.NetManager.Eap
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| netId | number | Yes | ID of the Ethernet NIC. If the default value -1 is specified, the system automatically matches the Ethernet NIC to initiate EAP authentication. |
| profile | EthEapProfile | Yes | EAP profile. |
Error codes
For details about the error codes, see Universal Error Codes and Extensible Authentication Error Codes.
| Error Code | Error Message |
|---|---|
| 201 | Permission denied. |
| 33200001 | Invalid netId. |
| 33200003 | Invalid profile. |
| 33200009 | netmanager stop. |
| 33200010 | invalid eth state. |
| 33200099 | internal error. |
Example
import {eap} from '@kit.NetworkKit';
let netId = 100;
let profile: eap.EthEapProfile = {
eapMethod: eap.EapMethod.EAP_TTLS,
phase2Method: eap.Phase2Method.PHASE2_AKA_PRIME,
identity: "identity",
anonymousIdentity: "anonymousIdentity",
password: "password",
caCertAliases: "caCertAliases",
caPath: "caPath",
clientCertAliases: "clientCertAliases",
certEntry: new Uint8Array([5,6,7,8,9,10]),
certPassword: "certPassword",
altSubjectMatch: "altSubjectMatch",
domainSuffixMatch: "domainSuffixMatch",
realm: "realm",
plmn: "plmn",
eapSubId: 1
};
try {
eap.startEthEap(netId, profile);
console.info('startEthEap success');
} catch (err) {
console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}
eap.logOffEthEap
logOffEthEap(netId: number): void
Revokes the EAP-authenticated state of an Ethernet NIC.
Required permissions: ohos.permission.MANAGE_ENTERPRISE_WIFI_CONNECTION
System capability: SystemCapability.Communication.NetManager.Eap
Parameters
| Name | Type | Mandatory | Description |
|---|---|---|---|
| netId | number | Yes | ID of the Ethernet NIC. If the default value -1 is specified, the system automatically matches the Ethernet NIC to initiate EAP authentication. |
Error codes
For details about the error codes, see Universal Error Codes and Extensible Authentication Error Codes.
| Error Code | Error Message |
|---|---|
| 201 | Permission denied. |
| 33200001 | Invalid netId. |
| 33200002 | Log off fail. |
| 33200009 | netmanager stop. |
| 33200010 | invalid eth state. |
| 33200099 | internal error. |
Example
import {eap} from '@kit.NetworkKit';
let netId = 100;
try{
eap.logOffEthEap(netId);
console.info("logOffEthEap success");
} catch (err) {
console.error('errCode: ' + err.code + ', errMessage: ' + err.message);
}
EapData
Defines the EAP data.
System capability: SystemCapability.Communication.NetManager.Eap
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| msgId | number | No | No | Pseudo random number used to associate the EAP data before and after processing. |
| eapBuffer | Uint8Array | No | No | Raw EAP data starting from the EAP header, which is not encrypted. |
| bufferLen | number | No | No | Data length. |
CustomResult
Enumerates the EAP authentication results.
System capability: SystemCapability.Communication.NetManager.Eap
| Name | Value | Description |
|---|---|---|
| RESULT_FAIL | 0 | The authentication process ends with a failed result. |
| RESULT_NEXT | 1 | The authentication is successful, and the process proceeds to the next step. |
| RESULT_FINISH | 2 | The authentication process ends with a successful result. |
EapMethod
Enumerates the EAP authentication methods.
System capability: SystemCapability.Communication.NetManager.Eap
| Name | Value | Description |
|---|---|---|
| EAP_NONE | 0 | Not specified. |
| EAP_PEAP | 1 | PEAP. |
| EAP_TLS | 2 | TLS. |
| EAP_TTLS | 3 | TTLS. |
| EAP_PWD | 4 | Password. |
| EAP_SIM | 5 | SIM. |
| EAP_AKA | 6 | AKA. |
| EAP_AKA_PRIME | 7 | AKA Prime. |
| EAP_UNAUTH_TLS | 8 | UNAUTH TLS. |
Phase2Method
Enumerates the Phase 2 authentication methods.
System capability: SystemCapability.Communication.NetManager.Eap
| Name | Value | Description |
|---|---|---|
| PHASE2_NONE | 0 | Not specified. |
| PHASE2_PAP | 1 | PAP. |
| PHASE2_MSCHAP | 2 | MS-CHAP. |
| PHASE2_MSCHAPV2 | 3 | MS-CHAPv2. |
| PHASE2_GTC | 4 | GTC. |
| PHASE2_SIM | 5 | SIM. |
| PHASE2_AKA | 6 | AKA. |
| PHASE2_AKA_PRIME | 7 | AKA Prime. |
EthEapProfile
Represents the EAP profile information.
System capability: SystemCapability.Communication.NetManager.Eap
| Name | Type | Read-Only | Optional | Description |
|---|---|---|---|---|
| eapMethod | EapMethod | No | No | EAP authentication method. |
| phase2Method | Phase2Method | No | No | Phase 2 authentication method. |
| identity | string | No | No | Identity information. |
| anonymousIdentity | string | No | No | Anonymous identity. |
| password | string | No | No | Password. |
| caCertAliases | string | No | No | CA certificate alias. |
| caPath | string | No | No | CA certificate path. |
| clientCertAliases | string | No | No | Client certificate alias. |
| certEntry | Uint8Array | No | No | CA certificate content. |
| certPassword | string | No | No | CA certificate password. |
| altSubjectMatch | string | No | No | A string to match the alternate subject. |
| domainSuffixMatch | string | No | No | A string to match the domain suffix. |
| realm | string | No | No | Realm for the passpoint credential. |
| plmn | string | No | No | Public land mobile network (PLMN) of the passpoint credential provider. |
| eapSubId | number | No | No | Sub-ID of the SIM card. |