[wpa] Add general support for WPA-protected 802.11 networks
[people/cooldavid/gpxe.git] / src / include / gpxe / wpa.h
1 /*
2  * Copyright (c) 2009 Joshua Oreman <oremanj@rwcr.net>.
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License as
6  * published by the Free Software Foundation; either version 2 of the
7  * License, or any later version.
8  *
9  * This program is distributed in the hope that it will be useful, but
10  * WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
12  * General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
17  */
18
19 #ifndef _GPXE_WPA_H
20 #define _GPXE_WPA_H
21
22 #include <gpxe/ieee80211.h>
23 #include <gpxe/list.h>
24
25 FILE_LICENCE ( GPL2_OR_LATER );
26
27 /** @file
28  *
29  * Common definitions for all types of WPA-protected networks.
30  */
31
32
33 /** EAPOL-Key type field for modern 802.11i/RSN WPA packets */
34 #define EAPOL_KEY_TYPE_RSN      2
35
36 /** Old EAPOL-Key type field used by WPA1 hardware before 802.11i ratified */
37 #define EAPOL_KEY_TYPE_WPA      254
38
39
40 /**
41  * @defgroup eapol_key_info EAPOL-Key Info field bits
42  * @{
43  */
44
45 /** Key descriptor version, indicating WPA or WPA2 */
46 #define EAPOL_KEY_INFO_VERSION  0x0007
47
48 /** Key type bit, indicating pairwise or group */
49 #define EAPOL_KEY_INFO_TYPE     0x0008
50
51 /** Key install bit; set on message 3 except when legacy hacks are used */
52 #define EAPOL_KEY_INFO_INSTALL  0x0040
53
54 /** Key ACK bit; set when a response is required, on all messages except #4 */
55 #define EAPOL_KEY_INFO_KEY_ACK  0x0080
56
57 /** Key MIC bit; set when the MIC field is valid, on messages 3 and 4 */
58 #define EAPOL_KEY_INFO_KEY_MIC  0x0100
59
60 /** Secure bit; set when both sides have both keys, on messages 3 and 4 */
61 #define EAPOL_KEY_INFO_SECURE   0x0200
62
63 /** Error bit; set on a MIC failure for TKIP */
64 #define EAPOL_KEY_INFO_ERROR    0x0400
65
66 /** Request bit; set when authentication is initiated by the Peer (unusual) */
67 #define EAPOL_KEY_INFO_REQUEST  0x0800
68
69 /** Key Encrypted bit; set when the Key Data field is encrypted */
70 #define EAPOL_KEY_INFO_KEY_ENC  0x1000
71
72 /** SMC Message bit; set when this frame is part of an IBSS SMK handshake */
73 #define EAPOL_KEY_INFO_SMC_MESS 0x2000
74
75
76 /** Key descriptor version field value for WPA (TKIP) */
77 #define EAPOL_KEY_VERSION_WPA   1
78
79 /** Key descriptor version field value for WPA2 (CCMP) */
80 #define EAPOL_KEY_VERSION_WPA2  2
81
82 /** Key type field value for a PTK (pairwise) key handshake */
83 #define EAPOL_KEY_TYPE_PTK      0x0008
84
85 /** Key type field value for a GTK (group) key handshake */
86 #define EAPOL_KEY_TYPE_GTK      0x0000
87
88 /** @} */
89
90
91
92 /** An EAPOL-Key packet.
93  *
94  * These are used for the WPA 4-Way Handshake, whether or not prior
95  * authentication has been performed using EAP.
96  *
97  * On LANs, an eapol_key_pkt is always encapsulated in the data field
98  * of an eapol_frame, with the frame's type code set to EAPOL_TYPE_KEY.
99  *
100  * Unlike 802.11 frame headers, the fields in this structure are
101  * stored in big-endian!
102  */
103 struct eapol_key_pkt
104 {
105         /** One of the EAPOL_KEY_TYPE_* defines. */
106         u8 type;
107
108         /** Bitfield of key characteristics, network byte order */
109         u16 info;
110
111         /** Length of encryption key to be used, network byte order
112          *
113          * This is 16 for CCMP, 32 for TKIP, and 5 or 13 for WEP.
114          */
115         u16 keysize;
116
117         /** Monotonically increasing value for EAPOL-Key conversations
118          *
119          * In another classic demonstration of overengineering, this
120          * 8-byte value will rarely be anything above 1. It's stored
121          * in network byte order.
122          */
123         u64 replay;
124
125         /** Nonce value
126          *
127          * This is the authenticator's ANonce in frame 1, the peer's
128          * SNonce in frame 2, and 0 in frames 3 and 4.
129          */
130         u8 nonce[32];
131
132         /** Initialization vector
133          *
134          * This contains the IV used with the Key Encryption Key, or 0
135          * if the key is unencrypted or encrypted using an algorithm
136          * that does not require an IV.
137          */
138         u8 iv[16];
139
140         /** Receive sequence counter for GTK
141          *
142          * This is used to synchronize the client's replay counter for
143          * ordinary data packets. The first six bytes contain PN0
144          * through PN5 for CCMP mode, or TSC0 through TSC5 for TKIP
145          * mode. The last two bytes are zero.
146          */
147         u8 rsc[8];
148
149         /** Reserved bytes */
150         u8 _reserved[8];
151
152         /** Message integrity code over the entire EAPOL frame
153          *
154          * This is calculated using HMAC-MD5 when the key descriptor
155          * version field in @a info is 1, and HMAC-SHA1 ignoring the
156          * last 4 bytes of the hash when the version field in @a info
157          * is 2.
158          */
159         u8 mic[16];
160
161         /** Length of the @a data field in bytes, network byte order */
162         u16 datalen;
163
164         /** Key data
165          *
166          * This is formatted as a series of 802.11 information
167          * elements, with cryptographic data encapsulated using a
168          * "vendor-specific IE" code and an IEEE-specified OUI.
169          */
170         u8 data[0];
171 } __attribute__ (( packed ));
172
173
174 /** WPA handshaking state */
175 enum wpa_state {
176         /** Waiting for PMK to be set */
177         WPA_WAITING = 0,
178
179         /** Ready for 4-Way Handshake */
180         WPA_READY,
181
182         /** Performing 4-Way Handshake */
183         WPA_WORKING,
184
185         /** 4-Way Handshake succeeded */
186         WPA_SUCCESS,
187
188         /** 4-Way Handshake failed */
189         WPA_FAILURE,
190 };
191
192 /** Bitfield indicating a selection of WPA transient keys */
193 enum wpa_keymask {
194         /** Pairwise transient key */
195         WPA_PTK = 1,
196
197         /** Group transient key */
198         WPA_GTK = 2,
199 };
200
201
202 /** Length of a nonce */
203 #define WPA_NONCE_LEN           32
204
205 /** Length of a TKIP main key */
206 #define WPA_TKIP_KEY_LEN        16
207
208 /** Length of a TKIP MIC key */
209 #define WPA_TKIP_MIC_KEY_LEN    8
210
211 /** Length of a CCMP key */
212 #define WPA_CCMP_KEY_LEN        16
213
214 /** Length of an EAPOL Key Confirmation Key */
215 #define WPA_KCK_LEN             16
216
217 /** Length of an EAPOL Key Encryption Key */
218 #define WPA_KEK_LEN             16
219
220 /** Usual length of a Pairwise Master Key */
221 #define WPA_PMK_LEN             32
222
223 /** Length of a PMKID */
224 #define WPA_PMKID_LEN           16
225
226
227 /** Structure of the Temporal Key for TKIP encryption */
228 struct tkip_tk
229 {
230         /** Main key: input to TKIP Phase 1 and Phase 2 key mixing functions */
231         u8 key[WPA_TKIP_KEY_LEN];
232
233         /** Michael MIC keys */
234         struct {
235                 /** MIC key for packets from the AP */
236                 u8 rx[WPA_TKIP_MIC_KEY_LEN];
237
238                 /** MIC key for packets to the AP */
239                 u8 tx[WPA_TKIP_MIC_KEY_LEN];
240         } __attribute__ (( packed )) mic;
241 } __attribute__ (( packed ));
242
243 /** Structure of a generic Temporal Key */
244 union wpa_tk
245 {
246         /** CCMP key */
247         u8 ccmp[WPA_CCMP_KEY_LEN];
248
249         /** TKIP keys */
250         struct tkip_tk tkip;
251 };
252
253 /** Structure of the Pairwise Transient Key */
254 struct wpa_ptk
255 {
256         /** EAPOL-Key Key Confirmation Key (KCK) */
257         u8 kck[WPA_KCK_LEN];
258
259         /** EAPOL-Key Key Encryption Key (KEK) */
260         u8 kek[WPA_KEK_LEN];
261
262         /** Temporal key */
263         union wpa_tk tk;
264 } __attribute__ (( packed ));
265
266 /** Structure of the Group Transient Key */
267 struct wpa_gtk
268 {
269         /** Temporal key */
270         union wpa_tk tk;
271 } __attribute__ (( packed ));
272
273
274 /** Common context for WPA security handshaking
275  *
276  * Any implementor of a particular handshaking type (e.g. PSK or EAP)
277  * must include this structure at the very beginning of their private
278  * data context structure, to allow the EAPOL-Key handling code to
279  * work. When the preliminary authentication is done, it is necessary
280  * to call wpa_start(), passing the PMK (derived from PSK or EAP MSK)
281  * as an argument. The handshaker can use its @a step function to
282  * monitor @a state in this wpa_ctx structure for success or
283  * failure. On success, the keys will be available in @a ptk and @a
284  * gtk according to the state of the @a valid bitmask.
285  *
286  * After an initial success, the parent handshaker does not need to
287  * concern itself with rekeying; the WPA common code takes care of
288  * that.
289  */
290 struct wpa_common_ctx
291 {
292         /** 802.11 device we are authenticating for */
293         struct net80211_device *dev;
294
295         /** The Pairwise Master Key to use in handshaking
296          *
297          * This is set either by running the PBKDF2 algorithm on a
298          * passphrase with the SSID as salt to generate a pre-shared
299          * key, or by copying the first 32 bytes of the EAP Master
300          * Session Key in 802.1X-served authentication.
301          */
302         u8 pmk[WPA_PMK_LEN];
303
304         /** Length of the Pairwise Master Key
305          *
306          * This is always 32 except with one EAP method which only
307          * gives 16 bytes.
308          */
309         int pmk_len;
310
311         /** State of EAPOL-Key handshaking */
312         enum wpa_state state;
313
314         /** Replay counter for this association
315          *
316          * This stores the replay counter value for the most recent
317          * packet we've accepted. It is initially initialised to ~0 to
318          * show we'll accept anything.
319          */
320         u64 replay;
321
322         /** Mask of valid keys after authentication success
323          *
324          * If the PTK is not valid, the GTK should be used for both
325          * unicast and multicast decryption; if the GTK is not valid,
326          * multicast packets cannot be decrypted.
327          */
328         enum wpa_keymask valid;
329
330         /** The cipher to use for unicast RX and all TX */
331         enum net80211_crypto_alg crypt;
332
333         /** The cipher to use for broadcast and multicast RX */
334         enum net80211_crypto_alg gcrypt;
335
336         /** The Pairwise Transient Key derived from the handshake */
337         struct wpa_ptk ptk;
338
339         /** The Group Transient Key derived from the handshake */
340         struct wpa_gtk gtk;
341
342         /** Authenticator-provided nonce */
343         u8 Anonce[WPA_NONCE_LEN];
344
345         /** Supplicant-generated nonce (that's us) */
346         u8 Snonce[WPA_NONCE_LEN];
347
348         /** Whether we should refrain from generating another SNonce */
349         int have_Snonce;
350
351         /** Data in WPA or RSN IE from AP's beacon frame */
352         void *ap_rsn_ie;
353
354         /** Length of @a ap_rsn_ie */
355         int ap_rsn_ie_len;
356
357         /** Whether @a ap_rsn_ie is an RSN IE (as opposed to old WPA) */
358         int ap_rsn_is_rsn;
359
360         /** List entry */
361         struct list_head list;
362 };
363
364
365 /** WPA handshake key integrity and encryption handler
366  *
367  * Note that due to the structure of the 4-Way Handshake we never
368  * actually need to encrypt key data, only decrypt it.
369  */
370 struct wpa_kie {
371         /** Value of version bits in EAPOL-Key info field for which to use
372          *
373          * This should be one of the @c EAPOL_KEY_VERSION_* constants.
374          */
375         int version;
376
377         /** Calculate MIC over message
378          *
379          * @v kck       Key Confirmation Key, 16 bytes
380          * @v msg       Message to calculate MIC over
381          * @v len       Number of bytes to calculate MIC over
382          * @ret mic     Calculated MIC, 16 bytes long
383          *
384          * The @a mic return may point within @a msg, so it must not
385          * be filled until the calculation has been performed.
386          */
387         void ( * mic ) ( const void *kck, const void *msg, size_t len,
388                          void *mic );
389
390         /** Decrypt key data
391          *
392          * @v kek       Key Encryption Key, 16 bytes
393          * @v iv        Initialisation vector for encryption, 16 bytes
394          * @v msg       Message to decrypt (Key Data field)
395          * @v len       Length of message
396          * @ret msg     Decrypted message in place of original
397          * @ret len     Updated to reflect encrypted length
398          * @ret rc      Return status code
399          *
400          * The decrypted message is written over the encrypted one.
401          */
402         int ( * decrypt ) ( const void *kek, const void *iv, void *msg,
403                             u16 *len );
404 };
405
406 #define WPA_KIES        __table ( struct wpa_kie, "wpa_kies" )
407 #define __wpa_kie       __table_entry ( WPA_KIES, 01 )
408
409
410
411 /**
412  * @defgroup wpa_kde Key descriptor element types
413  * @{
414  */
415
416 /** Payload structure of the GTK-encapsulating KDE
417  *
418  * This does not include the IE type, length, or OUI bytes, which are
419  * generic to all KDEs.
420  */
421 struct wpa_kde_gtk_encap
422 {
423         /** Key ID and TX bit */
424         u8 id;
425
426         /** Reserved byte */
427         u8 _rsvd;
428
429         /** Encapsulated group transient key */
430         struct wpa_gtk gtk;
431 } __attribute__ (( packed ));
432
433 /** Mask for Key ID in wpa_kde_gtk::id field */
434 #define WPA_GTK_KID     0x03
435
436 /** Mask for Tx bit in wpa_kde_gtk::id field */
437 #define WPA_GTK_TXBIT   0x04
438
439
440 /** KDE type for an encapsulated Group Transient Key (requires encryption) */
441 #define WPA_KDE_GTK     _MKOUI ( 0x00, 0x0F, 0xAC, 0x01 )
442
443 /** KDE type for a MAC address */
444 #define WPA_KDE_MAC     _MKOUI ( 0x00, 0x0F, 0xAC, 0x03 )
445
446 /** KDE type for a PMKID */
447 #define WPA_KDE_PMKID   _MKOUI ( 0x00, 0x0F, 0xAC, 0x04 )
448
449 /** KDE type for a nonce */
450 #define WPA_KDE_NONCE   _MKOUI ( 0x00, 0x0F, 0xAC, 0x06 )
451
452 /** KDE type for a lifetime value */
453 #define WPA_KDE_LIFETIME _MKOUI ( 0x00, 0x0F, 0xAC, 0x07 )
454
455
456 /** Any key descriptor element type
457  *
458  * KDEs follow the 802.11 information element format of a type byte
459  * (in this case "vendor-specific", with the requisite OUI+subtype
460  * after length) and a length byte whose value does not include the
461  * length of the type and length bytes.
462  */
463 struct wpa_kde
464 {
465         /** Information element type: always 0xDD (IEEE80211_IE_VENDOR) */
466         u8 ie_type;
467
468         /** Length, not including ie_type and length fields */
469         u8 len;
470
471         /** OUI + type byte */
472         u32 oui_type;
473
474         /** Payload data */
475         union {
476                 /** For GTK-type KDEs, encapsulated GTK */
477                 struct wpa_kde_gtk_encap gtk_encap;
478
479                 /** For MAC-type KDEs, the MAC address */
480                 u8 mac[ETH_ALEN];
481
482                 /** For PMKID-type KDEs, the PMKID */
483                 u8 pmkid[WPA_PMKID_LEN];
484
485                 /** For Nonce-type KDEs, the nonce */
486                 u8 nonce[WPA_NONCE_LEN];
487
488                 /** For Lifetime-type KDEs, the lifetime in seconds
489                  *
490                  * This is in network byte order!
491                  */
492                 u32 lifetime;
493         };
494 } __attribute__ (( packed ));
495
496 /** @} */
497
498 int wpa_make_rsn_ie ( struct net80211_device *dev, union ieee80211_ie **ie );
499 int wpa_start ( struct net80211_device *dev, struct wpa_common_ctx *ctx,
500                 const void *pmk, size_t pmk_len );
501 void wpa_stop ( struct net80211_device *dev );
502
503 #endif /* _GPXE_WPA_H */