MdePkg/Include/Protocol/Supplicant.h

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