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   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   //
 156   // 802.11 PMK. The corresponding Data is 32 bytes pairwise master key.
 157   //
 158   EfiSupplicant80211PMK,
 159   EfiSupplicantDataTypeMaximum
 160 } EFI_SUPPLICANT_DATA_TYPE;
 161
 162 ///
 163 /// EFI_80211_LINK_STATE
 164 ///
 165 typedef enum {
 166   //
 167   // Indicates initial start state, unauthenticated, unassociated.
 168   //
 169   Ieee80211UnauthenticatedUnassociated,
 170   //
 171   // Indicates authenticated, unassociated.
 172   //
 173   Ieee80211AuthenticatedUnassociated,
 174   //
 175   // Indicates authenticated and associated, but pending RSN authentication.
 176   //
 177   Ieee80211PendingRSNAuthentication,
 178   //
 179   // Indicates authenticated and associated.
 180   //
 181   Ieee80211AuthenticatedAssociated
 182 } EFI_80211_LINK_STATE;
 183
 184 ///
 185 /// EFI_SUPPLICANT_KEY_TYPE (IEEE Std 802.11 Section 6.3.19.1.2)
 186 ///
 187 typedef enum {
 188   Group,
 189   Pairwise,
 190   PeerKey,
 191   IGTK
 192 } EFI_SUPPLICANT_KEY_TYPE;
 193
 194 ///
 195 /// EFI_SUPPLICANT_KEY_DIRECTION (IEEE Std 802.11 Section 6.3.19.1.2)
 196 ///
 197 typedef enum {
 198   //
 199   // Indicates that the keys are being installed for the receive direction.
 200   //
 201   Receive,
 202   //
 203   // Indicates that the keys are being installed for the transmit direction.
 204   //
 205   Transmit,
 206   //
 207   // Indicates that the keys are being installed for both the receive and
 208   // transmit directions.
 209   //
 210   Both
 211 } EFI_SUPPLICANT_KEY_DIRECTION;
 212
 213 ///
 214 /// EFI_SUPPLICANT_KEY_REFRESH
 215 ///
 216 typedef struct {
 217   //
 218   // If TRUE, indicates GTK is just refreshed after a successful call to
 219   // EFI_SUPPLICANT_PROTOCOL.BuildResponsePacket().
 220   //
 221   BOOLEAN                                 GTKRefresh;
 222 } EFI_SUPPLICANT_KEY_REFRESH;
 223
 224 #define EFI_MAX_KEY_LEN 64
 225
 226 ///
 227 /// EFI_SUPPLICANT_KEY
 228 ///
 229 typedef struct {
 230   //
 231   // The key value.
 232   //
 233   UINT8                                   Key[EFI_MAX_KEY_LEN];
 234   //
 235   // Length in bytes of the Key. Should be up to EFI_MAX_KEY_LEN.
 236   //
 237   UINT8                                   KeyLen;
 238   //
 239   // The key identifier.
 240   //
 241   UINT8                                   KeyId;
 242   //
 243   // Defines whether this key is a group key, pairwise key, PeerKey, or
 244   // Integrity Group.
 245   //
 246   EFI_SUPPLICANT_KEY_TYPE                 KeyType;
 247   //
 248   // The value is set according to the KeyType.
 249   //
 250   EFI_80211_MAC_ADDRESS                   Addr;
 251   //
 252   // The Receive Sequence Count value.
 253   //
 254   UINT8                                   Rsc[8];
 255   //
 256   // Length in bytes of the Rsc. Should be up to 8.
 257   //
 258   UINT8                                   RscLen;
 259   //
 260   // Indicates whether the key is configured by the Authenticator or
 261   // Supplicant. The value true indicates Authenticator.
 262   //
 263   BOOLEAN                                 IsAuthenticator;
 264   //
 265   // The cipher suite required for this association.
 266   //
 267   EFI_80211_SUITE_SELECTOR                CipherSuite;
 268   //
 269   // Indicates the direction for which the keys are to be installed.
 270   //
 271   EFI_SUPPLICANT_KEY_DIRECTION            Direction;
 272 } EFI_SUPPLICANT_KEY;
 273
 274 ///
 275 /// EFI_SUPPLICANT_GTK_LIST
 276 ///
 277 typedef struct {
 278   //
 279   // Indicates the number of GTKs that are contained in GTKList.
 280   //
 281   UINT8                                   GTKCount;
 282   //
 283   // A variable-length array of GTKs of type EFI_SUPPLICANT_KEY. The number of
 284   // entries is specified by GTKCount.
 285   //
 286   EFI_SUPPLICANT_KEY                      GTKList[1];
 287 } EFI_SUPPLICANT_GTK_LIST;
 288
 289 ///
 290 /// EFI_SUPPLICANT_FRAGMENT_DATA
 291 ///
 292 typedef struct {
 293   //
 294   // Length of data buffer in the fragment.
 295   //
 296   UINT32                                  FragmentLength;
 297   //
 298   // Pointer to the data buffer in the fragment.
 299   //
 300   VOID                                    *FragmentBuffer;
 301 } EFI_SUPPLICANT_FRAGMENT_DATA;
 302
 303 /**
 304   BuildResponsePacket() is called during STA and AP authentication is in
 305   progress. Supplicant derives the PTK or session keys depend on type of
 306   authentication is being employed.
 307
 308   @param[in]       This           Pointer to the EFI_SUPPLICANT_PROTOCOL
 309                                   instance.
 310   @param[in]       RequestBuffer  Pointer to the most recently received EAPOL
 311                                   packet. NULL means the supplicant need
 312                                   initiate the EAP authentication session and
 313                                   send EAPOL-Start message.
 314   @param[in]       RequestBufferSize
 315                                   Packet size in bytes for the most recently
 316                                   received EAPOL packet. 0 is only valid when
 317                                   RequestBuffer is NULL.
 318   @param[out]      Buffer         Pointer to the buffer to hold the built
 319                                   packet.
 320   @param[in, out]  BufferSize     Pointer to the buffer size in bytes. On
 321                                   input, it is the buffer size provided by the
 322                                   caller. On output, it is the buffer size in
 323                                   fact needed to contain the packet.
 324
 325   @retval EFI_SUCCESS             The required EAPOL packet is built
 326                                   successfully.
 327   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 328                                   TRUE:
 329                                   RequestBuffer is NULL, but RequestSize is
 330                                   NOT 0.
 331                                   RequestBufferSize is 0.
 332                                   Buffer is NULL, but RequestBuffer is NOT 0.
 333                                   BufferSize is NULL.
 334   @retval EFI_BUFFER_TOO_SMALL    BufferSize is too small to hold the response
 335                                   packet.
 336   @retval EFI_NOT_READY           Current EAPOL session state is NOT ready to
 337                                   build ResponsePacket.
 338
 339 **/
 340 typedef
 341 EFI_STATUS
 342 (EFIAPI *EFI_SUPPLICANT_BUILD_RESPONSE_PACKET) (
 343   IN     EFI_SUPPLICANT_PROTOCOL          *This,
 344   IN     UINT8                            *RequestBuffer,     OPTIONAL
 345   IN     UINTN                            RequestBufferSize,  OPTIONAL
 346      OUT UINT8                            *Buffer,
 347   IN OUT UINTN                            *BufferSize
 348   );
 349
 350 /**
 351   ProcessPacket() is called to Supplicant driver to encrypt or decrypt the data
 352   depending type of authentication type.
 353
 354   @param[in]       This           Pointer to the EFI_SUPPLICANT_PROTOCOL
 355                                   instance.
 356   @param[in, out]  FragmentTable  Pointer to a list of fragment. The caller
 357                                   will take responsible to handle the original
 358                                   FragmentTable while it may be reallocated in
 359                                   Supplicant driver.
 360   @param[in]       FragmentCount  Number of fragment.
 361   @param[in]       CryptMode      Crypt mode.
 362
 363   @retval EFI_SUCCESS             The operation completed successfully.
 364   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 365                                   TRUE:
 366                                   FragmentTable is NULL.
 367                                   FragmentCount is NULL.
 368                                   CryptMode is invalid.
 369   @retval EFI_NOT_READY           Current supplicant state is NOT Authenticated.
 370   @retval EFI_ABORTED             Something wrong decryption the message.
 371   @retval EFI_UNSUPPORTED         This API is not supported.
 372
 373 **/
 374 typedef
 375 EFI_STATUS
 376 (EFIAPI *EFI_SUPPLICANT_PROCESS_PACKET) (
 377   IN     EFI_SUPPLICANT_PROTOCOL          *This,
 378   IN OUT EFI_SUPPLICANT_FRAGMENT_DATA     **FragmentTable,
 379   IN     UINT32                           *FragmentCount,
 380   IN     EFI_SUPPLICANT_CRYPT_MODE        CryptMode
 381   );
 382
 383 /**
 384   Set Supplicant configuration data.
 385
 386   @param[in]  This                Pointer to the EFI_SUPPLICANT_PROTOCOL
 387                                   instance.
 388   @param[in]  DataType            The type of data.
 389   @param[in]  Data                Pointer to the buffer to hold the data.
 390   @param[in]  DataSize            Pointer to the buffer size in bytes.
 391
 392   @retval EFI_SUCCESS             The Supplicant configuration data is set
 393                                   successfully.
 394   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 395                                   TRUE:
 396                                   Data is NULL.
 397                                   DataSize is 0.
 398   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 399   @retval EFI_OUT_OF_RESOURCES    Required system resources could not be allocated.
 400
 401 **/
 402 typedef
 403 EFI_STATUS
 404 (EFIAPI *EFI_SUPPLICANT_SET_DATA) (
 405   IN EFI_SUPPLICANT_PROTOCOL              *This,
 406   IN EFI_SUPPLICANT_DATA_TYPE             DataType,
 407   IN VOID                                 *Data,
 408   IN UINTN                                DataSize
 409   );
 410
 411 /**
 412   Get Supplicant configuration data.
 413
 414   @param[in]       This           Pointer to the EFI_SUPPLICANT_PROTOCOL
 415                                   instance.
 416   @param[in]       DataType       The type of data.
 417   @param[out]      Data           Pointer to the buffer to hold the data.
 418                                   Ignored if DataSize is 0.
 419   @param[in, out]  DataSize       Pointer to the buffer size in bytes. On
 420                                   input, it is the buffer size provided by the
 421                                   caller. On output, it is the buffer size in
 422                                   fact needed to contain the packet.
 423
 424   @retval EFI_SUCCESS             The Supplicant configuration data is got
 425                                   successfully.
 426   @retval EFI_INVALID_PARAMETER   One or more of the following conditions is
 427                                   TRUE:
 428                                   This is NULL.
 429                                   DataSize is NULL.
 430                                   Data is NULL if *DataSize is not zero.
 431   @retval EFI_UNSUPPORTED         The DataType is unsupported.
 432   @retval EFI_NOT_FOUND           The Supplicant configuration data is not
 433                                   found.
 434   @retval EFI_BUFFER_TOO_SMALL    The size of Data is too small for the
 435                                   specified configuration data and the required
 436                                   size is returned in DataSize.
 437
 438 **/
 439 typedef
 440 EFI_STATUS
 441 (EFIAPI *EFI_SUPPLICANT_GET_DATA) (
 442   IN     EFI_SUPPLICANT_PROTOCOL          *This,
 443   IN     EFI_SUPPLICANT_DATA_TYPE         DataType,
 444      OUT UINT8                            *Data,     OPTIONAL
 445   IN OUT UINTN                            *DataSize
 446   );
 447
 448 ///
 449 /// The EFI_SUPPLICANT_PROTOCOL is designed to provide unified place for WIFI
 450 /// and EAP security management. Both PSK authentication and 802.1X EAP
 451 /// authentication can be managed via this protocol and driver or application
 452 /// as a consumer can only focus on about packet transmitting or receiving.
 453 ///
 454 struct _EFI_SUPPLICANT_PROTOCOL {
 455   EFI_SUPPLICANT_BUILD_RESPONSE_PACKET    BuildResponsePacket;
 456   EFI_SUPPLICANT_PROCESS_PACKET           ProcessPacket;
 457   EFI_SUPPLICANT_SET_DATA                 SetData;
 458   EFI_SUPPLICANT_GET_DATA                 GetData;
 459 };
 460
 461 extern EFI_GUID gEfiSupplicantServiceBindingProtocolGuid;
 462 extern EFI_GUID gEfiSupplicantProtocolGuid;
 463
 464 #endif