--- /dev/null
+/** @file\r
+ This file defines the EFI Supplicant Protocol.\r
+\r
+ Copyright (c) 2016, Intel Corporation. All rights reserved.<BR>\r
+ This program and the accompanying materials\r
+ are licensed and made available under the terms and conditions of the BSD License\r
+ which accompanies this distribution. The full text of the license may be found at\r
+ http://opensource.org/licenses/bsd-license.php\r
+\r
+ THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
+ WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
+\r
+ @par Revision Reference:\r
+ This Protocol is introduced in UEFI Specification 2.6\r
+\r
+**/\r
+\r
+#ifndef __EFI_SUPPLICANT_PROTOCOL_H__\r
+#define __EFI_SUPPLICANT_PROTOCOL_H__\r
+\r
+#include <Protocol/WiFi2.h>\r
+\r
+///\r
+/// The EFI Supplicant Service Binding Protocol is used to locate EFI\r
+/// Supplicant Protocol drivers to create and destroy child of the driver to\r
+/// communicate with other host using Supplicant protocol.\r
+///\r
+#define EFI_SUPPLICANT_SERVICE_BINDING_PROTOCOL_GUID \\r
+ { \\r
+ 0x45bcd98e, 0x59ad, 0x4174, { 0x95, 0x46, 0x34, 0x4a, 0x7, 0x48, 0x58, 0x98 } \\r
+ }\r
+\r
+///\r
+/// The EFI Supplicant protocol provides services to process authentication and\r
+/// data encryption/decryption for security management.\r
+///\r
+#define EFI_SUPPLICANT_PROTOCOL_GUID \\r
+ { \\r
+ 0x54fcc43e, 0xaa89, 0x4333, { 0x9a, 0x85, 0xcd, 0xea, 0x24, 0x5, 0x1e, 0x9e } \\r
+ }\r
+\r
+typedef struct _EFI_SUPPLICANT_PROTOCOL EFI_SUPPLICANT_PROTOCOL;\r
+\r
+///\r
+/// EFI_SUPPLICANT_CRYPT_MODE\r
+///\r
+typedef enum {\r
+ //\r
+ // Encrypt data provided in the fragment buffers.\r
+ //\r
+ EfiSupplicantEncrypt,\r
+ //\r
+ // Decrypt data provided in the fragment buffers.\r
+ //\r
+ EfiSupplicantDecrypt,\r
+} EFI_SUPPLICANT_CRYPT_MODE;\r
+\r
+///\r
+/// EFI_SUPPLICANT_DATA_TYPE\r
+///\r
+typedef enum {\r
+ //\r
+ // Session Configuration\r
+ //\r
+\r
+ //\r
+ // Current authentication type in use. The corresponding Data is of type\r
+ // EFI_80211_AKM_SUITE_SELECTOR.\r
+ //\r
+ EfiSupplicant80211AKMSuite,\r
+ //\r
+ // Group data encryption type in use. The corresponding Data is of type\r
+ // EFI_SUPPLICANT_CIPHER_SUITE_SELECTOR.\r
+ //\r
+ EfiSupplicant80211GroupDataCipherSuite,\r
+ //\r
+ // Pairwise encryption type in use. The corresponding Data is of type\r
+ // EFI_80211_CIPHER_SUITE_SELECTOR.\r
+ //\r
+ EfiSupplicant80211PairwiseCipherSuite,\r
+ //\r
+ // PSK password. The corresponding Data is a NULL-terminated ASCII string.\r
+ //\r
+ EfiSupplicant80211PskPassword,\r
+ //\r
+ // Target SSID name. The corresponding Data is of type EFI_80211_SSID.\r
+ //\r
+ EfiSupplicant80211TargetSSIDName,\r
+ //\r
+ // Station MAC address. The corresponding Data is of type\r
+ // EFI_80211_MAC_ADDRESS.\r
+ //\r
+ EfiSupplicant80211StationMac,\r
+ //\r
+ // Target SSID MAC address. The corresponding Data is 6 bytes MAC address.\r
+ //\r
+ EfiSupplicant80211TargetSSIDMac,\r
+\r
+ //\r
+ // Session Information\r
+ //\r
+\r
+ //\r
+ // 802.11 PTK. The corresponding Data is of type EFI_SUPPLICANT_KEY.\r
+ //\r
+ EfiSupplicant80211PTK,\r
+ //\r
+ // 802.11 GTK. The corresponding Data is of type EFI_SUPPLICANT_GTK_LIST.\r
+ //\r
+ EfiSupplicant80211GTK,\r
+ //\r
+ // Supplicant state. The corresponding Data is\r
+ // EFI_EAPOL_SUPPLICANT_PAE_STATE.\r
+ //\r
+ EfiSupplicantState,\r
+ //\r
+ // 802.11 link state. The corresponding Data is EFI_80211_LINK_STATE.\r
+ //\r
+ EfiSupplicant80211LinkState,\r
+ //\r
+ // Flag indicates key is refreshed. The corresponding Data is\r
+ // EFI_SUPPLICANT_KEY_REFRESH.\r
+ //\r
+ EfiSupplicantKeyRefresh,\r
+\r
+ //\r
+ // Session Configuration\r
+ //\r
+\r
+ //\r
+ // Supported authentication types. The corresponding Data is of type\r
+ // EFI_80211_AKM_SUITE_SELECTOR.\r
+ //\r
+ EfiSupplicant80211SupportedAKMSuites,\r
+ //\r
+ // Supported software encryption types provided by supplicant driver. The\r
+ // corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.\r
+ //\r
+ EfiSupplicant80211SupportedSoftwareCipherSuites,\r
+ //\r
+ // Supported hardware encryption types provided by wireless UNDI driver. The\r
+ // corresponding Data is of type EFI_80211_CIPHER_SUITE_SELECTOR.\r
+ //\r
+ EfiSupplicant80211SupportedHardwareCipherSuites,\r
+\r
+ //\r
+ // Session Information\r
+ //\r
+\r
+ //\r
+ // 802.11 Integrity GTK. The corresponding Data is of type\r
+ // EFI_SUPPLICANT_GTK_LIST.\r
+ //\r
+ EfiSupplicant80211IGTK,\r
+ EfiSupplicantDataTypeMaximum\r
+} EFI_SUPPLICANT_DATA_TYPE;\r
+\r
+///\r
+/// EFI_80211_LINK_STATE\r
+///\r
+typedef enum {\r
+ //\r
+ // Indicates initial start state, unauthenticated, unassociated.\r
+ //\r
+ Ieee80211UnauthenticatedUnassociated,\r
+ //\r
+ // Indicates authenticated, unassociated.\r
+ //\r
+ Ieee80211AuthenticatedUnassociated,\r
+ //\r
+ // Indicates authenticated and associated, but pending RSN authentication.\r
+ //\r
+ Ieee80211PendingRSNAuthentication,\r
+ //\r
+ // Indicates authenticated and associated.\r
+ //\r
+ Ieee80211AuthenticatedAssociated\r
+} EFI_80211_LINK_STATE;\r
+\r
+///\r
+/// EFI_SUPPLICANT_KEY_TYPE (IEEE Std 802.11 Section 6.3.19.1.2)\r
+///\r
+typedef enum {\r
+ Group,\r
+ Pairwise,\r
+ PeerKey,\r
+ IGTK\r
+} EFI_SUPPLICANT_KEY_TYPE;\r
+\r
+///\r
+/// EFI_SUPPLICANT_KEY_DIRECTION (IEEE Std 802.11 Section 6.3.19.1.2)\r
+///\r
+typedef enum {\r
+ //\r
+ // Indicates that the keys are being installed for the receive direction.\r
+ //\r
+ Receive,\r
+ //\r
+ // Indicates that the keys are being installed for the transmit direction.\r
+ //\r
+ Transmit,\r
+ //\r
+ // Indicates that the keys are being installed for both the receive and\r
+ // transmit directions.\r
+ //\r
+ Both\r
+} EFI_SUPPLICANT_KEY_DIRECTION;\r
+\r
+///\r
+/// EFI_SUPPLICANT_KEY_REFRESH\r
+///\r
+typedef struct {\r
+ //\r
+ // If TRUE, indicates GTK is just refreshed after a successful call to\r
+ // EFI_SUPPLICANT_PROTOCOL.BuildResponsePacket().\r
+ //\r
+ BOOLEAN GTKRefresh;\r
+} EFI_SUPPLICANT_KEY_REFRESH;\r
+\r
+#define EFI_MAX_KEY_LEN 64\r
+\r
+///\r
+/// EFI_SUPPLICANT_KEY\r
+///\r
+typedef struct {\r
+ //\r
+ // The key value.\r
+ //\r
+ UINT8 Key[EFI_MAX_KEY_LEN];\r
+ //\r
+ // Length in bytes of the Key. Should be up to EFI_MAX_KEY_LEN.\r
+ //\r
+ UINT8 KeyLen;\r
+ //\r
+ // The key identifier.\r
+ //\r
+ UINT8 KeyId;\r
+ //\r
+ // Defines whether this key is a group key, pairwise key, PeerKey, or\r
+ // Integrity Group.\r
+ //\r
+ EFI_SUPPLICANT_KEY_TYPE KeyType;\r
+ //\r
+ // The value is set according to the KeyType.\r
+ //\r
+ EFI_80211_MAC_ADDRESS Addr;\r
+ //\r
+ // The Receive Sequence Count value.\r
+ //\r
+ UINT8 Rsc[8];\r
+ //\r
+ // Length in bytes of the Rsc. Should be up to 8.\r
+ //\r
+ UINT8 RscLen;\r
+ //\r
+ // Indicates whether the key is configured by the Authenticator or\r
+ // Supplicant. The value true indicates Authenticator.\r
+ //\r
+ BOOLEAN IsAuthenticator;\r
+ //\r
+ // The cipher suite required for this association.\r
+ //\r
+ EFI_80211_SUITE_SELECTOR CipherSuite;\r
+ //\r
+ // Indicates the direction for which the keys are to be installed.\r
+ //\r
+ EFI_SUPPLICANT_KEY_DIRECTION Direction;\r
+} EFI_SUPPLICANT_KEY;\r
+\r
+///\r
+/// EFI_SUPPLICANT_GTK_LIST\r
+///\r
+typedef struct {\r
+ //\r
+ // Indicates the number of GTKs that are contained in GTKList.\r
+ //\r
+ UINT8 GTKCount;\r
+ //\r
+ // A variable-length array of GTKs of type EFI_SUPPLICANT_KEY. The number of\r
+ // entries is specified by GTKCount.\r
+ //\r
+ EFI_SUPPLICANT_KEY GTKList[1];\r
+} EFI_SUPPLICANT_GTK_LIST;\r
+\r
+///\r
+/// EFI_SUPPLICANT_FRAGMENT_DATA\r
+///\r
+typedef struct {\r
+ //\r
+ // Length of data buffer in the fragment.\r
+ //\r
+ UINT32 FragmentLength;\r
+ //\r
+ // Pointer to the data buffer in the fragment.\r
+ //\r
+ VOID *FragmentBuffer;\r
+} EFI_SUPPLICANT_FRAGMENT_DATA;\r
+\r
+/**\r
+ BuildResponsePacket() is called during STA and AP authentication is in\r
+ progress. Supplicant derives the PTK or session keys depend on type of\r
+ authentication is being employed.\r
+\r
+ @param[in] This Pointer to the EFI_SUPPLICANT_PROTOCOL\r
+ instance.\r
+ @param[in] RequestBuffer Pointer to the most recently received EAPOL\r
+ packet. NULL means the supplicant need\r
+ initiate the EAP authentication session and\r
+ send EAPOL-Start message.\r
+ @param[in] RequestBufferSize\r
+ Packet size in bytes for the most recently\r
+ received EAPOL packet. 0 is only valid when\r
+ RequestBuffer is NULL.\r
+ @param[out] Buffer Pointer to the buffer to hold the built\r
+ packet.\r
+ @param[in, out] BufferSize Pointer to the buffer size in bytes. On\r
+ input, it is the buffer size provided by the\r
+ caller. On output, it is the buffer size in\r
+ fact needed to contain the packet.\r
+\r
+ @retval EFI_SUCCESS The required EAPOL packet is built\r
+ successfully.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is\r
+ TRUE:\r
+ RequestBuffer is NULL, but RequestSize is\r
+ NOT 0.\r
+ RequestBufferSize is 0.\r
+ Buffer is NULL, but RequestBuffer is NOT 0.\r
+ BufferSize is NULL.\r
+ @retval EFI_BUFFER_TOO_SMALL BufferSize is too small to hold the response\r
+ packet.\r
+ @retval EFI_NOT_READY Current EAPOL session state is NOT ready to\r
+ build ResponsePacket.\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_SUPPLICANT_BUILD_RESPONSE_PACKET) (\r
+ IN EFI_SUPPLICANT_PROTOCOL *This,\r
+ IN UINT8 *RequestBuffer, OPTIONAL\r
+ IN UINTN RequestBufferSize, OPTIONAL\r
+ OUT UINT8 *Buffer,\r
+ IN OUT UINTN *BufferSize\r
+ );\r
+\r
+/**\r
+ ProcessPacket() is called to Supplicant driver to encrypt or decrypt the data\r
+ depending type of authentication type.\r
+\r
+ @param[in] This Pointer to the EFI_SUPPLICANT_PROTOCOL\r
+ instance.\r
+ @param[in, out] FragmentTable Pointer to a list of fragment. The caller\r
+ will take responsible to handle the original\r
+ FragmentTable while it may be reallocated in\r
+ Supplicant driver.\r
+ @param[in] FragmentCount Number of fragment.\r
+ @param[in] CryptMode Crypt mode.\r
+\r
+ @retval EFI_SUCCESS The operation completed successfully.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is\r
+ TRUE:\r
+ FragmentTable is NULL.\r
+ FragmentCount is NULL.\r
+ CryptMode is invalid.\r
+ @retval EFI_NOT_READY Current supplicant state is NOT Authenticated.\r
+ @retval EFI_ABORTED Something wrong decryption the message.\r
+ @retval EFI_UNSUPPORTED This API is not supported.\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_SUPPLICANT_PROCESS_PACKET) (\r
+ IN EFI_SUPPLICANT_PROTOCOL *This,\r
+ IN OUT EFI_SUPPLICANT_FRAGMENT_DATA **FragmentTable,\r
+ IN UINT32 *FragmentCount,\r
+ IN EFI_SUPPLICANT_CRYPT_MODE CryptMode\r
+ );\r
+\r
+/**\r
+ Set Supplicant configuration data.\r
+\r
+ @param[in] This Pointer to the EFI_SUPPLICANT_PROTOCOL\r
+ instance.\r
+ @param[in] DataType The type of data.\r
+ @param[in] Data Pointer to the buffer to hold the data.\r
+ @param[in] DataSize Pointer to the buffer size in bytes.\r
+\r
+ @retval EFI_SUCCESS The Supplicant configuration data is set\r
+ successfully.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is\r
+ TRUE:\r
+ Data is NULL.\r
+ DataSize is 0.\r
+ @retval EFI_UNSUPPORTED The DataType is unsupported.\r
+ @retval EFI_OUT_OF_RESOURCES Required system resources could not be allocated.\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_SUPPLICANT_SET_DATA) (\r
+ IN EFI_SUPPLICANT_PROTOCOL *This,\r
+ IN EFI_SUPPLICANT_DATA_TYPE DataType,\r
+ IN VOID *Data,\r
+ IN UINTN DataSize\r
+ );\r
+\r
+/**\r
+ Get Supplicant configuration data.\r
+\r
+ @param[in] This Pointer to the EFI_SUPPLICANT_PROTOCOL\r
+ instance.\r
+ @param[in] DataType The type of data.\r
+ @param[out] Data Pointer to the buffer to hold the data.\r
+ Ignored if DataSize is 0.\r
+ @param[in, out] DataSize Pointer to the buffer size in bytes. On\r
+ input, it is the buffer size provided by the\r
+ caller. On output, it is the buffer size in\r
+ fact needed to contain the packet.\r
+\r
+ @retval EFI_SUCCESS The Supplicant configuration data is got\r
+ successfully.\r
+ @retval EFI_INVALID_PARAMETER One or more of the following conditions is\r
+ TRUE:\r
+ This is NULL.\r
+ DataSize is NULL.\r
+ Data is NULL if *DataSize is not zero.\r
+ @retval EFI_UNSUPPORTED The DataType is unsupported.\r
+ @retval EFI_NOT_FOUND The Supplicant configuration data is not\r
+ found.\r
+ @retval EFI_BUFFER_TOO_SMALL The size of Data is too small for the\r
+ specified configuration data and the required\r
+ size is returned in DataSize.\r
+\r
+**/\r
+typedef\r
+EFI_STATUS\r
+(EFIAPI *EFI_SUPPLICANT_GET_DATA) (\r
+ IN EFI_SUPPLICANT_PROTOCOL *This,\r
+ IN EFI_SUPPLICANT_DATA_TYPE DataType,\r
+ OUT UINT8 *Data, OPTIONAL\r
+ IN OUT UINTN *DataSize\r
+ );\r
+\r
+///\r
+/// The EFI_SUPPLICANT_PROTOCOL is designed to provide unified place for WIFI\r
+/// and EAP security management. Both PSK authentication and 802.1X EAP\r
+/// authentication can be managed via this protocol and driver or application\r
+/// as a consumer can only focus on about packet transmitting or receiving.\r
+///\r
+struct _EFI_SUPPLICANT_PROTOCOL {\r
+ EFI_SUPPLICANT_BUILD_RESPONSE_PACKET BuildResponsePacket;\r
+ EFI_SUPPLICANT_PROCESS_PACKET ProcessPacket;\r
+ EFI_SUPPLICANT_SET_DATA SetData;\r
+ EFI_SUPPLICANT_GET_DATA GetData;\r
+};\r
+\r
+extern EFI_GUID gEfiSupplicantServiceBindingProtocolGuid;\r
+extern EFI_GUID gEfiSupplicantProtocolGuid;\r
+\r
+#endif\r