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