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