2876 .. _network-protocols-vlan-eap-wi-fi-and-supplicant:
27. Network Protocols — VLAN, EAP, Wi-Fi and Supplicant¶
27.1. VLAN Configuration Protocol¶
27.1.1. EFI_VLAN_CONFIG_PROTOCOL¶
Summary
This protocol is to provide manageability interface for VLAN configuration.
GUID
#define EFI_VLAN_CONFIG_PROTOCOL_GUID \
{0x9e23d768, 0xd2f3, 0x4366, \
{0x9f, 0xc3, 0x3a, 0x7a, 0xba, 0x86, 0x43, 0x74}}
Protocol Interface Structure
typedef struct _EFI_VLAN_CONFIG_PROTOCOL {
EFI_VLAN_CONFIG_SET Set;
EFI_VLAN_CONFIG_FIND Find;
EFI_VLAN_CONFIG_REMOVE Remove;
} EFI_VLAN_CONFIG_PROTOCOL;
Parameters
- Set
Create new VLAN device or modify configuration parameter of an already-configured VLAN
- Find
Find configuration information for specified VLAN or all configured VLANs.
- Remove
Remove a VLAN device.
Description
This protocol is to provide manageability interface for VLAN setting. The intended VLAN tagging implementation is IEEE802.1Q.
27.1.2. EFI_VLAN_CONFIG_PROTOCOL.Set()¶
Summary
Create a VLAN device or modify the configuration parameter of an already-configured VLAN
Prototype
typedef
EFI_STATUS
(EFIAPI * EFI_VLAN_CONFIG_SET) (
IN EFI_VLAN_CONFIG_PROTOCOL *This,
IN UINT16 VlanId,
IN UINT8 Priority
);
Parameters
- This
Pointer to EFI_VLAN_CONFIG_PROTOCOL instance.
- VlanId
A unique identifier (1-4094) of the VLAN which is being created or modified, or zero (0).
- Priority
3 bit priority in VLAN header. Priority 0 is default value. If VlanId is zero (0), Priority is ignored.
Description
The Set() function is used to create a new VLAN device or change the VLAN configuration parameters. If the VlanId hasn’t been configured in the physical Ethernet device, a new VLAN device will be created. If a VLAN with this VlanId is already configured, then related configuration will be updated as the input parameters.
If VlanId is zero, the VLAN device will send and receive untagged frames. Otherwise, the VLAN device will send and receive VLAN-tagged frames containing the VlanId.
If VlanId is out of scope of (0-4094), EFI_INVALID_PARAMETER is returned
If Priority is out of the scope of (0-7), then EFI_INVALID_PARAMETER is returned.
If there is not enough system memory to perform the registration, then EFI_OUT_OF_RESOURCES is returned.
Status Codes Returned
EFI_SUCCESS |
The VLAN is successfully configured |
EFI_INVALID_PARAMETER |
One or more of following conditions is TRUE
• This is NULL
• VlanId is an invalid VLAN Identifier
• Priority is invalid
|
EFI_OUT_OF_RESOURCES |
There is not enough system memory to perform the registration. |
27.1.3. EFI_VLAN_CONFIG_PROTOCOL.Find()¶
Summary
Find configuration information for specified VLAN or all configured VLANs.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_VLAN_CONFIG_FIND) (
IN EFI_VLAN_CONFIG_PROTOCOL *This,
IN UINT16 *VlanId, OPTIONAL
OUT UINT16 *NumberOfVlan,
OUT EFI_VLAN_FIND_DATA **Entries
);
Parameters
- This
Pointer to EFI_VLAN_CONFIG_PROTOCOL instance.
- VlanId
Pointer to VLAN identifier. Set to NULL to find all configured VLANs
- NumberOfVlan
The number of VLANs which is found by the specified criteria
- Entries
The buffer which receive the VLAN configuration. Type EFI_VLAN_FIND_DATA is defined below.
Description
The Find() function is used to find the configuration information for matching VLAN and allocate a buffer into which those entries are copied.
Related Definitions
//**********************************************
// EFI_VLAN_FIND_DATA
//**********************************************
typedef struct {
UINT16 VlanId;
UINT8 Priority;
} EFI_VLAN_FIND_DATA;
- VlanId
Vlan Identifier
- Priority
Priority of this VLAN
Status Codes Returned
EFI_SUCCESS |
The VLAN is successfully found |
EFI_INVALID_PARAMETER |
One or more of following conditions is TRUE
• This is NULL
• Specified VlanId is invalid
|
EFI_NOT_FOUND |
No matching VLAN is found |
27.1.4. EFI_VLAN_CONFIG_PROTOCOL.Remove()¶
Summary
Remove the configured VLAN device
Prototype
typedef
EFI_STATUS
(EFIAPI * EFI_VLAN_CONFIG_REMOVE) (
IN EFI_VLAN_CONFIG_PROTOCOL *This,
IN UINT16 VlanId
);
Parameters
- This
Pointer to EFI_VLAN_CONFIG_PROTOCOL instance.
- VlanId
Identifier (0-4094) of the VLAN to be removed.
Description
The Remove() function is used to remove the specified VLAN device. If the VlanId is out of the scope of (0-4094), EFI_INVALID_PARAMETER is returned. If specified VLAN hasn’t been previously configured, EFI_NOT_FOUND is returned.
Status Codes Returned
EFI_SUCCESS |
The VLAN is successfully removed |
EFI_INVALID_PARAMETER |
One or more of following conditions is TRUE
• This is NULL
• VlanId is an invalid parameter.
|
EFI_NOT_FOUND |
The to-be-removed VLAN does not exist |
27.2. EAP Protocol¶
This section defines the EAP protocol. This protocol is designed to make the EAP framework configurable and extensible. It is intended for the supplicant side.
27.2.1. EFI_EAP_PROTOCOL¶
Summary
This protocol is used to abstract the ability to configure and extend the EAP framework.
GUID
#define EFI_EAP_PROTOCOL_GUID \
{ 0x5d9f96db, 0xe731, 0x4caa,\
{0xa0, 0x0d, 0x72, 0xe1, 0x87, 0xcd, 0x77, 0x62 }}
Protocol Interface Structure
typedef struct _EFI_EAP_PROTOCOL {
EFI_EAP_SET_DESIRED_AUTHENTICATION_METHOD SetDesiredAuthMethod;
EFI_EAP_REGISTER_AUTHENTICATION_METHOD RegisterAuthMethod;
} EFI_EAP_PROTOCOL;
Parameters
- SetDesiredAuthMethod
Set the desired EAP authentication method for the Port. See the SetDesiredAuthMethod() function description.
- RegisterAuthMethod
Register an EAP authentication method. See the RegisterAuthMethod() function description.
Description
EFI_EAP_PROTOCOL is used to configure the desired EAP authentication method for the EAP framework and extend the EAP framework by registering new EAP authentication method on a Port. The EAP framework is built on a per-Port basis. Herein, a Port means a NIC. For the details of EAP protocol, please refer to RFC 2284.
Related Definitions
//
// Type for the identification number assigned to the Port by the
// System in which the Port resides.
//
typedef VOID * EFI_PORT_HANDLE;
27.2.2. EFI_EAP.SetDesiredAuthMethod()¶
Summary
Set the desired EAP authentication method for the Port.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_SET_DESIRED_AUTHENTICATION_METHOD) (
IN struct _EFI_EAP_PROTOCOL *This,
IN UINT8 EapAuthType
);
Parameters
- This
A pointer to the EFI_EAP_PROTOCOL instance that indicates the calling context. Type EFI_EAP_PROTOCOL is defined in Section 1.1.
- EapAuthType
The type of the desired EAP authentication method for the Port. It should be the type value defined by RFC. See RFC 2284 for details. Current valid values are defined in “Related Definitions”.
Related Definitions
//
// EAP Authentication Method Type (RFC 3748)
//
#define EFI_EAP_TYPE_TLS 13 /* REQUIRED - RFC 5216 */
Description
The SetDesiredAuthMethod() function sets the desired EAP authentication method indicated by EapAuthType for the Port.
If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is returned.
If the EAP authentication method of EapAuthType is unsupported, then it will return EFI_UNSUPPORTED.
The cryptographic strength of EFI_EAP_TYPE_TLS shall be at least of hash strength SHA-256 and RSA key length of at least 2048 bits.
Status Codes Returned
EFI_SUCCESS |
The desired EAP authentication method is set successfully. |
EFI_INVALID_PARAMETER |
EapAuthType is an invalid EAP authentication type. |
EFI_UNSUPPORTED |
The EAP authentication method of EapAuthType is unsupported by the Port. |
27.2.3. EFI_EAP.RegisterAuthMethod()¶
Summary
Register an EAP authentication method.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_REGISTER_AUTHENTICATION_METHOD) (
IN struct _EFI_EAP_PROTOCOL *This,
IN UINT8 EapAuthType,
IN EFI_EAP_BUILD_RESPONSE_PACKET Handler
);
Parameters
- This
A pointer to the EFI_EAP_PROTOCOL instance that indicates the calling context. Type EFI_EAP_PROTOCOL is defined in Section 1.1.
- EapAuthType
The type of the EAP authentication method to register. It should be the type value defined by RFC. See RFC 2284 for details. Current valid values are defined in the SetDesiredAuthMethod() function description.
- Handler
The handler of the EAP authentication method to register. Type EFI_EAP_BUILD_RESPONSE_PACKET is defined in “Related Definitions”.
Related Definitions
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_BUILD_RESPONSE_PACKET) (
IN EFI_PORT_HANDLE PortNumber
IN UINT8 *RequestBuffer,
IN UINTN RequestSize,
IN UINT8 *Buffer,
IN OUT UINTN *BufferSize
);
- Routine Description:
Build EAP response packet in response to the EAP request packet specified by (RequestBuffer, RequestSize).
- Arguments
- PortNumber — Specified the Port where the EAP request packet comes.RequestBuffer — Pointer to the most recently received EAP-Request packet.RequestSize — Packet size in bytes for the most recently received EAP-Request packet.Buffer — Pointer to the buffer to hold the built packet.BufferSize — Pointer to the buffer size in bytes. On input, it is thebuffer size provided by the caller. On output, it is the buffer sizein fact needed to contain the packet.
- Returns:
EFI_SUCCESS — The required EAP response packet is built successfully. Others — Failures are encountered during the packet building process.
Description
The RegisterAuthMethod() function registers the user provided EAP authentication method, the type of which is EapAuthType and the handler of which is Handler.
If EapAuthType is an invalid EAP authentication type, then EFI_INVALID_PARAMETER is returned.
If there is not enough system memory to perform the registration, then EFI_OUT_OF_RESOURCES is returned.
Status Codes Returned
EFI_SUCCESS |
The EAP authentication method of EapAuthType is registered successfully. |
EFI_INVALID_PARAMETER |
EapAuthType is an invalid EAP authentication type. |
EFI_OUT_OF_RESOURCES |
There is not enough system memory to perform the registration. |
27.2.4. EAPManagement Protocol¶
This section defines the EAP management protocol. This protocol is designed to provide ease of management and ease of test for EAPOL state machine. It is intended for the supplicant side. It conforms to IEEE 802.1x specification.
27.2.5. EFI_EAP_MANAGEMENT_PROTOCOL¶
Summary
This protocol provides the ability to configure and control EAPOL state machine, and retrieve the status and the statistics information of EAPOL state machine.
GUID
#define EFI_EAP_MANAGEMENT_PROTOCOL_GUID \
{ 0xbb62e663, 0x625d, 0x40b2, \
{ 0xa0, 0x88, 0xbb, 0xe8, 0x36, 0x23, 0xa2, 0x45 }
Protocol Interface Structure
typedef struct _EFI_EAP_MANAGEMENT_PROTOCOL {
EFI_EAP_GET_SYSTEM_CONFIGURATION GetSystemConfiguration;
EFI_EAP_SET_SYSTEM_CONFIGURATION SetSystemConfiguration;
EFI_EAP_INITIALIZE_PORT InitializePort;
EFI_EAP_USER_LOGON UserLogon;
EFI_EAP_USER_LOGOFF UserLogoff;
EFI_EAP_GET_SUPPLICANT_STATUS GetSupplicantStatus;
EFI_EAP_SET_SUPPLICANT_CONFIGURATION SetSupplicantConfiguration;
EFI_EAP_GET_SUPPLICANT_STATISTICS GetSupplicantStatistics;
} EFI_EAP_MANAGEMENT_PROTOCOL;
Parameters
- GetSystemConfiguration
Read the system configuration information associated with the Port. See the GetSystemConfiguration() function description.
- SetSystemConfiguration
Set the system configuration information associated with the Port. See the SetSystemConfiguration() function description.
- InitializePort
Cause the EAPOL state machines for the Port to be initialized. See the InitializePort() function description.
- UserLogon
Notify the EAPOL state machines for the Port that the user of the System has logged on. See the UserLogon() function description.
- UserLogoff
Notify the EAPOL state machines for the Port that the user of the System has logged off. See the UserLogoff() function description.
- GetSupplicantStatus
Read the status of the Supplicant PAE state machine for the Port, including the current state and the configuration of the operational parameters. See the GetSupplicantStatus() function description.
- SetSupplicantConfiguration
Set the configuration of the operational parameter of the Supplicant PAE state machine for the Port. See the SetSupplicantConfiguration() function description.
- GetSupplicantStatistics
Read the statistical information regarding the operation of the Supplicant associated with the Port. See the GetSupplicantStatistics() function description.
Description
The EFI_EAP_MANAGEMENT protocol is used to control, configure and monitor EAPOL state machine on a Port. EAPOL state machine is built on a per-Port basis. Herein, a Port means a NIC. For the details of EAPOL, please refer to IEEE 802.1x specification.
27.2.6. EFI_EAP_MANAGEMENT.GetSystemConfiguration()¶
Summary
Read the system configuration information associated with the Port.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_GET_SYSTEM_CONFIGURATION) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
OUT BOOLEAN *SystemAuthControl,
OUT EFI_EAPOL_PORT_INFO *PortInfo OPTIONAL
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
- SystemAuthControl
Returns the value of the SystemAuthControl parameter of the System. TRUE means Enabled. FALSE means Disabled.
- PortInfo
Returns EFI_EAPOL_PORT_INFO structure to describe the Port’s information. This parameter can be NULL to ignore reading the Port’s information. Type EFI_EAPOL_PORT_INFO is defined in “Related Definitions”.
Related Definitions
//
// PAE Capabilities
//
#define PAE_SUPPORT_AUTHENTICATOR 0x01
#define PAE_SUPPORT_SUPPLICANT 0x02
typedef struct _EFI_EAPOL_PORT_INFO {
EFI_PORT_HANDLE PortNumber;
UINT8 ProtocolVersion;
UINT8 PaeCapabilities;
} EFI_EAPOL_PORT_INFO;
- PortNumber
The identification number assigned to the Port by the System in which the Port resides.
- ProtocolVersion
The protocol version number of the EAPOL implementation supported by the Port.
- PaeCapabilities
The capabilities of the PAE associated with the Port. This field indicates whether Authenticator functionality, Supplicant functionality, both, or neither, is supported by the Port’s PAE.
Description
The GetSystemConfiguration() function reads the system configuration information associated with the Port, including the value of the SystemAuthControl parameter of the System is returned in SystemAuthControl and the Port’s information is returned in the buffer pointed to by PortInfo. The Port’s information is optional. If P ortInfo is NULL, then reading the Port’s information is ignored.
If SystemAuthControl is NULL, then EFI_INVALID_PARAMETER is returned.
Status Codes Returned
EFI_SUCCESS |
The system configuration information of the Port is read successfully. |
EFI_INVALID_PARAMETER |
SystemAuthControl is NULL. |
27.2.7. EFI_EAP_MANAGEMENT.SetSystemConfiguration()¶
Summary
Set the system configuration information associated with the Port.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_SET_SYSTEM_CONFIGURATION) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
IN BOOLEAN SystemAuthControl
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
- SystemAuthControl
The desired value of the SystemAuthControl parameter of the System. TRUE means Enabled. FALSE means Disabled.
Description
The SetSystemConfiguration() function sets the value of the SystemAuthControl parameter of the System to SystemAuthControl.
Status Codes Returned
EFI_SUCCESS |
The system configuration information of the Port is set successfully. |
27.2.8. EFI_EAP_MANAGEMENT.InitializePort()¶
Summary
Cause the EAPOL state machines for the Port to be initialized.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_INITIALIZE_PORT) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
Description
The InitializePort() function causes the EAPOL state machines for the Port.
Status Codes Returned
EFI_SUCCESS |
The Port is initialized successfully. |
27.2.9. EFI_EAP_MANAGEMENT.UserLogon()¶
Summary
Notify the EAPOL state machines for the Port that the user of the System has logged on.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_USER_LOGON) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
);
Parameters
- This
A pointer to the E FI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
Description
The UserLogon() function notifies the EAPOL state machines for the Port.
Status Codes Returned
EFI_SUCCESS |
The Port is notified successfully. |
27.2.10. EFI_EAP_MANAGEMENT.UserLogoff()¶
Summary
Notify the EAPOL state machines for the Port that the user of the System has logged off.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_USER_LOGOFF) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
Description
The UserLogoff() function notifies the EAPOL state machines for the Port.
Status Codes Returned
EFI_SUCCESS |
The Port is notified successfully. |
27.2.11. EFI_EAP_MANAGEMENT.GetSupplicantStatus()¶
Summary
Read the status of the Supplicant PAE state machine for the Port, including the current state and the configuration of the operational parameters.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_GET_SUPPLICANT_STATUS) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
OUT EFI_EAPOL_SUPPLICANT_PAE_STATE *CurrentState,
IN OUT EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION *Configuration OPTIONAL
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
- CurrentState
Returns the current state of the Supplicant PAE state machine for the Port. Type EFI_EAPOL_SUPPLICANT_PAE_STATE is defined in “Related Definitions”.
- Configuration
Returns the configuration of the operational parameters of the Supplicant PAE state machine for the Port as required. This parameter can be NULL to ignore reading the configuration. On input, Configuration. ValidFieldMask specifies the operational parameters to be read. On output, Configuration returns the configuration of the required operational parameters. Type EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION is defined in “Related Definitions”.
Related Definitions
//
// Supplicant PAE state machine (IEEE Std 802.1X Section 8.5.10)
//
typedef enum _EFI_EAPOL_SUPPLICANT_PAE_STATE {
Logoff,
Disconnected,
Connecting,
Acquired,
Authenticating,
Held,
Authenticated,
MaxSupplicantPaeState
} EFI_EAPOL_SUPPLICANT_PAE_STATE;
//
// Definitions for ValidFieldMask
//
#define AUTH_PERIOD_FIELD_VALID 0x01
#define HELD_PERIOD_FIELD_VALID 0x02
#define START_PERIOD_FIELD_VALID 0x04
#define MAX_START_FIELD_VALID 0x08
typedef struct _EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION {
UINT8 ValidFieldMask;
UINTN AuthPeriod;
UINTN HeldPeriod;
UINTN StartPeriod;
UINTN MaxStart;
} EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION;
- ValidFieldMask
Indicates which of the following fields are valid.
- AuthPeriod
The initial value for the authWhile timer. Its default value is 30 s.
- HeldPeriod
The initial value for the heldWhile timer. Its default value is 60 s.
- StartPeriod
The initial value for the startWhen timer. Its default value is 30 s.
- MaxStart
The maximum number of successive EAPOL-Start messages will be sent before the Supplicant assumes that there is no Authenticator present. Its default value is 3.
Description
The GetSupplicantStatus() function reads the status of the Supplicant PAE state machine for the Port, including the current state CurrentState and the configuration of the operational parameters Configuration. The configuration of the operational parameters is optional. If Configuration is NULL, then reading the configuration is ignored. The operational parameters in Configuration to be read can also be specified by Configuration. ValidFieldMask.
If CurrentState is NULL, then EFI_INVALID_PARAMETER is returned.
Status Codes Returned
EFI_SUCCESS |
The status of the Supplicant PAE state machine for the Port is read successfully. |
EFI_INVALID_PARAMETER |
CurrentState is NULL. |
27.2.12. EFI_EAP_MANAGEMENT.SetSupplicantConfiguration()¶
Summary
Set the configuration of the operational parameter of the Supplicant PAE state machine for the Port.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_SET_SUPPLICANT_CONFIGURATION) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
IN EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION *Configuration
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
- Configuration
The desired configuration of the operational parameters of the Supplicant PAE state machine for the Port as required. Type EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION is defined in the GetSupplicantStatus() function description.
Description
The SetSupplicantConfiguration() function sets the configuration of the operational parameter of the Supplicant PAE state machine for the Port to Configuration. The operational parameters in Configuration to be set can be specified by Configuration.ValidFieldMask.
If Configuration is NULL, then EFI_INVALID_PARAMETER is returned.
Status Codes Returned
EFI_SUCCESS |
The configuration of the operational parameter of the Supplicant PAE state machine for the Port is set successfully. |
EFI_INVALID_PARAMETER |
Configuration is NULL. |
27.2.13. EFI_EAP_MANAGEMENT.GetSupplicantStatistics()¶
Summary
Read the statistical information regarding the operation of the Supplicant associated with the Port.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_GET_SUPPLICANT_STATISTICS) (
IN struct _EFI_EAP_MANAGEMENT_PROTOCOL *This,
OUT EFI_EAPOL_SUPPLICANT_PAE_STATISTICS *Statistics
);
Parameters
- This
A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL instance that indicates the calling context. Type EFI_EAP_MANAGEMENT_PROTOCOL is defined in EAPManagement Protocol .
- Statistics
Returns the statistical information regarding the operation of the Supplicant for the Port. Type EFI_EAPOL_SUPPLICANT_PAE_STATISTICS is defined in “Related Definitions”.
Related Definitions
//
// Supplicant Statistics (IEEE Std 802.1X Section 9.5.2)
//
typedef struct _EFI_EAPOL_SUPPLICANT_PAE_STATISTICS {
UINTN EapolFramesReceived;
UINTN EapolFramesTransmitted;
UINTN EapolStartFramesTransmitted;
UINTN EapolLogoffFramesTransmitted;
UINTN EapRespIdFramesTransmitted;
UINTN EapResponseFramesTransmitted;
UINTN EapReqIdFramesReceived;
UINTN EapRequestFramesReceived;
UINTN InvalidEapolFramesReceived;
UINTN EapLengthErrorFramesReceived;
UINTN LastEapolFrameVersion;
UINTN LastEapolFrameSource;
} EFI_EAPOL_SUPPLICANT_PAE_STATISTICS;
- EapolFramesReceived
The number of EAPOL frames of any type that have been received by this Supplicant.
- EapolFramesTransmitted
The number of EAPOL frames of any type that have been transmitted by this Supplicant.
- EapolStartFramesTransmitted
The number of EAPOL Start frames that have been transmitted by this Supplicant.
- EapolLogoffFramesTransmitted
The number of EAPOL Logoff frames that have been transmitted bythis Supplicant.
- EapRespIdFramesTransmitted
The number of EAP Resp/Id frames that have been transmitted by this Supplicant.
- EapResponseFramesTransmitted
The number of valid EAP Response frames (other than Resp/Id frames) that have been transmitted by this Supplicant.
- EapReqIdFramesReceived
The number of EAP Req/Id frames that have been received by this Supplicant.
- EapRequestFramesReceived
The number of EAP Request frames (other than Rq/Id frames) that have been received by this Supplicant.
- InvalidEapolFramesReceived
The number of EAPOL frames that have been received by this Supplicant in which the frame type is not recognized.
- EapLengthErrorFramesReceived
The number of EAPOL frames that have been received by this Supplicant in which the Packet Body Length field (7.5.5) is invalid.
- LastEapolFrameVersion
The protocol version number carried in the most recently received EAPOL frame.
- LastEapolFrameSource
The source MAC address carried in the most recently received EAPOL frame.
Description
The GetSupplicantStatistics() function reads the statistical information Statistics regarding the operation of the Supplicant associated with the Port.
If Statistics is NULL, then EFI_INVALID_PARAMETER is returned.
Status Codes Returned
EFI_SUCCESS |
The statistical information regarding the operation of the Supplicant for the Port is read successfully. |
EFI_INVALID_PARAMETER |
Statistics is NULL. |
27.2.14. EFI EAP Management2 Protocol¶
27.2.14.1. EFI_EAP_MANAGEMENT2_PROTOCOL¶
Summary
This protocol provides the ability to configure and control EAPOL state machine, and retrieve the information, status and the statistics information of EAPOL state machine.
GUID
#define EFI_EAP_MANAGEMENT2_PROTOCOL_GUID \
{ 0x5e93c847, 0x456d, 0x40b3, \
{ 0xa6, 0xb4, 0x78, 0xb0, 0xc9, 0xcf, 0x7f, 0x20 }}
Protocol Interface Structure
typedef struct _EFI_EAP_MANAGEMENT2_PROTOCOL {
...... // Same as EFI_EAP_MANAGEMENT_PROTOCOL
EFI_EAP_GET_KEY GetKey;
} EFI_EAP_MANAGMENT2_PROTOCOL;
Parameters
- GetKey
Provide Key information parsed from EAP packet. See the GetKey() function description.
Description
The EFI_EAP_MANAGEMENT2_PROTOCOL is used to control, configure and monitor EAPOL state machine on a Port, and return information of the Port. EAPOL state machine is built on a per-Port basis. Herein, a Port means a NIC. For the details of EAPOL, please refer to IEEE 802.1x specification.
27.2.15. EFI_EAP_MANAGEMENT2_PROTOCOL.GetKey()¶
Summary
Return key generated through EAP process.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_GET_KEY)(
IN EFI_EAP_MANAGEMENT2_PROTOCOL *This,
IN OUT UINT8 *Msk,
IN OUT UINTN *MskSize,
IN OUT UINT8 *Emsk,
IN OUT UINT8 *EmskSize
);
Parameters
- This
Pointer to the EFI_EAP_MANAGEMENT2_PROTOCOL instance.
- Msk
Pointer to MSK (Master Session Key) buffer.
- MskSize
MSK buffer size.
- Emsk
Pointer to EMSK (Extended Master Session Key) buffer.
- EmskSize
EMSK buffer size.
Description
The GetKey() function return the key generated through EAP process, so that the 802.11 MAC layer driver can use MSK to derive more keys, e.g. PMK (Pairwise Master Key).
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• Msk is NULL.
• MskSize is NULL.
• Emsk is NULL.
• EmskSize is NULL.
|
EFI_NOT_READY |
MSK and EMSK are not generated in current session yet. |
27.2.16. EFI EAP Configuration Protocol¶
27.2.16.1. EFI_EAP_CONFIGURATION_PROTOCOL¶
Summary
This protocol provides a way to set and get EAP configuration.
GUID
#define EFI_EAP_CONFIGURATION_PROTOCOL_GUID \
{ 0xe5b58dbb, 0x7688, 0x44b4, \
{ 0x97, 0xbf, 0x5f, 0x1d, 0x4b, 0x7c, 0xc8, 0xdb }}
Protocol Interface Structure
typedef struct _EFI_EAP_CONFIGURATION_PROTOCOL {
EFI_EAP_CONFIGURATION_SET_DATA SetData;
EFI_EAP_CONFIGURATION_GET_DATA GetData;
} EFI_EAP_CONFIGURATION_PROTOCOL;
Parameters
- SetData
Set EAP configuration data. See the SetData() function description.
- GetData
Get EAP configuration data. See the GetData() function description.
Description
The EFI_EAP_CONFIGURATION_PROTOCOL is designed to provide a way to set and get EAP configuration, such as Certificate, private key file.
27.2.17. EFI_EAP_CONFIGURATION_PROTOCOL.SetData()¶
Summary
Set EAP configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_CONFIGURATION_SET_DATA)(
IN EFI_EAP_CONFIGURATION_PROTOCOL *This,
IN EFI_EAP_TYPE EapType,
IN EFI_EAP_CONFIG_DATA_TYPE DataType,
IN VOID *Data,
IN UINTN DataSize
);
Parameters
- This
Pointer to the EFI_EAP_CONFIGURATION_PROTOCOL instance.
- EapType
EAP type. See EFI_EAP_TYPE.
- DataType
Configuration data type. See EFI_EAP_CONFIG_DATA_TYPE
- Data
Pointer to configuration data.
- DataSize
Total size of configuration data.
Description
The SetData() function sets EAP configuration to non-volatile storage or volatile storage.
Related Definitions
//
// Make sure it not conflict with any real EapTypeXXX
//
#define EFI_EAP_TYPE_ATTRIBUTE 0
typedef enum {
// EFI_EAP_TYPE_ATTRIBUTE
EfiEapConfigEapAuthMethod,
EfiEapConfigEapSupportedAuthMethod,
// EapTypeIdentity
EfiEapConfigIdentityString,
// EapTypeEAPTLS/EapTypePEAP
EfiEapConfigEapTlsCACert,
EfiEapConfigEapTlsClientCert,
EfiEapConfigEapTlsClientPrivateKeyFile,
EfiEapConfigEapTlsClientPrivateKeyFilePassword,\\
// ASCII format, Volatile
EfiEapConfigEapTlsCipherSuite,
EfiEapConfigEapTlsSupportedCipherSuite,
// EapTypeMSChapV2
EfiEapConfigEapMSChapV2Password, // UNICODE format, Volatile
// EapTypePEAP
EfiEapConfigEap2ndAuthMethod,
// More...
} EFI_EAP_CONFIG_DATA_TYPE;
//
// EFI_EAP_TYPE
//
typedef UINT8 EFI_EAP_TYPE;
#define EFI_EAP_TYPE_ATTRIBUTE 0
#define EFI_EAP_TYPE_IDENTITY 1
#define EFI_EAP_TYPE_NOTIFICATION 2
#define EFI_EAP_TYPE_NAK 3
#define EFI_EAP_TYPE_MD5CHALLENGE 4
#define EFI_EAP_TYPE_OTP 5
#define EFI_EAP_TYPE_GTC 6
#define EFI_EAP_TYPE_EAPTLS 13
#define EFI_EAP_TYPE_EAPSIM 18
#define EFI_EAP_TYPE_TTLS 21
#define EFI_EAP_TYPE_PEAP 25
#define EFI_EAP_TYPE_MSCHAPV2 26
#define EFI_EAP_TYPE_EAP_EXTENSION 33
......
Status Codes Returned
EFI_SUCCESS |
The EAP configuration data is set successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• Data is NULL.
• DataSize is 0.
|
EFI_UNSUPPORTED |
The EapType or DataType is unsupported. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.2.18. EFI_EAP_CONFIGURATION_PROTOCOL.GetData()¶
Summary
Get EAP configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_EAP_CONFIGURATION_GET_DATA)(
IN EFI_EAP_CONFIGURATION_PROTOCOL *This,
IN EFI_EAP_TYPE EapType,
IN EFI_EAP_CONFIG_DATA_TYPE DataType,
IN OUT VOID *Data,
IN OUT UINTN *DataSize
);
Parameters
- This
Pointer to the EFI_EAP_CONFIGURATION_PROTOCOL instance.
- EapType
EAP type. See EFI_EAP_TYPE.
- DataType
Configuration data type. See EFI_EAP_CONFIG_DATA_TYPE
- Data
Pointer to configuration data.
- DataSize
Total size of configuration data. On input, it means the size of Data * buffer. On output, it means the size of copied *Data buffer if EFI_SUCCESS, and means the size of desired Data buffer if EFI_BUFFER_TOO_SMALL.
Description
The GetData() function gets EAP configuration.
Status Codes Returned
EFI_SUCCESS |
The EAP configuration data is got successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• Data is NULL.
• DataSize is NULL.
|
EFI_UNSUPPORTED |
The EapType or DataType is unsupported. |
EFI_NOT_FOUND |
The EAP configuration data is not found. |
EFI_BUFFER_TOO_SMALL |
The buffer is too small to hold the buffer. |
27.3. EFI Wireless MAC Connection Protocol¶
27.3.1. EFI_WIRELESS_MAC_CONNECTION_PROTOCOL¶
Summary
This protocol provides management service interfaces of 802.11 MAC layer. It is used by network applications (and drivers) to establish wireless connection with an access point (AP).
GUID
#define EFI_WIRELESS_MAC_CONNECTION_PROTOCOL_GUID \
{ 0xda55bc9, 0x45f8, 0x4bb4, \
{ 0x87, 0x19, 0x52, 0x24, 0xf1, 0x8a, 0x4d, 0x45 }}
Protocol Interface Structure
typedef struct _EFI_WIRELESS_MAC_CONNECTION_PROTOCOL {
EFI_WIRELESS_MAC_CONNECTION_SCAN Scan;
EFI_WIRELESS_MAC_CONNECTION_ASSOCIATE Associate;
EFI_WIRELESS_MAC_CONNECTION_DISASSOCIATE Disassociate;
EFI_WIRELESS_MAC_CONNECTION_AUTHENTICATE Authenticate;
EFI_WIRELESS_MAC_CONNECTION_DEAUTHENTICATE Deauthenticate;
} EFI_WIRELESS_MAC_CONNECTION_PROTOCOL;
Parameters
- Scan
Determine the characteristics of the available BSSs. See the Scan() function description.
- Associate
Places an association request with a specific peer MAC entity. See the Associate() function description.
- Disassociate
Reports a disassociation with a specific peer MAC entity. See the Disassociate() function description.
- Authenticate
Requests authentication with a specific peer MAC entity. See the Authenticate() function description.
- Deauthenticate
Invalidates an authentication relationship with a peer MAC entity. See the Deauthenticate() function description.
Description
The EFI_WIRELESS_MAC_CONNECTION_PROTOCOL is designed to provide management service interfaces for the EFI wireless network stack to establish wireless connection with AP. An EFI Wireless MAC Connection Protocol instance will be installed on each communication device that the EFI wireless network stack runs on.
27.3.2. EFI_WIRELESS_MAC_CONNECTION_PROTOCOL.Scan()¶
Summary
Request a survey of potential BSSs that administrator can later elect to try to join.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_SCAN)(
IN EFI_WIRELESS_MAC_CONNECTION_PROTOCOL *This,
IN EFI_80211_SCAN_DATA_TOKEN *Data
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_PROTOCOL
- Data
Pointer to the scan token. Type EFI_80211_SCAN_DATA_TOKEN is defined in “Related Definitions” below.
Description
The Scan() function returns the description of the set of BSSs detected by the scan process. Passive scan operation is performed by default.
Related Definitions
//**********************************************
// EFI_80211_SCAN_DATA_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_SCAN_DATA *Data;
EFI_80211_SCAN_RESULT_CODE ResultCode;
EFI_80211_SCAN_RESULT *Result;
} EFI_80211_SCAN_DATA_TOKEN;
- Event
This Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_SUCCESS: Scan operation completed successfully.EFI_NOT_FOUND: Failed to find available BSS.EFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED: The scan operation is not completed due to some underlying hardware or software state.EFI_NOT_READY: The scan operation is started but not yet completed.- Data
Pointer to the scan data. Type EFI_80211_SCAN_DATA is defined below.
- ResultCode
Indicates the scan state. Type EFI_80211_SCAN_RESULT_CODE is defined below.
- Result
Indicates the scan result. It is caller’s responsibility to free this buffer. Type EFI_80211_SCAN_RESULT is defined below.
The EFI_80211_SCAN_DATA_TOKEN structure is defined to support the process of determining the characteristics of the available BSSs. As input, the Data field must be filled in by the caller of EFI Wireless MAC Connection Protocol. After the scan operation completes, the EFI Wireless MAC Connection Protocol driver updates the Status, ResultCode and Result field and the Event is signaled.
//**********************************************
// EFI_80211_SCAN_DATA
//**********************************************
typedef struct {
EFI_80211_BSS_TYPE BSSType;
EFI_80211_MAC_ADDRESS BSSId;
UINT8 SSIdLen;
UINT8 *SSId;
BOOLEAN PassiveMode;
UINT32 ProbeDelay;
UINT32 *ChannelList;
UINT32 MinChannelTime;
UINT32 MaxChannelTime;
EFI_80211_ELEMENT_REQ *RequestInformation;
EFI_80211_ELEMENT_SSID *SSIDList;
EFI_80211_ACC_NET_TYPE AccessNetworkType;
UINT8 *VendorSpecificInfo;
} EFI_80211_SCAN_DATA;
- BSSType
Determines whether infrastructure BSS, IBSS, MBSS, or all, are included in the scan. Type EFI_80211_BSS_TYPE is defined below.
- BSSId
Indicates a specific or wildcard BSSID. Use all binary 1s to represent all SSIDs. Type EFI_80211_MAC_ADDRESS is defined below.
- SSIdLen
Length in bytes of the SSId. If zero, ignore the SSId field.
- SSId
Specifies the desired SSID or the wildcard SSID. Use NULL to represent all SSIDs.
- PassiveMode
Indicates passive scanning if TRUE.
- ProbeDelay
The delay in microseconds to be used prior to transmitting a Probe frame during active scanning. If zero, the value can be overridden by an implementation-dependent default value.
- ChannelList
Specifies a list of channels that are examined when scanning for a BSS. If set to NULL, all valid channels will be scanned.
- MinChannelTime
Indicates the minimum time in TU to spend on each channel when scanning. If zero, the value can be overridden by an implementation-dependent default value.
- MaxChannelTime
Indicates the maximum time in TU to spend on each channel when scanning. If zero, the value can be overridden by an implementation-dependent default value.
- RequestInformation
Points to an optionally present element. This is an optional parameter and may be NULL. Type EFI_80211_ELEMENT_REQ is defined below.
- SSIDList
Indicates one or more SSID elements that are optionally present. This is an optional parameter and may be NULL. Type EFI_80211_ELEMENT_SSID is defined below.
- AccessNetworkType
Specifies a desired specific access network type or the wildcard access network type. Use 15 as wildcard access network type. Type EFI_80211_ACC_NET_TYPE is defined below.
- VendorSpecificInfo
Specifies zero or more elements. This is an optional parameter and may be NULL.
//**********************************************
// EFI_80211_BSS_TYPE
//**********************************************
typedef enum {
IeeeInfrastructureBSS,
IeeeIndependentBSS,
IeeeMeshBSS,
IeeeAnyBss
} EFI_80211_BSS_TYPE;
The EFI_80211_BSS_TYPE is defined to enumerate BSS type.
//**********************************************
// EFI_80211_MAC_ADDRESS
//**********************************************
typedef struct {
UINT8 Addr[6];
} EFI_80211_MAC_ADDRESS;
The EFI_80211_MAC_ADDRESS is defined to record a 48-bit MAC address.
//**********************************************
// EFI_80211_ELEMENT_REQ
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
UINT8 RequestIDs[1];
} EFI_80211_ELEMENT_REQ;
- Hdr
Common header of an element. Type EFI_80211_ELEMENT_HEADER is defined below.
- RequestIDs
Start of elements that are requested to be included in the Probe Response frame. The elements are listed in order of increasing element ID.
//**********************************************
// EFI_80211_ELEMENT_HEADER
//**********************************************
typedef struct {
UINT8 ElementID;
UINT8 Length;
} EFI_80211_ELEMENT_HEADER;
- ElementID
A unique element ID defined in IEEE 802.11 specification.
- Length
Specifies the number of octets in the element body.
//**********************************************
// EFI_80211_ELEMENT_SSID
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
UINT8 SSId [32];
} EFI_80211_ELEMENT_SSID;
- Hdr
Common header of an element.
- SSId
Service set identifier. If Hdr.Length is zero, this field is ignored.
//**********************************************
// EFI_80211_ACC_NET_TYPE
//**********************************************
typedef enum {
IeeePrivate = 0,
IeeePrivatewithGuest = 1,
IeeeChargeablePublic = 2,
IeeeFreePublic = 3,
IeeePersonal = 4,
IeeeEmergencyServOnly = 5,
IeeeTestOrExp = 14,
IeeeWildcard = 15
} EFI_80211_ACC_NET_TYPE;
The EFI_80211_ACC_NET_TYPE records access network types defined in IEEE 802.11 specification.
//**********************************************
// EFI_80211_SCAN_RESULT_CODE
//**********************************************
typedef enum {
ScanSuccess,
ScanNotSupported
} EFI_80211_SCAN_RESULT_CODE;
- ScanSuccess
The scan operation finished successfully.
- ScanNotSupported
The scan operation is not supported in current implementation.
//**********************************************
// EFI_80211_SCAN_RESULT
//**********************************************
typedef struct {
UINTN NumOfBSSDesp;
EFI_80211_BSS_DESCRIPTION **BSSDespSet;
UINTN NumofBSSDespFromPilot;
EFI_80211_BSS_DESP_PILOT **BSSDespFromPilotSet;
UINT8 *VendorSpecificInfo;
} EFI_80211_SCAN_RESULT;
- NumOfBSSDesp
The number of EFI_80211_BSS_DESCRIPTION in BSSDespSet. If zero, BSSDespSet should be ignored.
- BSSDespSet
Points to zero or more instances of EFI_80211_BSS_DESCRIPTION. Type EFI_80211_BSS_DESCRIPTION is defined below.
- NumOfBSSDespFromPilot
The number of EFI_80211_BSS_DESP_PILOT in BSSDespFromPilotSet. If zero, BSSDespFromPilotSet should be ignored.
- BSSDespFromPilotSet
Points to zero or more instances of EFI_80211_BSS_DESP_PILOT. Type EFI_80211_BSS_DESP_PILOT is defined below.
- VendorSpecificInfo
Specifies zero or more elements. This is an optional parameter and may be NULL.
//**********************************************
// EFI_80211_BSS_DESCRIPTION
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS *BSSId;
UINT8 *SSId;
UINT8 SSIdLen;
EFI_80211_BSS_TYPE BSSType;
UINT16 BeaconPeriod;
UINT64 Timestamp;
UINT16 CapabilityInfo;
UINT8 *BSSBasicRateSet;
UINT8 *OperationalRateSet;
EFI_80211_ELEMENT_COUNTRY *Country;
EFI_80211_ELEMENT_RSN RSN;
UINT8 RSSI;
UINT8 RCPIMeasurement;
UINT8 RSNIMeasurement;
UINT8 *RequestedElements;
UINT8 *BSSMembershipSelectorSet;
EFI_80211_ELEMENT_EXT_CAP *ExtCapElement;
} EFI_80211_BSS_DESCRIPTION;
- BSSId
Indicates a specific BSSID of the found BSS.
- SSId
Specifies the SSID of the found BSS. If NULL, ignore SSIdLen field.
- SSIdLen
Length in bytes of the SSId. If zero, ignore SSId field.
- BSSType
Specifies the type of the found BSS.
- BeaconPeriod
The beacon period in TU of the found BSS.
- Timestamp
The timestamp of the received frame from the found BSS.
- CapabilityInfo
The advertised capabilities of the BSS.
- BSSBasicRateSet
The set of data rates that shall be supported by all STAs that desire to join this BSS.
- OperationalRateSet
The set of data rates that the peer STA desires to use for communication within the BSS.
- Country
The information required to identify the regulatory domain in which the peer STA is located. Type EFI_80211_ELEMENT_COUNTRY is defined below.
- RSN
The cipher suites and AKM suites supported in the BSS. Type EFI_80211_ELEMENT_RSN is defined below.
- RSSI
Specifies the RSSI of the received frame.
- RCPIMeasurement
Specifies the RCPI of the received frame.
- RSNIMeasurement
Specifies the RSNI of the received frame.
- RequestedElements
Specifies the elements requested by the request element of the Probe Request frame. This is an optional parameter and may be NULL.
- BSSMembershipSelectorSet
Specifies the BSS membership selectors that represent the set of features that shall be supported by all STAs to join this BSS.
- ExtCapElement
Specifies the parameters within the Extended Capabilities element that are supported by the MAC entity. This is an optional parameter and may be NULL. Type EFI_80211_ELEMENT_EXT_CAP is defined below.
//**********************************************
// EFI_80211_ELEMENT_COUNTRY
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
UINT8 CountryStr [3];
EFI_80211_COUNTRY_TRIPLET CountryTriplet[1];
} EFI_80211_ELEMENT_COUNTRY;
- Hdr
Common header of an element.
- CountryStr
Specifies country strings in 3 octets.
- CountryTriplet
Indicates a triplet that repeated in country element. The number of triplets is determined by the Hdr.Length field.
//**********************************************
// EFI_80211_COUNTRY_TRIPLET
//**********************************************
typedef union {
EFI_80211_COUNTRY_TRIPLET_SUBBAND Subband;
EFI_80211_COUNTRY_TRIPLET_OPERATE Operating;
} EFI_80211_COUNTRY_TRIPLET;
- Subband
The subband triplet.
- Operating
The operating triplet.
//**********************************************
// EFI_80211_COUNTRY_TRIPLET_SUBBAND
//**********************************************
typedef struct {
UINT8 FirstChannelNum;
UINT8 NumOfChannels;
UINT8 MaxTxPowerLevel;
} EFI_80211_COUNTRY_TRIPLET_SUBBAND;
- FirstChannelNum
Indicates the lowest channel number in the subband. It has a positive integer value less than 201.
- NumOfChannels
Indicates the number of channels in the subband.
- MaxTxPowerLevel
Indicates the maximum power in dBm allowed to be transmitted.
//**********************************************
// EFI_80211_COUNTRY_TRIPLET_OPERATE
//**********************************************
typedef struct {
UINT8 OperatingExtId;
UINT8 OperatingClass;
UINT8 CoverageClass;
} EFI_80211_COUNTRY_TRIPLET_OPERATE;
- OperatingExtId
Indicates the operating extension identifier. It has a positive integer value of 201 or greater.
- OperatingClass
Index into a set of values for radio equipment set of rules.
- CoverageClass
Specifies an AirPropagationTime characteristics used in BSS operation. Refer the definition of an AirPropagationTime in IEEE 802.11 specification.
//**********************************************
// EFI_80211_ELEMENT_RSN
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
EFI_80211_ELEMENT_DATA_RSN *Data;
} EFI_80211_ELEMENT_RSN;
- Hdr
Common header of an element.
- Data
Points to RSN element. Type EFI_80211_ELEMENT_DATA_RSN is defined below. The size of a RSN element is limited to 255 octets.
//**********************************************
// EFI_80211_ELEMENT_DATA_RSN
//**********************************************
typedef struct {
UINT16 Version;
UINT32 GroupDataCipherSuite;
//UINT16 PairwiseCipherSuiteCount;
//UINT32 PairwiseCipherSuiteList [PairwiseCipherSuiteCount];
//UINT16 AKMSuiteCount;
//UINT32 AKMSuiteList [AKMSuiteCount];
//UINT16 RSNCapabilities;
//UINT16 PMKIDCount;
//UINT8 PMKIDList [PMKIDCount][16];
//UINT32 GroupManagementCipherSuite;
} EFI_80211_ELEMENT_DATA_RSN;
- Version
Indicates the version number of the RSNA protocol. Value 1 is defined in current IEEE 802.11 specification.
- GroupDataCipherSuite
Specifies the cipher suite selector used by the BSS to protect group address frames.
- PairwiseCipherSuiteCount
Indicates the number of pairwise cipher suite selectors that are contained in PairwiseCipherSuiteList.
- PairwiseCipherSuiteList
Contains a series of cipher suite selectors that indicate the pairwise cipher suites contained in this element.
- AKMSuiteCount
Indicates the number of AKM suite selectors that are contained in AKMSuiteList.
- AKMSuiteList
Contains a series of AKM suite selectors that indicate the AKM suites contained in this element.
- RSNCapabilities
Indicates requested or advertised capabilities.
- PMKIDCount
Indicates the number of PKMIDs in the PMKIDList.
- PMKIDList
Contains zero or more PKMIDs that the STA believes to be valid for the destination AP.
- GroupManagementCipherSuite
Specifies the cipher suite selector used by the BSS to protect group addressed robust management frames.
//**********************************************
// EFI_80211_ELEMENT_EXT_CAP
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
UINT8 Capabilities[1];
} EFI_80211_ELEMENT_EXT_CAP;
- Hdr
Common header of an element.
- Capabilities
Indicates the capabilities being advertised by the STA transmitting the element. This is a bit field with variable length. Refer to IEEE 802.11 specification for bit value.
//**********************************************
// EFI_80211_BSS_DESP_PILOT
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
EFI_80211_BSS_TYPE BSSType;
UINT8 ConCapInfo;
UINT8 ConCountryStr[2];
UINT8 OperatingClass;
UINT8 Channel;
UINT8 Interval;
EFI_80211_MULTIPLE_BSSID *MultipleBSSID;
UINT8 RCPIMeasurement;
UINT8 RSNIMeasurement;
} EFI_80211_BSS_DESP_PILOT;
- BSSId
Indicates a specific BSSID of the found BSS.
- BSSType
Specifies the type of the found BSS.
- ConCapInfo
One octet field to report condensed capability information.
- ConCountryStr
Two octet’s field to report condensed country string.
- OperatingClass
Indicates the operating class value for the operating channel.
- Channel
Indicates the operating channel.
- Interval
Indicates the measurement pilot interval in TU.
- MultipleBSSID
Indicates that the BSS is within a multiple BSSID set.
- RCPIMeasurement
Specifies the RCPI of the received frame.
- RSNIMeasurement
Specifies the RSNI of the received frame.
//**********************************************
// EFI_80211_MULTIPLE_BSSID
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
UINT8 Indicator;
EFI_80211_SUBELEMENT_INFO SubElement[1];
} EFI_80211_MULTIPLE_BSSID;
- Hdr
Common header of an element.
- Indicator
Indicates the maximum number of BSSIDs in the multiple BSSID set. When Indicator is set to n, 2n is the maximum number.
- SubElement
Contains zero or more sub-elements. Type EFI_80211_SUBELEMENT_INFO is defined below.
//**********************************************
// EFI_80211_SUBELEMENT_INFO
//**********************************************
typedef struct {
UINT8 SubElementID;
UINT8 Length;
UINT8 Data[1];
} EFI_80211_SUBELEMENT_INFO;
- SubElementID
Indicates the unique identifier within the containing element or sub-element.
- Length
Specifies the number of octets in the Data field.
- Data
A variable length data buffer.
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• This is NULL.
• Data is NULL.
• Data -> Data is NULL.
|
EFI_UNSUPPORTED |
One or more of the input parameters are not supported by this implementation. |
EFI_ALREADY_STARTED |
The scan operation is already started. |
27.3.3. EFI_WIRELESS_MAC_CONNECTION_PROTOCOL.Associate()¶
Summary
Request an association with a specified peer MAC entity that is within an AP.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_ASSOCIATE)(
IN EFI_WIRELESS_MAC_CONNECTION_PROTOCOL *This,
IN EFI_80211_ASSOCIATE_DATA_TOKEN *Data
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_PROTOCOL instance.
- Data
Pointer to the association token. Type EFI_80211_ASSOCIATE_DATA_TOKEN is defined in Related Definitions below.
Description
The Associate() function provides the capability for MAC layer to become associated with an AP.
Related Definitions
//**********************************************
// EFI_80211_ASSOCIATE_DATA_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_ASSOCIATE_DATA Data;
EFI_80211_ASSOCIATE_RESULT_CODE ResultCode;
EFI_80211_ASSOCIATE_RESULT Result;
} EFI_80211_ASSOCIATE_DATA_TOKEN;
- Event
This Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values: EFI_SUCCESS: Association operation completed successfully. EFI_DEVICE_ERROR: An unexpected network or system error occurred.
- Data
Pointer to the association data. Type EFI_80211_ASSOCIATE_DATA is defined below.
- ResultCode
Indicates the association state. Type EFI_80211_ASSOCIATE_RESULT_CODE is defined below.
- Result
Indicates the association result. It is caller’s responsibility to free this buffer. Type EFI_80211_ASSOCIATE_RESULT* is defined below.
The EFI_80211_ASSOCIATE_DATA_TOKEN structure is defined to support the process of association with a specified AP. As input, the Data field must be filled in by the caller of EFI Wireless MAC Connection Protocol. After the association operation completes, the EFI Wireless MAC Connection Protocol driver updates the Status, ResultCode and Result field and the Event is signaled.
//**********************************************
// EFI_80211_ASSOCIATE_DATA
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
UINT16 CapabilityInfo;
UINT32 FailureTimeout;
UINT32 ListenInterval;
EFI_80211_ELEMENT_SUPP_CHANNEL *Channels;
EFI_80211_ELEMENT_RSN RSN;
EFI_80211_ELEMENT_EXT_CAP ExtCapElement;
UINT8 *VendorSpecificInfo;
} EFI_80211_ASSOCIATE_DATA;
- BSSId
Specifies the address of the peer MAC entity to associate with.
- CapabilityInfo
Specifies the requested operational capabilities to the AP in 2 octets.
- FailureTimeout
Specifies a time limit in TU, after which the associate procedure is terminated.
- ListenInterval
Specifies if in power save mode, how often the STA awakes and listens for the next beacon frame in TU.
- Channels
Indicates a list of channels in which the STA is capable of operating. Type EFI_80211_ELEMENT_SUPP_CHANNEL is defined below.
- RSN
The cipher suites and AKM suites selected by the STA.
- ExtCapElement
Specifies the parameters within the Extended Capabilities element that are supported by the MAC entity. This is an optional parameter and may be NULL.
- VendorSpecificInfo
Specifies zero or more elements. This is an optional parameter and may be NULL.
//**********************************************
// EFI_80211_ELEMENT_SUPP_CHANNEL
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
EFI_80211_ELEMENT_SUPP_CHANNEL_TUPLE Subband[1];
} EFI_80211_ELEMENT_SUPP_CHANNEL;
- Hdr
Common header of an element.
- Subband
Indicates one or more tuples of (first channel, number of channels). Type EFI_80211_ELEMENT_SUPP_CHANNEL_TUPLE is defined below.
//**********************************************
// EFI_80211_ELEMENT_SUPP_CHANNEL_TUPLE
//**********************************************
typedef struct {
UINT8 FirstChannelNumber;
UINT8 NumberOfChannels;
} EFI_80211_ELEMENT_SUPP_CHANNEL_TUPLE;
- FirstChannelNumber
The first channel number in a subband of supported channels.
- NumberOfChannels
The number of channels in a subband of supported channels.
//**********************************************
// EFI_80211_ASSOCIATE_RESULT_CODE
//**********************************************
typedef enum {
AssociateSuccess,
AssociateRefusedReasonUnspecified,
AssociateRefusedCapsMismatch,
AssociateRefusedExtReason,
AssociateRefusedAPOutOfMemory,
AssociateRefusedBasicRatesMismatch,
AssociateRejectedEmergencyServicesNotSupported,
AssociateRefusedTemporarily
} EFI_80211_ASSOCIATE_RESULT_CODE;
The EFI_80211_ASSOCIATE_RESULT_CODE records the result responses to the association request, which are defined in IEEE 802.11 specification.
//**********************************************
// EFI_80211_ASSOCIATE_RESULT
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
UINT16 CapabilityInfo;
UINT16 AssociationID;
UINT8 RCPIValue;
UINT8 RSNIValue;
EFI_80211_ELEMENT_EXT_CAP *ExtCapElement;
EFI_80211_ELEMENT_TIMEOUT_VAL TimeoutInterval;
UINT8 *VendorSpecificInfo;
} EFI_80211_ASSOCIATE_RESULT;
- BSSId
Specifies the address of the peer MAC entity from which the association request was received.
- CapabilityInfo
Specifies the operational capabilities advertised by the AP.
- AssociationID
Specifies the association ID value assigned by the AP.
- RCPIValue
Indicates the measured RCPI of the corresponding association request frame. It is an optional parameter and is set to zero if unavailable.
- RSNIValue
Indicates the measured RSNI at the time the corresponding association request frame was received. It is an optional parameter and is set to zero if unavailable.
- ExtCapElement
Specifies the parameters within the Extended Capabilities element that are supported by the MAC entity. This is an optional parameter and may be NULL.
- TimeoutInterval
Specifies the timeout interval when the result code is AssociateRefusedTemporarily .
- VendorSpecificInfo
Specifies zero or more elements. This is an optional parameter and may be NULL.
//**********************************************
// EFI_80211_ELEMENT_TIMEOUT_VAL
//**********************************************
typedef struct {
EFI_80211_ELEMENT_HEADER Hdr;
UINT8 Type;
UINT32 Value;
} EFI_80211_ELEMENT_TIMEOUT_VAL;
- Hdr
Common header of an element.
- Type
Specifies the timeout interval type.
- Value
Specifies the timeout interval value.
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• This is NULL.
• Data is NULL.
• Data -> Data is NULL.
|
EFI_UNSUPPORTED |
One or more of the input parameters are not supported by this implementation. |
EFI_ALREADY_STARTED |
The association process is already started. |
EFI_NOT_READY |
Authentication is not performed before this association process. |
EFI_NOT_FOUND |
The specified peer MAC entity is not found. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.3.4. EFI_WIRELESS_MAC_CONNECTION_PROTOCOL.Disassociate()¶
Summary
Request a disassociation with a specified peer MAC entity.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_DISASSOCIATE)(
IN EFI_WIRELESS_MAC_CONNECTION_PROTOCOL *This,
IN EFI_80211_DISASSOCIATE_DATA_TOKEN *Data
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_PROTOCOL instance.
- Data
Pointer to the disassociation token. Type EFI_80211_DISASSOCIATE_DATA_TOKEN is defined in Related Definitions below.
Description
The Disassociate() function is invoked to terminate an existing association. Disassociation is a notification and cannot be refused by the receiving peer except when management frame protection is negotiated and the message integrity check fails.
Related Definitions
//**********************************************
// EFI_80211_DISASSOCIATE_DATA_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_DISASSOCIATE_DATA *Data;
EFI_80211_DISASSOCIATE_RESULT_CODE ResultCode;
} EFI_80211_DISASSOCIATE_DATA_TOKEN;
- Event
This Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_SUCCESS: Disassociation operation completed successfully.EFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED: The disassociation operation is not completed due to some underlying hardware or software state.EFI_NOT_READY: The disassociation operation is started but not yet completed.- Data
Pointer to the disassociation data. Type EFI_80211_DISASSOCIATE_DATA is defined below.
- ResultCode
Indicates the disassociation state. Type EFI_80211_DISASSOCIATE_RESULT_CODE is defined below.
//**********************************************
// EFI_80211_DISASSOCIATE_DATA
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
EFI_80211_REASON_CODE ReasonCode;
UINT8 *VendorSpecificInfo;
} EFI_80211_DISASSOCIATE_DATA;
- BSSId
Specifies the address of the peer MAC entity with which to perform the disassociation process.
- ReasonCode
Specifies the reason for initiating the disassociation process.
- VendorSpecificInfo
Zero or more elements, may be NULL.
//**********************************************
// EFI_80211_REASON_CODE
//**********************************************
typedef enum {
Ieee80211UnspecifiedReason = 1,
Ieee80211PreviousAuthenticateInvalid = 2,
Ieee80211DeauthenticatedSinceLeaving = 3,
Ieee80211DisassociatedDueToInactive = 4,
Ieee80211DisassociatedSinceApUnable = 5,
Ieee80211Class2FrameNonauthenticated = 6,
Ieee80211Class3FrameNonassociated = 7,
Ieee80211DisassociatedSinceLeaving = 8,
// ...
} EFI_80211_REASON_CODE;
Note: The reason codes are defined in chapter 8.4.1.7 Reason Code field, IEEE 802.11-2012.
//**********************************************
// EFI_80211_DISASSOCIATE_RESULT_CODE
//**********************************************
typedef enum {
DisassociateSuccess,
DisassociateInvalidParameters
} EFI_80211_DISASSOCIATE_RESULT_CODE;
- DisassociateSuccess
Disassociation process completed successfully.
- DisassociateInvalidParameters
Disassociation failed due to any input parameter is invalid.
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• This is NULL.
• Data is NULL.
|
EFI_ALREADY_STARTED |
The disassociation process is already started. |
EFI_NOT_READY |
The disassociation service is invoked to a nonexistent association relationship. |
EFI_NOT_FOUND |
The specified peer MAC entity is not found. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.3.5. EFI_WIRELESS_MAC_CONNECTION_PROTOCOL.Authenticate()¶
Summary
Request the process of establishing an authentication relationship with a peer MAC entity.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_AUTHENTICATE)(
IN EFI_WIRELESS_MAC_CONNECTION_PROTOCOL *This,
IN EFI_80211_AUTHENTICATE_DATA_TOKEN *Data
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_PROTOCOL instance.
- Data
Pointer to the authentication token. Type EFI_80211_AUTHENTICATE_DATA_TOKEN is defined in Related Definitions below.
Description
The Authenticate() function requests authentication with a specified peer MAC entity. This service might be time-consuming thus is designed to be invoked independently of the association service.
Related Definitions
//**********************************************
// EFI_80211_AUTHENTICATE_DATA_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_AUTHENTICATE_DATA *Data;
EFI_80211_AUTHENTICATE_RESULT_CODE ResultCode;
EFI_80211_AUTHENTICATE_RESULT Result;
} EFI_80211_AUTHENTICATE_DATA_TOKEN;
- Event
This Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_PROTOCOL_ERROR: Peer MAC entity rejects the authentication.EFI_NO_RESPONSE: Peer MAC entity does not response the authentication request.EFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED: The authentication operation is not completed due to some underlying hardware or software state.EFI_NOT_READY: The authentication operation is started but not yet completed.- Data
Pointer to the authentication data. Type EFI_80211_AUTHENTICATE_DATA is defined below.
- ResultCode
Indicates the association state. Type EFI_80211_AUTHENTICATE_RESULT_CODE is defined below.
- Result
Indicates the association result. It is caller’s responsibility to free this buffer. Type EFI_80211_AUTHENTICATE_RESULT is defined below.
//**********************************************
// EFI_80211_AUTHENTICATION_DATA
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
EFI_80211_AUTHENTICATION_TYPE AuthType;
UINT32 FailureTimeout;
UINT8 *FTContent;
UINT8 *SAEContent;
UINT8 *VendorSpecificInfo;
} EFI_80211_AUTHENTICATE_DATA;
- BSSId
Specifies the address of the peer MAC entity with which to perform the authentication process.
- AuthType
Specifies the type of authentication algorithm to use during the authentication process.
- FailureTimeout
Specifies a time limit in TU after which the authentication procedure is terminated.
- FTContent
Specifies the set of elements to be included in the first message of the FT authentication sequence, may be NULL.
- SAEContent
Specifies the set of elements to be included in the SAE Commit Message or SAE Confirm Message, may be NULL.
- VendorSpecificInfo
Zero or more elements, may be NULL.
//**********************************************
// EFI_80211_AUTHENTICATION_TYPE
//**********************************************
typedef enum {
OpenSystem,
SharedKey,
FastBSSTransition,
SAE
} EFI_80211_AUTHENTICATION_TYPE;
- OpenSystem
Open system authentication, admits any STA to the DS.
- SharedKey
Shared Key authentication relies on WEP to demonstrate knowledge of a WEP encryption key.
- FastBSSTransition
FT authentication relies on keys derived during the initial mobility domain association to authenticate the stations.
- SAE
SAE authentication uses finite field cryptography to prove knowledge of a shared password.
//**********************************************
// EFI_80211_AUTHENTICATION_RESULT_CODE
//**********************************************
typedef enum {
AuthenticateSuccess,
AuthenticateRefused,
AuthenticateAnticLoggingTokenRequired,
AuthenticateFiniteCyclicGroupNotSupported,
AuthenticationRejected,
AuthenticateInvalidParameter
} EFI_80211_AUTHENTICATE_RESULT_CODE;
The result code indicates the result response to the authentication request from the peer MAC entity.
//**********************************************
// EFI_80211_AUTHENTICATION_RESULT
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
UINT8 *FTContent;
UINT8 *SAEContent;
UINT8 *VendorSpecificInfo;
} EFI_80211_AUTHENTICATE_RESULT;
- BSSId
Specifies the address of the peer MAC entity from which the authentication request was received.
- FTContent
Specifies the set of elements to be included in the second message of the FT authentication sequence, may be NULL.
- SAEContent
Specifies the set of elements to be included in the SAE Commit Message or SAE Confirm Message, may be NULL.
- VendorSpecificInfo
Zero or more elements, may be NULL.
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• This is NULL.
• Data is NULL.
• Data Data is NULL.
|
EFI_UNSUPPORTED |
One or more of the input parameters are not supported by this implementation. |
EFI_ALREADY_STARTED |
The authentication process is already started. |
EFI_NOT_FOUND |
The specified peer MAC entity is not found. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.3.6. EFI_WIRELESS_MAC_CONNECTION_PROTOCOL.Deauthenticate()¶
Summary
Invalidate the authentication relationship with a peer MAC entity.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_DEAUTHENTICATE)(
IN EFI_WIRELESS_MAC_CONNECTION_PROTOCOL *This,
IN EFI_80211_DEAUTHENTICATE_DATA_TOKEN *Data
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION _PROTOCOL instance.
- Data
Pointer to the deauthentication token. Type EFI_80211_DEAUTHENTICATE_DATA_TOKEN is defined in Related Definitions below.
Description
The Deauthenticate() function requests that the authentication relationship with a specified peer MAC entity be invalidated. Deauthentication is a notification and when it is sent out the association at the transmitting station is terminated.
Related Definitions
//**********************************************
// EFI_80211_DEAUTHENTICATE_DATA_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_DEAUTHENTICATE_DATA *Data;
} EFI_80211_DEAUTHENTICATE_DATA_TOKEN;
- Event
This Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_SUCCESS: Deauthentication operation completed successfully.EFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED:The deauthentication operation is not completed due to some underlying hardware or software state.EFI_NOT_READY: The deauthentication operation is started but not yet completed.- Data
Pointer to the deauthentication data. Type EFI_80211_DEAUTHENTICATE_DATA is defined below.
//**********************************************
// EFI_80211_DEAUTHENTICATE_DATA
//**********************************************
typedef struct {
EFI_80211_MAC_ADDRESS BSSId;
EFI_80211_REASON_CODE ReasonCode;
UINT8 *VendorSpecificInfo;
} EFI_80211_DEAUTHENTICATE_DATA;
- BSSId
Specifies the address of the peer MAC entity with which to perform the deauthentication process.
- ReasonCode
Specifies the reason for initiating the deauthentication process.
- VendorSpecificInfo
Zero or more elements, may be NULL.
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• This is NULL.
• Data is NULL.
• Data Data is NULL.
|
EFI_ALREADY_STARTED |
The deauthentication process is already started. |
EFI_NOT_READY |
The deauthentication service is invoked to a nonexistent association or authentication relationship. |
EFI_NOT_FOUND |
The specified peer MAC entity is not found. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.4. EFI Wireless MAC Connection II Protocol¶
This section provides a detailed description of EFI Wireless MAC Connection II Protocol.
27.4.1. EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL¶
Summary
The EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL provides network management service interfaces for 802.11 network stack. It is used by network applications (and drivers) to establish wireless connection with a wireless network.
GUID
#define EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL_GUID \
{ 0x1b0fb9bf, 0x699d, 0x4fdd, \
{ 0xa7, 0xc3, 0x25, 0x46, 0x68, 0x1b, 0xf6, 0x3b }}
Protocol Interface Structure
typedef struct _EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL {
EFI_WIRELESS_MAC_CONNECTION_II_GET_NETWORKS GetNetworks;
EFI_WIRELESS_MAC_CONNECTION_II_CONNECT_NETWORK ConnectNetwork;
EFI_WIRELESS_MAC_CONNECTION_II_DISCONNECT_NETWORK DisconnectNetwork;
} EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL;
Parameters
- GetNetworks
Get a list of nearby detectable wireless network. See the GetNetworks() function description.
- ConnectNetwork
Places a connection request with a specific wireless network. See the ConnectNetwork() function description.
- DisconnectNetwork
Places a disconnection request with a specific wireless network. See the DisconnectNetwork() function description.
Description
The EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL is designed to provide management service interfaces for the EFI wireless network stack to establish relationship with a wireless network (identified by EFI_80211_NETWORK defined below). An EFI Wireless MAC Connection II Protocol instance will be installed on each communication device that the EFI wireless network stack runs on.
27.4.2. EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL.GetNetworks()¶
Summary
Request a survey of potential wireless networks that administrator can later elect to try to join.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_II_GET_NETWORKS)(
IN EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL *This,
IN EFI_80211_GET_NETWORKS_TOKEN *Token
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL instance.
- Token
Pointer to the token for getting wireless network. Type EFI_80211_GET_NETWORKS_TOKEN is defined in Related Definitions below.
Description
The GetNetworks() function returns the description of a list of wireless networks detected by wireless UNDI driver. This function is always non-blocking. If the operation succeeds or fails due to any error, the Token->Event will be signaled and Token->Status will be updated accordingly. The caller of this function is responsible for inputting SSIDs in case of searching hidden networks.
Related Definitions
//**********************************************
// EFI_80211_GET_NETWORKS_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_GET_NETWORKS_DATA *Data;
EFI_80211_GET_NETWORKS_RESULT *Result;
} EFI_80211_GET_NETWORKS_TOKEN;
- Event
If the status code returned by GetNetworks() is EFI_SUCCESS, then this Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol II driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_SUCCESS: The operation completed successfully.EFI_NOT_FOUND: Failed to find available wireless networks.EFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED: The operation is not completed due to some underlying hardware or software state.EFI_NOT_READY: The operation is started but not yet completed.- Data
Pointer to the input data for getting networks. Type EFI_80211_GET_NETWORKS_DATA is defined below.
- Result
Indicates the scan result. It is caller’s responsibility to free this buffer. Type EFI_80211_GET_NETWORKS_RESULT is defined below.
//**********************************************
// EFI_80211_GET_NETWORKS_DATA
//**********************************************
typedef struct {
UINT32 NumOfSSID;
EFI_80211_SSID SSIDList[1];
} EFI_80211_GET_NETWORKS_DATA;
- NumOfSSID
The number of EFI_80211_SSID in SSIDList. If zero, SSIDList should be ignored.
- SSIDList
The SSIDList is a pointer to an array of EFI_80211_SSID instances. The number of entries is specified by NumOfSSID. The array should only include SSIDs of hidden networks. It is suggested that the caller inputs less than 10 elements in the SSIDList. It is the caller’s responsibility to free this buffer. Type EFI_80211_SSID is defined below.
#define EFI_MAX_SSID_LEN 32
//**********************************************
// EFI_80211_SSID
//**********************************************
typedef struct {
UINT8 SSIdLen;
UINT8 SSId[EFI_MAX_SSID_LEN];
} EFI_80211_SSID;
- SSIdLen
Length in bytes of the SSId. If zero, ignore SSId field.
- SSId
Specifies the service set identifier.
//**********************************************
// EFI_80211_GET_NETWORKS_RESULT
//**********************************************
typedef struct {
UINT8 NumOfNetworkDesc;
EFI_80211_NETWORK_DESCRIPTION NetworkDesc[1];
} EFI_80211_GET_NETWORKS_RESULT;
- NumOfNetworkDesc
The number of elements in NetworkDesc. If zero, NetworkDesc should be ignored.
- NetworkDesc
The NetworkDesc is a variable-length array of elements of type EFI_80211_NETWORK_DESCRIPTION. Type EFI_80211_NETWORK_DESCRIPTION is defined below.
//**********************************************
// EFI_80211_NETWORK_DESCRIPTION
//**********************************************
typedef struct {
EFI_80211_NETWORK Network;
UINT8 NetworkQuality;
} EFI_80211_NETWORK_DESCRIPTION;
- Network
Specifies the found wireless network. Type EFI_80211_NETWORK is defined below.
- NetworkQuality
Indicates the network quality as a value between 0 to 100, where 100 indicates the highest network quality.
//**********************************************
// EFI_80211_NETWORK
//**********************************************
typedef struct {
EFI_80211_BSS_TYPE BSSType;
EFI_80211_SSID SSId;
EFI_80211_AKM_SUITE_SELECTOR *AKMSuite;
EFI_80211_CIPHER_SUITE_SELECTOR *CipherSuite;
} EFI_80211_NETWORK;
- BSSType
Specifies the type of the BSS. Type EFI_80211_BSS_TYPE is defined below.
- SSId
Specifies the SSID of the BSS. Type EFI_80211_SSID is defined above.
- AKMSuite
Pointer to the AKM suites supported in the wireless network. Type EFI_80211_AKM_SUITE_SELECTOR is defined below.
- CipherSuite
Pointer to the cipher suites supported in the wireless network. Type EFI_80211_CIPHER_SUITE_SELECTOR is defined below.
//**********************************************
// EFI_80211_BSS_TYPE
//**********************************************
typedef enum {
IeeeInfrastructureBSS,
IeeeIndependentBSS,
IeeeMeshBSS,
IeeeAnyBss
} EFI_80211_BSS_TYPE;
The EFI_80211_BSS_TYPE is defined to enumerate BSS type.
//**********************************************
// EFI_80211_SUITE_SELECTOR
//**********************************************
typedef struct {
UINT8 Oui[3];
UINT8 SuiteType;
} EFI_80211_SUITE_SELECTOR;
- Oui
Organization Unique Identifier, as defined in IEEE 802.11 standard, usually set to 00-0F-AC.
- SuiteType
Suites types, as defined in IEEE 802.11 standard.
//***********************************************************
// EFI_80211_AKM_SUITE_SELECTOR
//************************************************************
typedef struct {
UINT16 AKMSuiteCount;
EFI_80211_SUITE_SELECTOR AKMSuiteList[1];
} EFI_80211_AKM_SUITE_SELECTOR;
- AKMSuiteCount
Indicates the number of AKM suite selectors that are contained in AKMSuiteList. If zero, the AKMSuiteList is ignored.
- AKMSuiteList
A variable-length array of AKM suites, as defined in IEEE 802.11 standard, Table 8-101. The number of entries is specified by AKMSuiteCount.
//************************************************************
// EFI_80211_CIPHER_SUITE_SELECTOR
//************************************************************
typedef struct {
UINT16 CipherSuiteCount;
EFI_80211_SUITE_SELECTOR CipherSuiteList[1];
} EFI_80211_CIPHER_SUITE_SELECTOR;
- CipherSuiteCount
Indicates the number of cipher suites that are contained in CipherSuiteList. If zero, the CipherSuiteList is ignored.
- CipherSuiteList
A variable-length array of cipher suites, as defined in IEEE 802.11 standard, Table 8-99. The number of entries is specified by CipherSuiteCount.
Status Codes Returned
EFI_SUCCESS |
The operation started, and an event will eventually be raised for the caller. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
This is NULL.
Token is NULL.
|
EFI_UNSUPPORTED |
One or more of the input parameters is not supported by this implementation. |
EFI_ALREADY_STARTED |
The operation of getting wireless network is already started. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.4.3. EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL.ConnectNetwork()¶
Summary
Connect a wireless network specified by a particular SSID, BSS type and Security type.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_II_CONNECT_NETWORK)(
IN EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL *This,
IN EFI_80211_CONNECT_NETWORK_TOKEN *Token
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL instance.
- Token
Pointer to the token for connecting wireless network. Type EFI_80211_CONNECT_NETWORK_TOKEN is defined in Related Definitions below.
Description
The ConnectNetwork() function places a request to wireless UNDI driver to connect a wireless network specified by a particular SSID, BSS type, Authentication method and cipher. This function will trigger wireless UNDI driver to perform authentication and association process to establish connection with a particular Access Point for the specified network. This function is always non-blocking. If the connection succeeds or fails due to any error, the Token->Event will be signaled and Token->Status will be updated accordingly.
After having signaled a successful connection completion, the UNDI driver will update the network connection state using the network media state information type in the EFI_ADAPTER_INFORMATION_PROTOCOL. If needed, the caller should use EFI_ADAPTER_INFORMATION_PROTOCOL to regularly get the network media state to find if the UNDI driver is still connected to the wireless network ( EFI_SUCCESS ) or not ( EFI_NO_MEDIA ).
Generally a driver or application in WiFi stack would provide user interface to end user to manage profiles for selecting which wireless network to join and other state management. This module should prompt the user to select a network and input WiFi security data such as certificate, private key file, password, etc. Then the module should deploy WiFi security data through EFI Supplicant Protocol and/ or EFI EAP Configuration Protocol before calling ConnectNetwork() function.
Related Definitions
//**********************************************
// EFI_80211_CONNECT_NETWORK_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
EFI_80211_CONNECT_NETWORK_DATA *Data;
EFI_80211_CONNECT_NETWORK_RESULT_CODE ResultCode;
} EFI_80211_CONNECT_NETWORK_TOKEN;
- Event
If the status code returned by ConnectNetwork() is EFI_SUCCESS, then this Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol II driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_SUCCESS: The operation completed successfully.EFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED: The operation is not completed due to some underlying hardware or software state.EFI_NOT_READY: The operation is started but not yet completed.- Data
Pointer to the connection data. Type EFI_80211_CONNECT_NETWORK_DATA is defined below.
- ResultCode
Indicates the connection state. Type EFI_80211_CONNECT_NETWORK_RESULT_CODE is defined below.
The EFI_80211_CONNECT_NETWORK_TOKEN structure is defined to support the process of determining the characteristics of the available networks. As input, the Data field must be filled in by the caller of EFI Wireless MAC Connection II Protocol. After the operation completes, the EFI Wireless MAC Connection II Protocol driver updates the Status and ResultCode field and the Event is signaled.
//**********************************************
// EFI_80211_CONNECT_NETWORK_DATA
//**********************************************
typedef struct {
EFI_80211_NETWORK *Network;
UINT32 FailureTimeout;
} EFI_80211_CONNECT_NETWORK_DATA;
- Network
Specifies the wireless network to connect to. Type EFI_80211_NETWORK is defined above.
- FailureTimeout
Specifies a time limit in seconds that is optionally present, after which the connection establishment procedure is terminated by the UNDI driver. This is an optional parameter and may be 0. Values of 5 seconds or higher are recommended.
//**********************************************
// EFI_80211_CONNECT_NETWORK_RESULT_CODE
//**********************************************
typedef enum {
ConnectSuccess,
ConnectRefused,
ConnectFailed,
ConnectFailureTimeout,
ConnectFailedReasonUnspecified
} EFI_80211_CONNECT_NETWORK_RESULT_CODE;
- ConnectSuccess
The connection establishment operation finished successfully.
- ConnectRefused
The connection was refused by the Network.
- ConnectFailed
The connection establishment operation failed (i.e, Network is not detected).
- ConnectFailureTimeout
The connection establishment operation was terminated on timeout.
- ConnectFailedReasonUnspecified
The connection establishment operation failed on other reason.
Status Codes Returned
EFI_SUCCESS |
The operation started successfully. Results will be notified eventually. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
This is NULL.
Token is NULL.
|
EFI_UNSUPPORTED |
One or more of the input parameters are not supported by this implementation. |
EFI_ALREADY_STARTED |
The connection process is already started. |
EFI_NOT_FOUND |
The specified wireless network is not found. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.4.4. EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL.DisconnectNetwork()¶
Summary
Request a disconnection with current connected wireless network.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_WIRELESS_MAC_CONNECTION_II_DISCONNECT_NETWORK)(
IN EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL *This,
IN EFI_80211_DISCONNECT_NETWORK_TOKEN *Token
);
Parameters
- This
Pointer to the EFI_WIRELESS_MAC_CONNECTION_II_PROTOCOL instance.
- Token
Pointer to the token for disconnecting wireless network. Type EFI_80211_DISCONNECT_NETWORK_TOKEN is defined in Related Definitions below.
Description
The DisconnectNetwork() function places a request to wireless UNDI driver to disconnect from the wireless network it is connected to. This function will trigger the wireless UNDI driver to perform disassociation and deauthentication process to terminate an existing connection. This function is always non-blocking. After wireless UNDI driver received acknowledgment frame from AP and freed up corresponding resources, the Token->Event will be signaled and Token->Status will be updated accordingly.
Related Definitions
//**********************************************
// EFI_80211_DISCONNECT_NETWORK_TOKEN
//**********************************************
typedef struct {
EFI_EVENT Event;
EFI_STATUS Status;
} EFI_80211_DISCONNECT_NETWORK_TOKEN;
- Event
If the status code returned by DisconnectNetwork() is EFI_SUCCESS, then this Event will be signaled after the Status field is updated by the EFI Wireless MAC Connection Protocol II driver. The type of Event must be EFI_NOTIFY_SIGNAL.
- Status
Will be set to one of the following values:
EFI_SUCCESS: The operation completed successfullyEFI_DEVICE_ERROR: An unexpected network or system error occurred.EFI_ACCESS_DENIED: The operation is not completed due to some underlying hardware or software state.
Status Codes Returned
EFI_SUCCESS |
The operation started successfully. Results will be notified eventually. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
This is NULL.
Token is NULL.
|
EFI_UNSUPPORTED |
One or more of the input parameters are not supported by this implementation. |
EFI_NOT_FOUND |
Not connected to a wireless network. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.5. EFI Supplicant Protocol¶
This section defines the EFI Supplicant Protocol.
27.5.1. Supplicant Service Binding Protocol¶
27.5.2. EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL¶
Summary
The EFI Supplicant Service Binding Protocol is used to locate EFI Supplicant Protocol drivers to create and destroy child of the driver to communicate with other host using Supplicant protocol.
GUID
#define EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL_GUID \
{ 0x45bcd98e, 0x59ad, 0x4174, \
{ 0x95, 0x46, 0x34, 0x4a, 0x7, 0x48, 0x58, 0x98 }}
Description
A module that requires supplicant services can call one of the protocol handler services, such as BS->LocateHandleBuffer(), to search devices that publish an EFI Supplicant Service Binding Protocol GUID. Such device supports the EFI Supplicant Protocol and may be available for use. After a successful call to the EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL.CreateChild() function, the newly created child EFI Supplicant Protocol driver is in an un-configured state; it is not ready to do any operation until configured via SetData(). Every successful call to the EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL.CreateChild() function must be matched with a call to the EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL.DestroyChild() function to release the protocol driver.
27.5.3. Supplicant Protocol¶
27.5.4. EFI_SUPPLICANT_PROTOCOL¶
Summary
This protocol provides services to process authentication and data encryption/decryption for security management.
GUID
#define EFI_SUPPLICANT_PROTOCOL_GUID \
{ 0x54fcc43e, 0xaa89, 0x4333, \
{ 0x9a, 0x85, 0xcd, 0xea, 0x24, 0x5, 0x1e, 0x9e }}
Protocol Interface Structure
typedef struct _EFI_SUPPLICANT_PROTOCOL {
EFI_SUPPLICANT_BUILD_RESPONSE_PACKET BuildResponsePacket;
EFI_SUPPLICANT_PROCESS_PACKET ProcessPacket;
EFI_SUPPLICANT_SET_DATA SetData;
EFI_SUPPLICANT_GET_DATA GetData;
} EFI_SUPPLICANT_PROTOCOL;
Parameters
- BuildResponsePacket
This API processes security data for handling key management. See the BuildResponsePacket() function description.
- ProcessPacket
This API processes frame for encryption or decryption. See the ProcessPacket() function description.
- SetData
This API sets the information needed during key generated in handshake. See the SetData() function description.
- GetData
This API gets the information generated in handshake. See the GetData() function description.
Description
The EFI_SUPPLICANT_PROTOCOL is designed to provide unified place for WIFI and EAP security management. Both PSK authentication and 802.1X EAP authentication can be managed via this protocol and driver or application as a consumer can only focus on about packet transmitting or receiving. For 802.1X EAP authentication, an instance of EFI_EAP_CONFIGURATION_PROTOCOL must be installed to the same handle as the EFI Supplicant Protocol.
27.5.5. EFI_SUPPLICANT_PROTOCOL.BuildResponsePacket()¶
Summary
BuildResponsePacket() is called during STA and AP authentication is in progress. Supplicant derives the PTK or session keys depend on type of authentication is being employed.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_SUPPLICANT_BUILD_RESPONSE_PACKET)(
IN EFI_SUPPLICANT_PROTOCOL *This,
IN UINT8 *RequestBuffer, OPTIONAL
IN UINTN RequestBufferSize, OPTIONAL
OUT UINT8 *Buffer,
IN OUT UINTN *BufferSize
);
Parameters
- This
Pointer to the EFI_SUPPLICANT_PROTOCOL instance.
- RequestBuffer
Pointer to the most recently received EAPOL packet. NULL means the supplicant need initiate the EAP authentication session and send EAPOL-Start message.
- RequestSize
Packet size in bytes for the most recently received EAPOL packet. 0 is only valid when RequestBuffer is NULL.
- Buffer
Pointer to the buffer to hold the built packet.
- BufferSize
Pointer to the buffer size in bytes. On input, it is the buffer size provided by the caller. On output, it is the buffer size in fact needed to contain the packet.
Description
The consumer calls BuildResponsePacket() when it receives the security frame. It simply passes the data to supplicant to process the data. It could be WPA-PSK which starts the 4-way handshake, or WPA-EAP first starts with Authentication process and then 4-way handshake, or 2-way group key handshake. In process of authentication, 4-way handshake or group key handshake, Supplicant needs to communicate with its peer (AP/AS) to fill the output buffer parameter. Once the 4 way handshake or group key handshake is over, and PTK (Pairwise Transient keys) and GTK (Group Temporal Key) are generated.
Status Codes Returned
EFI_SUCCESS |
The required EAPOL packet is built successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• RequestBuffer is NULL, but RequestSize is NOT 0.
• RequestSize is 0.
• Buffer is NULL, but RequestBuffer is NOT 0.
• RequestSize is 0.
• BufferSize is NULL.
|
EFI_BUFFER_TOO_SMALL |
BufferSize is too small to hold the response packet. |
EFI_NOT_READY |
Current EAPOL session state is NOT ready to build ResponsePacket. |
27.5.6. EFI_SUPPLICANT_PROTOCOL.ProcessPacket()¶
Summary
ProcessPacket() is called to Supplicant driver to encrypt or decrypt the data depending type of authentication type.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_SUPPLICANT_PROCESS_PACKET)(
IN EFI_SUPPLICANT_PROTOCOL *This,
IN OUT EFI_SUPPLICANT_FRAGMENT_DATA **FragmentTable,
IN UINT32 *FragmentCount,
IN EFI_SUPPLICANT_CRYPT_MODE CryptMode
);
Parameters
- This
Pointer to the EFI_SUPPLICANT_PROTOCOL instance.
- FragmentTable
Pointer to a list of fragment. The caller will take responsible to handle the original FragmentTable while it may be reallocated in Supplicant driver.
- FragmentCount
Number of fragment.
- CryptMode
Crypt mode.
Description
ProcessPacket() is responsible for encrypting or decrypting the data traffic as per authentication type. The consumer routes the data frame as it is to Supplicant module and encrypts or decrypts packet with updated length comes as output parameter. Supplicant holds the derived PTK and GTKs and uses this key to encrypt or decrypt the network traffic.
If the Supplicant driver does not support any encryption and decryption algorithm, then EFI_UNSUPPORTED is returned.
Related Definitions
//************************************************************
// EFI_SUPPLICANT_FRAGMENT_DATA
//************************************************************
typedef struct {
UINT32 FragmentLength;
VOID *FragmentBuffer;
} EFI_SUPPLICANT_FRAGMENT_DATA;
- FragmentLength
Length of data buffer in the fragment.
- FragmentBuffer
Pointer to the data buffer in the fragment.
//***********************************************************
// EFI_SUPPLICANT_CRYPT_MODE
//***********************************************************
typedef enum {
EfiSupplicantEncrypt,
EfiSupplicantDecrypt,
} EFI_SUPPLICANT_CRYPT_MODE;
- EfiSupplicantEncrypt
Encrypt data provided in the fragment buffers.
- EfiSupplicantDecrypt
Decrypt data provided in the fragment buffers.
Status Codes Returned
EFI_SUCCESS |
The operation completed successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• FragmentTable is NULL.
• FragmentCount is NULL.
• CryptMode is invalid.
|
EFI_NOT_READY |
Current supplicant state is NOT Authenticated. |
EFI_ABORTED |
Something wrong decryption the message. |
EFI_UNSUPPORTED |
This API is not supported. |
27.5.7. EFI_SUPPLICANT_PROTOCOL.SetData()¶
Summary
Set Supplicant configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_SUPPLICANT_SET_DATA)(
IN EFI_SUPPLICANT_PROTOCOL *This,
IN EFI_SUPPLICANT_DATA_TYPE DataType,
IN VOID *Data,
IN UINTN DataSize
);
Parameters
- This
Pointer to the EFI_ SUPPLICANT _PROTOCOL instance.
- DataType
The type of data.
- Data
Pointer to the buffer to hold the data.
- DataSize
Pointer to the buffer size in bytes.
Description
The SetData() function sets Supplicant configuration. For example, Supplicant driver need to know Password and TargetSSIDName to calculate PSK. Supplicant driver need to know StationMac and TargetSSIDMac to calculate PTK. Then it can derive KCK(key confirmation key) which is needed to calculate MIC, and KEK(key encryption key) which is needed to unwrap GTK.
Related Definitions
//************************************************************
// EFI_SUPPLICANT_DATA_TYPE
//************************************************************
typedef enum {
//
// Session Configuration
//
EfiSupplicant80211AKMSuite,
EfiSupplicant80211GroupDataCipherSuite,
EfiSupplicant80211PairwiseCipherSuite,
EfiSupplicant80211PskPassword,
EfiSupplicant80211TargetSSIDName,
EfiSupplicant80211StationMac,
EfiSupplicant80211TargetSSIDMac,
//
// Session Information
//
EfiSupplicant80211PTK,
EfiSupplicant80211GTK,
EfiSupplicantState,
EfiSupplicant80211LinkState,
EfiSupplicantKeyRefresh,
//
// Session Configuration
//
EfiSupplicant80211SupportedAKMSuites,
EfiSupplicant80211SupportedSoftwareCipherSuites,
EfiSupplicant80211SupportedHardwareCipherSuites,
//
// Session Information
//
EfiSupplicant80211IGTK,
EfiSupplicant80211PMK,
EfiSupplicantDataTypeMaximum
} EFI_SUPPLICANT_DATA_TYPE;
- EfiSupplicant80211AKMSuite
Current authentication type in use. The corresponding Data is of type EFI_80211_AKM_SUITE_SELECTOR.
- EfiSupplicant80211GroupDataCipherSuite
Group data encryption type in use. The corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.
- EfiSupplicant80211PairwiseCipherSuite
Pairwise encryption type in use. The corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.
- EfiSupplicant80211PskPassword
PSK password. The corresponding Data is a NULL-terminated ASCII string.
- EfiSupplicant80211TargetSSIDName
Target SSID name. The corresponding Data is of type EFI_80211_SSID.
- EfiSupplicant80211StationMac
Station MAC address. The corresponding Data is of type EFI_80211_MAC_ADDRESS.
- EfiSupplicant80211TargetSSIDMac
Target SSID MAC address. The corresponding Data is 6 bytes MAC address.
- EfiSupplicant80211PTK
802.11 PTK. The corresponding Data is of type EFI_SUPPLICANT_KEY.
- EfiSupplicant80211GTK
802.11 GTK. The corresponding Data is of type EFI_SUPPLICANT_GTK_LIST.
- EfiSupplicantState
Supplicant state. The corresponding Data is EFI_EAPOL_SUPPLICANT_PAE_STATE.
- EfiSupplicant80211LinkState
802.11 link state. The corresponding Data is EFI_80211_LINK_STATE.
- EfiSupplicantKeyRefresh
Flag indicates key is refreshed. The corresponding Data is EFI_SUPPLICANT_KEY_REFRESH.
- EfiSupplicant80211SupportedAKMSuites
Supported authentication types. The corresponding Data is of type EFI_80211_AKM_SUITE_SELECTOR.
- EfiSupplicant80211SupportedSoftwareCipherSuites
Supported software encryption types provided by supplicant driver. The corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.
- EfiSupplicant80211SupportedHardwareCipherSuites
Supported hardware encryption types provided by wireless UNDI driver. The corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.
- EfiSupplicant80211IGTK
802.11 Integrity GTK. The corresponding Data is of type EFI_SUPPLICANT_GTK_LIST.
- EfiSupplicant80211IPMK
802.11 PMK. The corresponding Data is 32 bytes pairwise master key.
//**********************************************
// EFI_80211_LINK_STATE
//**********************************************
typedef enum {
Ieee80211UnauthenticatedUnassociated,
Ieee80211AuthenticatedUnassociated,
Ieee80211PendingRSNAuthentication,
Ieee80211AuthenticatedAssociated
} EFI_80211_LINK_STATE;
- Ieee80211UnauthenticatedUnassociated
Indicates initial start state, unauthenticated, unassociated.
- Ieee80211AuthenticatedUnassociated
Indicates authenticated, unassociated.
- Ieee80211PendingRSNAuthentication
Indicates authenticated and associated, but pending RSN authentication.
- Ieee80211AuthenticatedAssociated
Indicates authenticated and associated.
//**********************************************
// EFI_SUPPLICANT_KEY_REFRESH
//**********************************************
typedef struct {
BOOLEAN GTKRefresh;
} EFI_SUPPLICANT_KEY_REFRESH;
- GTKRefresh
If TRUE, indicates GTK is just refreshed after a successful call to EFI_SUPPLICANT_PROTOCOL.BuildResponsePacket().
//************************************************************
// EFI_SUPPLICANT_GTK_LIST
//************************************************************
typedef struct {
UINT8 GTKCount;
EFI_SUPPLICANT_KEY GTKList[1];
} EFI_SUPPLICANT_GTK_LIST;
- GTKCount
Indicates the number of GTKs that are contained in GTKList.
- GTKList
A variable-length array of GTKs of type EFI_SUPPLICANT_KEY. The number of entries is specified by GTKCount
#define EFI_MAX_KEY_LEN 64
//************************************************************
// EFI_SUPPLICANT_KEY
//************************************************************
typedef struct {
UINT8 Key[EFI_MAX_KEY_LEN];
UINT8 KeyLen;
UINT8 KeyId;
EFI_SUPPLICANT_KEY_TYPE KeyType;
EFI_80211_MAC_ADDRESS Addr;
UINT8 Rsc[8];
UINT8 RscLen;
BOOLEAN IsAuthenticator;
EFI_80211_SUITE_SELECTOR CipherSuite;
EFI_SUPPLICANT_KEY_DIRECTION Direction;
} EFI_SUPPLICANT_KEY;
The EFI_SUPPLICANT_KEY descriptor is defined in the IEEE 802.11 standard, section 6.3.19.1.2.
- Key
The key value.
- KeyLen
Length in bytes of the Key. Should be up to EFI_MAX_KEY_LEN.
- KeyId
The key identifier.
- KeyType
Defines whether this key is a group key, pairwise key, PeerKey, or Integrity Group.
- Addr
The value is set according to the KeyType.
- RSC
The Receive Sequence Count value.
- RscLen
Length in bytes of the Rsc. Should be up to 8.
- IsAuthenticator
Indicates whether the key is configured by the Authenticator or Supplicant. The value true indicates Authenticator.
- CipherSuite
The cipher suite required for this association.
- Direction
Indicates the direction for which the keys are to be installed.
//**********************************************
// EFI_SUPPLICANT_KEY_TYPE (IEEE Std 802.11
// Section 6.3.19.1.2)
//**********************************************
typedef enum {
Group,
Pairwise,
PeerKey,
IGTK
} EFI_SUPPLICANT_KEY_TYPE;
The EFI_SUPPLICANT_KEY_TYPE is defined in the IEEE 802.11 specification.
//**********************************************
// EFI_SUPPLICANT_KEY_DIRECTION (IEEE Std 802.11
// Section 6.3.19.1.2)
//**********************************************
typedef enum {
Receive,
Transmit,
Both
} EFI_SUPPLICANT_KEY_DIRECTION;
- Receive
Indicates that the keys are being installed for the receive direction.
- Transmit
Indicates that the keys are being installed for the transmit direction.
- Both
Indicates that the keys are being installed for both the receive and transmit directions.
Status Codes Returned
EFI_SUCCESS |
The Supplicant configuration data is set successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• Data is NULL.
• DataSize is 0.
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_OUT_OF_RESOURCES |
Required system resources could not be allocated. |
27.5.8. EFI_SUPPLICANT_PROTOCOL.GetData()¶
Summary
Get Supplicant configuration data.
Prototype
typedef
EFI_STATUS
(EFIAPI *EFI_SUPPLICANT_GET_DATA)(
IN EFI_SUPPLICANT_PROTOCOL *This,
IN EFI_SUPPLICANT_DATA_TYPE DataType,
OUT UINT8 *Data, OPTIONAL
IN OUT UINTN *DataSize
);
Parameters
- This
Pointer to the EFI_SUPPLICANT_PROTOCOL instance.
- DataType
The type of data.
- Data
Pointer to the buffer to hold the data. Ignored if DataSize is 0.
- DataSize
Pointer to the buffer size in bytes. On input, it is the buffer size provided by the caller. On output, it is the buffer size in fact needed to contain the packet.
Description
The GetData() function gets Supplicant configuration. The typical example is PTK and GTK derived from handshake. The wireless NIC can support software encryption or hardware encryption. If the consumer uses software encryption, it can call ProcessPacket() to get result. If the consumer supports hardware encryption, it can get PTK and GTK via GetData() and program to hardware register.
Status Codes Returned
EFI_SUCCESS |
The Supplicant configuration data is got successfully. |
EFI_INVALID_PARAMETER |
One or more of the following conditions is TRUE:
• This is NULL.
• DataSize is NULL.
• Data is NULL if DataSize is not zero.
|
EFI_UNSUPPORTED |
The DataType is unsupported. |
EFI_NOT_FOUND |
The Supplicant configuration data is not found. |
EFI_BUFFER_TOO_SMALL |
The size of Data is too small for the specified configuration data and the required size is returned in DataSize. |