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
33typedef 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///
46typedef 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///
68typedef 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///
92typedef 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///
120typedef 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**/
202typedef
203EFI_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**/
226typedef
227EFI_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**/
244typedef
245EFI_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**/
262typedef
263EFI_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**/
280typedef
281EFI_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**/
318typedef
319EFI_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**/
349typedef
350EFI_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**/
375typedef
376EFI_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///
389struct _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
400extern EFI_GUID gEfiEapManagementProtocolGuid;
401
402#endif
403
404