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 461