MdePkg/Include/Protocol/EapManagement.h

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