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   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