MdePkg/Include/Protocol/Supplicant.h

   1 /** @file
   2   This file defines the EFI Supplicant Protocol.
   3
   4   Copyright (c) 2016 - 2017, Intel Corporation. All rights reserved.<BR>
   5   SPDX-License-Identifier: BSD-2-Clause-Patent
   6
   7   @par Revision Reference:
   8   This Protocol is introduced in UEFI Specification 2.6
   9
  10 **/
  11
  12 #ifndef __EFI_SUPPLICANT_PROTOCOL_H__
  13 #define __EFI_SUPPLICANT_PROTOCOL_H__
  14
  15 #include <Protocol/WiFi2.h>
  16
  17 ///
  18 /// The EFI Supplicant Service Binding Protocol is used to locate EFI
  19 /// Supplicant Protocol drivers to create and destroy child of the driver to
  20 /// communicate with other host using Supplicant protocol.
  21 ///
  22 #define EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL_GUID \
  23   { \
  24     0x45bcd98e, 0x59ad, 0x4174, { 0x95, 0x46, 0x34, 0x4a, 0x7, 0x48, 0x58, 0x98 } \
  25   }
  26
  27 ///
  28 /// The EFI Supplicant protocol provides services to process authentication and
  29 /// data encryption/decryption for security management.
  30 ///
  31 #define EFI_SUPPLICANT_PROTOCOL_GUID \
  32   { \
  33     0x54fcc43e, 0xaa89, 0x4333, { 0x9a, 0x85, 0xcd, 0xea, 0x24, 0x5, 0x1e, 0x9e } \
  34   }
  35
  36 typedef struct _EFI_SUPPLICANT_PROTOCOL EFI_SUPPLICANT_PROTOCOL;
  37
  38 ///
  39 /// EFI_SUPPLICANT_CRYPT_MODE
  40 ///
  41 typedef enum {
  42   //
  43   // Encrypt data provided in the fragment buffers.
  44   //
  45   EfiSupplicantEncrypt,
  46   //
  47   // Decrypt data provided in the fragment buffers.
  48   //
  49   EfiSupplicantDecrypt,
  50 } EFI_SUPPLICANT_CRYPT_MODE;
  51
  52 ///
  53 /// EFI_SUPPLICANT_DATA_TYPE
  54 ///
  55 typedef enum {
  56   //
  57   // Session Configuration
  58   //
  59
  60   //
  61   // Current authentication type in use. The corresponding Data is of type
  62   // EFI_80211_AKM_SUITE_SELECTOR.
  63   //
  64   EfiSupplicant80211AKMSuite,
  65   //
  66   // Group data encryption type in use. The corresponding Data is of type
  67   // EFI_SUPPLICANT_CIPHER_SUITE_SELECTOR.
  68   //
  69   EfiSupplicant80211GroupDataCipherSuite,
  70   //
  71   // Pairwise encryption type in use. The corresponding Data is of type
  72   // EFI_80211_CIPHER_SUITE_SELECTOR.
  73   //
  74   EfiSupplicant80211PairwiseCipherSuite,
  75   //
  76   // PSK password. The corresponding Data is a NULL-terminated ASCII string.
  77   //
  78   EfiSupplicant80211PskPassword,
  79   //
  80   // Target SSID name. The corresponding Data is of type EFI_80211_SSID.
  81   //
  82   EfiSupplicant80211TargetSSIDName,
  83   //
  84   // Station MAC address. The corresponding Data is of type
  85   // EFI_80211_MAC_ADDRESS.
  86   //
  87   EfiSupplicant80211StationMac,
  88   //
  89   // Target SSID MAC address. The corresponding Data is 6 bytes MAC address.
  90   //
  91   EfiSupplicant80211TargetSSIDMac,
  92
  93   //
  94   // Session Information
  95   //
  96
  97   //
  98   // 802.11 PTK. The corresponding Data is of type EFI_SUPPLICANT_KEY.
  99   //
 100   EfiSupplicant80211PTK,
 101   //
 102   // 802.11 GTK. The corresponding Data is of type EFI_SUPPLICANT_GTK_LIST.
 103   //
 104   EfiSupplicant80211GTK,
 105   //
 106   // Supplicant state. The corresponding Data is
 107   // EFI_EAPOL_SUPPLICANT_PAE_STATE.
 108   //
 109   EfiSupplicantState,
 110   //
 111   // 802.11 link state. The corresponding Data is EFI_80211_LINK_STATE.
 112   //
 113   EfiSupplicant80211LinkState,
 114   //
 115   // Flag indicates key is refreshed. The corresponding Data is
 116   // EFI_SUPPLICANT_KEY_REFRESH.
 117   //
 118   EfiSupplicantKeyRefresh,
 119
 120   //
 121   // Session Configuration
 122   //
 123
 124   //
 125   // Supported authentication types. The corresponding Data is of type
 126   // EFI_80211_AKM_SUITE_SELECTOR.
 127   //
 128   EfiSupplicant80211SupportedAKMSuites,
 129   //
 130   // Supported software encryption types provided by supplicant driver. The
 131   // corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.
 132   //
 133   EfiSupplicant80211SupportedSoftwareCipherSuites,
 134   //
 135   // Supported hardware encryption types provided by wireless UNDI driver. The
 136   // corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.
 137   //
 138   EfiSupplicant80211SupportedHardwareCipherSuites,
 139
 140   //
 141   // Session Information
 142   //
 143
 144   //
 145   // 802.11 Integrity GTK. The corresponding Data is of type
 146   // EFI_SUPPLICANT_GTK_LIST.
 147   //
 148   EfiSupplicant80211IGTK,
 149   //
 150   // 802.11 PMK. The corresponding Data is 32 bytes pairwise master key.
 151   //
 152   EfiSupplicant80211PMK,
 153   EfiSupplicantDataTypeMaximum
 154 } EFI_SUPPLICANT_DATA_TYPE;
 155
 156 ///
 157 /// EFI_80211_LINK_STATE
 158 ///
 159 typedef enum {
 160   //
 161   // Indicates initial start state, unauthenticated, unassociated.
 162   //
 163   Ieee80211UnauthenticatedUnassociated,
 164   //
 165   // Indicates authenticated, unassociated.
 166   //
 167   Ieee80211AuthenticatedUnassociated,
 168   //
 169   // Indicates authenticated and associated, but pending RSN authentication.
 170   //
 171   Ieee80211PendingRSNAuthentication,
 172   //
 173   // Indicates authenticated and associated.
 174   //
 175   Ieee80211AuthenticatedAssociated
 176 } EFI_80211_LINK_STATE;
 177
 178 ///
 179 /// EFI_SUPPLICANT_KEY_TYPE (IEEE Std 802.11 Section 6.3.19.1.2)
 180 ///
 181 typedef enum {
 182   Group,
 183   Pairwise,
 184   PeerKey,
 185   IGTK
 186 } EFI_SUPPLICANT_KEY_TYPE;
 187
 188 ///
 189 /// EFI_SUPPLICANT_KEY_DIRECTION (IEEE Std 802.11 Section 6.3.19.1.2)
 190 ///
 191 typedef enum {
 192   //
 193   // Indicates that the keys are being installed for the receive direction.
 194   //
 195   Receive,
 196   //
 197   // Indicates that the keys are being installed for the transmit direction.
 198   //
 199   Transmit,
 200   //
 201   // Indicates that the keys are being installed for both the receive and
 202   // transmit directions.
 203   //
 204   Both
 205 } EFI_SUPPLICANT_KEY_DIRECTION;
 206
 207 ///
 208 /// EFI_SUPPLICANT_KEY_REFRESH
 209 ///
 210 typedef struct {
 211   //
 212   // If TRUE, indicates GTK is just refreshed after a successful call to
 213   // EFI_SUPPLICANT_PROTOCOL.BuildResponsePacket().
 214   //
 215   BOOLEAN                                 GTKRefresh;
 216 } EFI_SUPPLICANT_KEY_REFRESH;
 217
 218 #define EFI_MAX_KEY_LEN 64
 219
 220 ///
 221 /// EFI_SUPPLICANT_KEY
 222 ///
 223 typedef struct {
 224   //
 225   // The key value.
 226   //
 227   UINT8                                   Key[EFI_MAX_KEY_LEN];
 228   //
 229   // Length in bytes of the Key. Should be up to EFI_MAX_KEY_LEN.
 230   //
 231   UINT8                                   KeyLen;
 232   //
 233   // The key identifier.
 234   //
 235   UINT8                                   KeyId;
 236   //
 237   // Defines whether this key is a group key, pairwise key, PeerKey, or
 238   // Integrity Group.
 239   //
 240   EFI_SUPPLICANT_KEY_TYPE                 KeyType;
 241   //
 242   // The value is set according to the KeyType.
 243   //
 244   EFI_80211_MAC_ADDRESS                   Addr;
 245   //
 246   // The Receive Sequence Count value.
 247   //
 248   UINT8                                   Rsc[8];
 249   //
 250   // Length in bytes of the Rsc. Should be up to 8.
 251   //
 252   UINT8                                   RscLen;
 253   //
 254   // Indicates whether the key is configured by the Authenticator or
 255   // Supplicant. The value true indicates Authenticator.
 256   //
 257   BOOLEAN                                 IsAuthenticator;
 258   //
 259   // The cipher suite required for this association.
 260   //
 261   EFI_80211_SUITE_SELECTOR                CipherSuite;
 262   //
 263   // Indicates the direction for which the keys are to be installed.
 264   //
 265   EFI_SUPPLICANT_KEY_DIRECTION            Direction;
 266 } EFI_SUPPLICANT_KEY;
 267
 268 ///
 269 /// EFI_SUPPLICANT_GTK_LIST
 270 ///
 271 typedef struct {
 272   //
 273   // Indicates the number of GTKs that are contained in GTKList.
 274   //
 275   UINT8                                   GTKCount;
 276   //
 277   // A variable-length array of GTKs of type EFI_SUPPLICANT_KEY. The number of
 278   // entries is specified by GTKCount.
 279   //
 280   EFI_SUPPLICANT_KEY                      GTKList[1];
 281 } EFI_SUPPLICANT_GTK_LIST;
 282
 283 ///
 284 /// EFI_SUPPLICANT_FRAGMENT_DATA
 285 ///
 286 typedef struct {
 287   //
 288   // Length of data buffer in the fragment.
 289   //
 290   UINT32                                  FragmentLength;
 291   //
 292   // Pointer to the data buffer in the fragment.
 293   //
 294   VOID                                    *FragmentBuffer;
 295 } EFI_SUPPLICANT_FRAGMENT_DATA;
 296
 297 /**
 298   BuildResponsePacket() is called during STA and AP authentication is in
 299   progress. Supplicant derives the PTK or session keys depend on type of
 300   authentication is being employed.
 301
 302   @param[in]       This           Pointer to the EFI_SUPPLICANT_PROTOCOL
 303                                   instance.
 304   @param[in]       RequestBuffer  Pointer to the most recently received EAPOL
 305                                   packet. NULL means the supplicant need
 306                                   initiate the EAP authentication session and
 307                                   send EAPOL-Start message.
 308   @param[in]       RequestBufferSize
 309                                   Packet size in bytes for the most recently
 310                                   received EAPOL packet. 0 is only valid when
 311                                   RequestBuffer is NULL.
 312   @param[out]      Buffer         Pointer to the buffer to hold the built
 313                                   packet.
 314   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On
 315                                   input, it is the buffer size provided by the
 316                                   caller. On output, it is the buffer size in
 317                                   fact needed to contain the packet.
 318
 319   @retval EFI_SUCCESS             The required EAPOL packet is built
 320                                   successfully.
 321   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 322                                   TRUE:
 323                                   RequestBuffer is NULL, but RequestSize is
 324                                   NOT 0.
 325                                   RequestBufferSize is 0.
 326                                   Buffer is NULL, but RequestBuffer is NOT 0.
 327                                   BufferSize is NULL.
 328   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response
 329                                   packet.
 330   @retval EFI_NOT_READY           Current EAPOL session state is NOT ready to
 331                                   build ResponsePacket.
 332
 333 **/
 334 typedef
 335 EFI_STATUS
 336 (EFIAPI *EFI_SUPPLICANT_BUILD_RESPONSE_PACKET) (
 337   IN     EFI_SUPPLICANT_PROTOCOL          *This,
 338   IN     UINT8                            *RequestBuffer,     OPTIONAL
 339   IN     UINTN                            RequestBufferSize,  OPTIONAL
 340      OUT UINT8                            *Buffer,
 341   IN OUT UINTN                            *BufferSize
 342   );
 343
 344 /**
 345   ProcessPacket() is called to Supplicant driver to encrypt or decrypt the data
 346   depending type of authentication type.
 347
 348   @param[in]       This           Pointer to the EFI_SUPPLICANT_PROTOCOL
 349                                   instance.
 350   @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller
 351                                   will take responsible to handle the original
 352                                   FragmentTable while it may be reallocated in
 353                                   Supplicant driver.
 354   @param[in]       FragmentCount  Number of fragment.
 355   @param[in]       CryptMode      Crypt mode.
 356
 357   @retval EFI_SUCCESS             The operation completed successfully.
 358   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 359                                   TRUE:
 360                                   FragmentTable is NULL.
 361                                   FragmentCount is NULL.
 362                                   CryptMode is invalid.
 363   @retval EFI_NOT_READY           Current supplicant state is NOT Authenticated.
 364   @retval EFI_ABORTED             Something wrong decryption the message.
 365   @retval EFI_UNSUPPORTED         This API is not supported.
 366
 367 **/
 368 typedef
 369 EFI_STATUS
 370 (EFIAPI *EFI_SUPPLICANT_PROCESS_PACKET) (
 371   IN     EFI_SUPPLICANT_PROTOCOL          *This,
 372   IN OUT EFI_SUPPLICANT_FRAGMENT_DATA     **FragmentTable,
 373   IN     UINT32                           *FragmentCount,
 374   IN     EFI_SUPPLICANT_CRYPT_MODE        CryptMode
 375   );
 376
 377 /**
 378   Set Supplicant configuration data.
 379
 380   @param[in]  This                Pointer to the EFI_SUPPLICANT_PROTOCOL
 381                                   instance.
 382   @param[in]  DataType            The type of data.
 383   @param[in]  Data                Pointer to the buffer to hold the data.
 384   @param[in]  DataSize            Pointer to the buffer size in bytes.
 385
 386   @retval EFI_SUCCESS             The Supplicant configuration data is set
 387                                   successfully.
 388   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 389                                   TRUE:
 390                                   Data is NULL.
 391                                   DataSize is 0.
 392   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 393   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 394
 395 **/
 396 typedef
 397 EFI_STATUS
 398 (EFIAPI *EFI_SUPPLICANT_SET_DATA) (
 399   IN EFI_SUPPLICANT_PROTOCOL              *This,
 400   IN EFI_SUPPLICANT_DATA_TYPE             DataType,
 401   IN VOID                                 *Data,
 402   IN UINTN                                DataSize
 403   );
 404
 405 /**
 406   Get Supplicant configuration data.
 407
 408   @param[in]       This           Pointer to the EFI_SUPPLICANT_PROTOCOL
 409                                   instance.
 410   @param[in]       DataType       The type of data.
 411   @param[out]      Data           Pointer to the buffer to hold the data.
 412                                   Ignored if DataSize is 0.
 413   @param[in, out]  DataSize       Pointer to the buffer size in bytes. On
 414                                   input, it is the buffer size provided by the
 415                                   caller. On output, it is the buffer size in
 416                                   fact needed to contain the packet.
 417
 418   @retval EFI_SUCCESS             The Supplicant configuration data is got
 419                                   successfully.
 420   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 421                                   TRUE:
 422                                   This is NULL.
 423                                   DataSize is NULL.
 424                                   Data is NULL if *DataSize is not zero.
 425   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 426   @retval EFI_NOT_FOUND           The Supplicant configuration data is not
 427                                   found.
 428   @retval EFI_BUFFER_TOO_SMALL    The size of Data is too small for the
 429                                   specified configuration data and the required
 430                                   size is returned in DataSize.
 431
 432 **/
 433 typedef
 434 EFI_STATUS
 435 (EFIAPI *EFI_SUPPLICANT_GET_DATA) (
 436   IN     EFI_SUPPLICANT_PROTOCOL          *This,
 437   IN     EFI_SUPPLICANT_DATA_TYPE         DataType,
 438      OUT UINT8                            *Data,     OPTIONAL
 439   IN OUT UINTN                            *DataSize
 440   );
 441
 442 ///
 443 /// The EFI_SUPPLICANT_PROTOCOL is designed to provide unified place for WIFI
 444 /// and EAP security management. Both PSK authentication and 802.1X EAP
 445 /// authentication can be managed via this protocol and driver or application
 446 /// as a consumer can only focus on about packet transmitting or receiving.
 447 ///
 448 struct _EFI_SUPPLICANT_PROTOCOL {
 449   EFI_SUPPLICANT_BUILD_RESPONSE_PACKET    BuildResponsePacket;
 450   EFI_SUPPLICANT_PROCESS_PACKET           ProcessPacket;
 451   EFI_SUPPLICANT_SET_DATA                 SetData;
 452   EFI_SUPPLICANT_GET_DATA                 GetData;
 453 };
 454
 455 extern EFI_GUID gEfiSupplicantServiceBindingProtocolGuid;
 456 extern EFI_GUID gEfiSupplicantProtocolGuid;
 457
 458 #endif