1 /** @file 2 EFI EAP Management Protocol Definition 3 The EFI EAP Management Protocol is designed to provide ease of management and 4 ease of test for EAPOL state machine. It is intended for the supplicant side. 5 It conforms to IEEE 802.1x specification. 6 The definitions in this file are defined in UEFI Specification 2.2, which have 7 not been verified by one implementation yet. 8 9 Copyright (c) 2009 - 2010, Intel Corporation. All rights reserved.<BR> 10 This program and the accompanying materials 11 are licensed and made available under the terms and conditions of the BSD License 12 which accompanies this distribution. The full text of the license may be found at 13 http://opensource.org/licenses/bsd-license.php 14 15 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS, 16 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED. 17 18 @par Revision Reference: 19 This Protocol is introduced in UEFI Specification 2.2 20 21 **/ 22 23 #ifndef __EFI_EAP_MANAGEMENT_PROTOCOL_H__ 24 #define __EFI_EAP_MANAGEMENT_PROTOCOL_H__ 25 26 #include <Protocol/Eap.h> 27 28 #define EFI_EAP_MANAGEMENT_PROTOCOL_GUID \ 29 { \ 30 0xbb62e663, 0x625d, 0x40b2, {0xa0, 0x88, 0xbb, 0xe8, 0x36, 0x23, 0xa2, 0x45 } \ 31 } 32 33 typedef struct _EFI_EAP_MANAGEMENT_PROTOCOL EFI_EAP_MANAGEMENT_PROTOCOL; 34 35 /// 36 /// PAE Capabilities 37 /// 38 ///@{ 39 #define PAE_SUPPORT_AUTHENTICATOR 0x01 40 #define PAE_SUPPORT_SUPPLICANT 0x02 41 ///@} 42 43 /// 44 /// EFI_EAPOL_PORT_INFO 45 /// 46 typedef struct _EFI_EAPOL_PORT_INFO { 47 /// 48 /// The identification number assigned to the Port by the System in 49 /// which the Port resides. 50 /// 51 EFI_PORT_HANDLE PortNumber; 52 /// 53 /// The protocol version number of the EAPOL implementation 54 /// supported by the Port. 55 /// 56 UINT8 ProtocolVersion; 57 /// 58 /// The capabilities of the PAE associated with the Port. This field 59 /// indicates whether Authenticator functionality, Supplicant 60 /// functionality, both, or neither, is supported by the Port's PAE. 61 /// 62 UINT8 PaeCapabilities; 63 } EFI_EAPOL_PORT_INFO; 64 65 /// 66 /// Supplicant PAE state machine (IEEE Std 802.1X Section 8.5.10) 67 /// 68 typedef enum _EFI_EAPOL_SUPPLICANT_PAE_STATE { 69 Logoff, 70 Disconnected, 71 Connecting, 72 Acquired, 73 Authenticating, 74 Held, 75 Authenticated, 76 MaxSupplicantPaeState 77 } EFI_EAPOL_SUPPLICANT_PAE_STATE; 78 79 /// 80 /// Definitions for ValidFieldMask 81 /// 82 ///@{ 83 #define AUTH_PERIOD_FIELD_VALID 0x01 84 #define HELD_PERIOD_FIELD_VALID 0x02 85 #define START_PERIOD_FIELD_VALID 0x04 86 #define MAX_START_FIELD_VALID 0x08 87 ///@} 88 89 /// 90 /// EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION 91 /// 92 typedef struct _EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION { 93 /// 94 /// Indicates which of the following fields are valid. 95 /// 96 UINT8 ValidFieldMask; 97 /// 98 /// The initial value for the authWhile timer. Its default value is 30s. 99 /// 100 UINTN AuthPeriod; 101 /// 102 /// The initial value for the heldWhile timer. Its default value is 60s. 103 /// 104 UINTN HeldPeriod; 105 /// 106 /// The initial value for the startWhen timer. Its default value is 30s. 107 /// 108 UINTN StartPeriod; 109 /// 110 /// The maximum number of successive EAPOL-Start messages will 111 /// be sent before the Supplicant assumes that there is no 112 /// Authenticator present. Its default value is 3. 113 /// 114 UINTN MaxStart; 115 } EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION; 116 117 /// 118 /// Supplicant Statistics (IEEE Std 802.1X Section 9.5.2) 119 /// 120 typedef struct _EFI_EAPOL_SUPPLICANT_PAE_STATISTICS { 121 /// 122 /// The number of EAPOL frames of any type that have been received by this Supplican. 123 /// 124 UINTN EapolFramesReceived; 125 /// 126 /// The number of EAPOL frames of any type that have been transmitted by this Supplicant. 127 /// 128 UINTN EapolFramesTransmitted; 129 /// 130 /// The number of EAPOL Start frames that have been transmitted by this Supplicant. 131 /// 132 UINTN EapolStartFramesTransmitted; 133 /// 134 /// The number of EAPOL Logoff frames that have been transmitted by this Supplicant. 135 /// 136 UINTN EapolLogoffFramesTransmitted; 137 /// 138 /// The number of EAP Resp/Id frames that have been transmitted by this Supplicant. 139 /// 140 UINTN EapRespIdFramesTransmitted; 141 /// 142 /// The number of valid EAP Response frames (other than Resp/Id frames) that have been 143 /// transmitted by this Supplicant. 144 /// 145 UINTN EapResponseFramesTransmitted; 146 /// 147 /// The number of EAP Req/Id frames that have been received by this Supplicant. 148 /// 149 UINTN EapReqIdFramesReceived; 150 /// 151 /// The number of EAP Request frames (other than Rq/Id frames) that have been received 152 /// by this Supplicant. 153 /// 154 UINTN EapRequestFramesReceived; 155 /// 156 /// The number of EAPOL frames that have been received by this Supplicant in which the 157 /// frame type is not recognized. 158 /// 159 UINTN InvalidEapolFramesReceived; 160 /// 161 /// The number of EAPOL frames that have been received by this Supplicant in which the 162 /// Packet Body Length field (7.5.5) is invalid. 163 /// 164 UINTN EapLengthErrorFramesReceived; 165 /// 166 /// The protocol version number carried in the most recently received EAPOL frame. 167 /// 168 UINTN LastEapolFrameVersion; 169 /// 170 /// The source MAC address carried in the most recently received EAPOL frame. 171 /// 172 UINTN LastEapolFrameSource; 173 } EFI_EAPOL_SUPPLICANT_PAE_STATISTICS; 174 175 /** 176 Read the system configuration information associated with the Port. 177 178 The GetSystemConfiguration() function reads the system configuration 179 information associated with the Port, including the value of the 180 SystemAuthControl parameter of the System is returned in SystemAuthControl 181 and the Port's information is returned in the buffer pointed to by PortInfo. 182 The Port's information is optional. 183 If PortInfo is NULL, then reading the Port's information is ignored. 184 185 If SystemAuthControl is NULL, then EFI_INVALID_PARAMETER is returned. 186 187 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 188 instance that indicates the calling context. 189 @param[out] SystemAuthControl Returns the value of the SystemAuthControl 190 parameter of the System. 191 TRUE means Enabled. FALSE means Disabled. 192 @param[out] PortInfo Returns EFI_EAPOL_PORT_INFO structure to describe 193 the Port's information. This parameter can be NULL 194 to ignore reading the Port's information. 195 196 @retval EFI_SUCCESS The system configuration information of the 197 Port is read successfully. 198 @retval EFI_INVALID_PARAMETER SystemAuthControl is NULL. 199 200 201 **/ 202 typedef 203 EFI_STATUS 204 (EFIAPI *EFI_EAP_GET_SYSTEM_CONFIGURATION)( 205 IN EFI_EAP_MANAGEMENT_PROTOCOL *This, 206 OUT BOOLEAN *SystemAuthControl, 207 OUT EFI_EAPOL_PORT_INFO *PortInfo OPTIONAL 208 ); 209 210 /** 211 Set the system configuration information associated with the Port. 212 213 The SetSystemConfiguration() function sets the value of the SystemAuthControl 214 parameter of the System to SystemAuthControl. 215 216 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 217 instance that indicates the calling context. 218 @param[in] SystemAuthControl The desired value of the SystemAuthControl 219 parameter of the System. 220 TRUE means Enabled. FALSE means Disabled. 221 222 @retval EFI_SUCCESS The system configuration information of the 223 Port is set successfully. 224 225 **/ 226 typedef 227 EFI_STATUS 228 (EFIAPI *EFI_EAP_SET_SYSTEM_CONFIGURATION)( 229 IN EFI_EAP_MANAGEMENT_PROTOCOL *This, 230 IN BOOLEAN SystemAuthControl 231 ); 232 233 /** 234 Cause the EAPOL state machines for the Port to be initialized. 235 236 The InitializePort() function causes the EAPOL state machines for the Port. 237 238 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 239 instance that indicates the calling context. 240 241 @retval EFI_SUCCESS The Port is initialized successfully. 242 243 **/ 244 typedef 245 EFI_STATUS 246 (EFIAPI *EFI_EAP_INITIALIZE_PORT)( 247 IN EFI_EAP_MANAGEMENT_PROTOCOL *This 248 ); 249 250 /** 251 Notify the EAPOL state machines for the Port that the user of the System has 252 logged on. 253 254 The UserLogon() function notifies the EAPOL state machines for the Port. 255 256 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 257 instance that indicates the calling context. 258 259 @retval EFI_SUCCESS The Port is notified successfully. 260 261 **/ 262 typedef 263 EFI_STATUS 264 (EFIAPI *EFI_EAP_USER_LOGON)( 265 IN EFI_EAP_MANAGEMENT_PROTOCOL *This 266 ); 267 268 /** 269 Notify the EAPOL state machines for the Port that the user of the System has 270 logged off. 271 272 The UserLogoff() function notifies the EAPOL state machines for the Port. 273 274 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 275 instance that indicates the calling context. 276 277 @retval EFI_SUCCESS The Port is notified successfully. 278 279 **/ 280 typedef 281 EFI_STATUS 282 (EFIAPI *EFI_EAP_USER_LOGOFF)( 283 IN EFI_EAP_MANAGEMENT_PROTOCOL *This 284 ); 285 286 /** 287 Read the status of the Supplicant PAE state machine for the Port, including the 288 current state and the configuration of the operational parameters. 289 290 The GetSupplicantStatus() function reads the status of the Supplicant PAE state 291 machine for the Port, including the current state CurrentState and the configuration 292 of the operational parameters Configuration. The configuration of the operational 293 parameters is optional. If Configuration is NULL, then reading the configuration 294 is ignored. The operational parameters in Configuration to be read can also be 295 specified by Configuration.ValidFieldMask. 296 297 If CurrentState is NULL, then EFI_INVALID_PARAMETER is returned. 298 299 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 300 instance that indicates the calling context. 301 @param[out] CurrentState Returns the current state of the Supplicant PAE 302 state machine for the Port. 303 @param[in, out] Configuration Returns the configuration of the operational 304 parameters of the Supplicant PAE state machine 305 for the Port as required. This parameter can be 306 NULL to ignore reading the configuration. 307 On input, Configuration.ValidFieldMask specifies the 308 operational parameters to be read. 309 On output, Configuration returns the configuration 310 of the required operational parameters. 311 312 @retval EFI_SUCCESS The configuration of the operational parameter 313 of the Supplicant PAE state machine for the Port 314 is set successfully. 315 @retval EFI_INVALID_PARAMETER CurrentState is NULL. 316 317 **/ 318 typedef 319 EFI_STATUS 320 (EFIAPI *EFI_EAP_GET_SUPPLICANT_STATUS)( 321 IN EFI_EAP_MANAGEMENT_PROTOCOL *This, 322 OUT EFI_EAPOL_SUPPLICANT_PAE_STATE *CurrentState, 323 IN OUT EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION *Configuration OPTIONAL 324 ); 325 326 /** 327 Set the configuration of the operational parameter of the Supplicant PAE 328 state machine for the Port. 329 330 The SetSupplicantConfiguration() function sets the configuration of the 331 operational Parameter of the Supplicant PAE state machine for the Port to 332 Configuration. The operational parameters in Configuration to be set can be 333 specified by Configuration.ValidFieldMask. 334 335 If Configuration is NULL, then EFI_INVALID_PARAMETER is returned. 336 337 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 338 instance that indicates the calling context. 339 @param[in] Configuration The desired configuration of the operational 340 parameters of the Supplicant PAE state machine 341 for the Port as required. 342 343 @retval EFI_SUCCESS The configuration of the operational parameter 344 of the Supplicant PAE state machine for the Port 345 is set successfully. 346 @retval EFI_INVALID_PARAMETER Configuration is NULL. 347 348 **/ 349 typedef 350 EFI_STATUS 351 (EFIAPI *EFI_EAP_SET_SUPPLICANT_CONFIGURATION)( 352 IN EFI_EAP_MANAGEMENT_PROTOCOL *This, 353 IN EFI_EAPOL_SUPPLICANT_PAE_CONFIGURATION *Configuration 354 ); 355 356 /** 357 Read the statistical information regarding the operation of the Supplicant 358 associated with the Port. 359 360 The GetSupplicantStatistics() function reads the statistical information 361 Statistics regarding the operation of the Supplicant associated with the Port. 362 363 If Statistics is NULL, then EFI_INVALID_PARAMETER is returned. 364 365 @param[in] This A pointer to the EFI_EAP_MANAGEMENT_PROTOCOL 366 instance that indicates the calling context. 367 @param[out] Statistics Returns the statistical information regarding the 368 operation of the Supplicant for the Port. 369 370 @retval EFI_SUCCESS The statistical information regarding the operation 371 of the Supplicant for the Port is read successfully. 372 @retval EFI_INVALID_PARAMETER Statistics is NULL. 373 374 **/ 375 typedef 376 EFI_STATUS 377 (EFIAPI *EFI_EAP_GET_SUPPLICANT_STATISTICS)( 378 IN EFI_EAP_MANAGEMENT_PROTOCOL *This, 379 OUT EFI_EAPOL_SUPPLICANT_PAE_STATISTICS *Statistics 380 ); 381 382 /// 383 /// EFI_EAP_MANAGEMENT_PROTOCOL 384 /// is used to control, configure and monitor EAPOL state machine on 385 /// a Port. EAPOL state machine is built on a per-Port basis. Herein, 386 /// a Port means a NIC. For the details of EAPOL, please refer to 387 /// IEEE 802.1x specification. 388 /// 389 struct _EFI_EAP_MANAGEMENT_PROTOCOL { 390 EFI_EAP_GET_SYSTEM_CONFIGURATION GetSystemConfiguration; 391 EFI_EAP_SET_SYSTEM_CONFIGURATION SetSystemConfiguration; 392 EFI_EAP_INITIALIZE_PORT InitializePort; 393 EFI_EAP_USER_LOGON UserLogon; 394 EFI_EAP_USER_LOGOFF UserLogoff; 395 EFI_EAP_GET_SUPPLICANT_STATUS GetSupplicantStatus; 396 EFI_EAP_SET_SUPPLICANT_CONFIGURATION SetSupplicantConfiguration; 397 EFI_EAP_GET_SUPPLICANT_STATISTICS GetSupplicantStatistics; 398 }; 399 400 extern EFI_GUID gEfiEapManagementProtocolGuid; 401 402 #endif 403 404