2 * Copyright (c) 2009 Joshua Oreman <oremanj@rwcr.net>.
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.
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.
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., 51 Franklin Street, Fifth Floor, Boston, MA
23 #include <ipxe/ieee80211.h>
24 #include <ipxe/list.h>
26 FILE_LICENCE ( GPL2_OR_LATER );
30 * Common definitions for all types of WPA-protected networks.
34 /** EAPOL-Key type field for modern 802.11i/RSN WPA packets */
35 #define EAPOL_KEY_TYPE_RSN 2
37 /** Old EAPOL-Key type field used by WPA1 hardware before 802.11i ratified */
38 #define EAPOL_KEY_TYPE_WPA 254
42 * @defgroup eapol_key_info EAPOL-Key Info field bits
46 /** Key descriptor version, indicating WPA or WPA2 */
47 #define EAPOL_KEY_INFO_VERSION 0x0007
49 /** Key type bit, indicating pairwise or group */
50 #define EAPOL_KEY_INFO_TYPE 0x0008
52 /** Key install bit; set on message 3 except when legacy hacks are used */
53 #define EAPOL_KEY_INFO_INSTALL 0x0040
55 /** Key ACK bit; set when a response is required, on all messages except #4 */
56 #define EAPOL_KEY_INFO_KEY_ACK 0x0080
58 /** Key MIC bit; set when the MIC field is valid, on messages 3 and 4 */
59 #define EAPOL_KEY_INFO_KEY_MIC 0x0100
61 /** Secure bit; set when both sides have both keys, on messages 3 and 4 */
62 #define EAPOL_KEY_INFO_SECURE 0x0200
64 /** Error bit; set on a MIC failure for TKIP */
65 #define EAPOL_KEY_INFO_ERROR 0x0400
67 /** Request bit; set when authentication is initiated by the Peer (unusual) */
68 #define EAPOL_KEY_INFO_REQUEST 0x0800
70 /** Key Encrypted bit; set when the Key Data field is encrypted */
71 #define EAPOL_KEY_INFO_KEY_ENC 0x1000
73 /** SMC Message bit; set when this frame is part of an IBSS SMK handshake */
74 #define EAPOL_KEY_INFO_SMC_MESS 0x2000
77 /** Key descriptor version field value for WPA (TKIP) */
78 #define EAPOL_KEY_VERSION_WPA 1
80 /** Key descriptor version field value for WPA2 (CCMP) */
81 #define EAPOL_KEY_VERSION_WPA2 2
83 /** Key type field value for a PTK (pairwise) key handshake */
84 #define EAPOL_KEY_TYPE_PTK 0x0008
86 /** Key type field value for a GTK (group) key handshake */
87 #define EAPOL_KEY_TYPE_GTK 0x0000
93 /** An EAPOL-Key packet.
95 * These are used for the WPA 4-Way Handshake, whether or not prior
96 * authentication has been performed using EAP.
98 * On LANs, an eapol_key_pkt is always encapsulated in the data field
99 * of an eapol_frame, with the frame's type code set to EAPOL_TYPE_KEY.
101 * Unlike 802.11 frame headers, the fields in this structure are
102 * stored in big-endian!
106 /** One of the EAPOL_KEY_TYPE_* defines. */
109 /** Bitfield of key characteristics, network byte order */
112 /** Length of encryption key to be used, network byte order
114 * This is 16 for CCMP, 32 for TKIP, and 5 or 13 for WEP.
118 /** Monotonically increasing value for EAPOL-Key conversations
120 * In another classic demonstration of overengineering, this
121 * 8-byte value will rarely be anything above 1. It's stored
122 * in network byte order.
128 * This is the authenticator's ANonce in frame 1, the peer's
129 * SNonce in frame 2, and 0 in frames 3 and 4.
133 /** Initialization vector
135 * This contains the IV used with the Key Encryption Key, or 0
136 * if the key is unencrypted or encrypted using an algorithm
137 * that does not require an IV.
141 /** Receive sequence counter for GTK
143 * This is used to synchronize the client's replay counter for
144 * ordinary data packets. The first six bytes contain PN0
145 * through PN5 for CCMP mode, or TSC0 through TSC5 for TKIP
146 * mode. The last two bytes are zero.
150 /** Reserved bytes */
153 /** Message integrity code over the entire EAPOL frame
155 * This is calculated using HMAC-MD5 when the key descriptor
156 * version field in @a info is 1, and HMAC-SHA1 ignoring the
157 * last 4 bytes of the hash when the version field in @a info
162 /** Length of the @a data field in bytes, network byte order */
167 * This is formatted as a series of 802.11 information
168 * elements, with cryptographic data encapsulated using a
169 * "vendor-specific IE" code and an IEEE-specified OUI.
172 } __attribute__ (( packed ));
175 /** WPA handshaking state */
177 /** Waiting for PMK to be set */
180 /** Ready for 4-Way Handshake */
183 /** Performing 4-Way Handshake */
186 /** 4-Way Handshake succeeded */
189 /** 4-Way Handshake failed */
193 /** Bitfield indicating a selection of WPA transient keys */
195 /** Pairwise transient key */
198 /** Group transient key */
203 /** Length of a nonce */
204 #define WPA_NONCE_LEN 32
206 /** Length of a TKIP main key */
207 #define WPA_TKIP_KEY_LEN 16
209 /** Length of a TKIP MIC key */
210 #define WPA_TKIP_MIC_KEY_LEN 8
212 /** Length of a CCMP key */
213 #define WPA_CCMP_KEY_LEN 16
215 /** Length of an EAPOL Key Confirmation Key */
216 #define WPA_KCK_LEN 16
218 /** Length of an EAPOL Key Encryption Key */
219 #define WPA_KEK_LEN 16
221 /** Usual length of a Pairwise Master Key */
222 #define WPA_PMK_LEN 32
224 /** Length of a PMKID */
225 #define WPA_PMKID_LEN 16
228 /** Structure of the Temporal Key for TKIP encryption */
231 /** Main key: input to TKIP Phase 1 and Phase 2 key mixing functions */
232 u8 key[WPA_TKIP_KEY_LEN];
234 /** Michael MIC keys */
236 /** MIC key for packets from the AP */
237 u8 rx[WPA_TKIP_MIC_KEY_LEN];
239 /** MIC key for packets to the AP */
240 u8 tx[WPA_TKIP_MIC_KEY_LEN];
241 } __attribute__ (( packed )) mic;
242 } __attribute__ (( packed ));
244 /** Structure of a generic Temporal Key */
248 u8 ccmp[WPA_CCMP_KEY_LEN];
254 /** Structure of the Pairwise Transient Key */
257 /** EAPOL-Key Key Confirmation Key (KCK) */
260 /** EAPOL-Key Key Encryption Key (KEK) */
265 } __attribute__ (( packed ));
267 /** Structure of the Group Transient Key */
272 } __attribute__ (( packed ));
275 /** Common context for WPA security handshaking
277 * Any implementor of a particular handshaking type (e.g. PSK or EAP)
278 * must include this structure at the very beginning of their private
279 * data context structure, to allow the EAPOL-Key handling code to
280 * work. When the preliminary authentication is done, it is necessary
281 * to call wpa_start(), passing the PMK (derived from PSK or EAP MSK)
282 * as an argument. The handshaker can use its @a step function to
283 * monitor @a state in this wpa_ctx structure for success or
284 * failure. On success, the keys will be available in @a ptk and @a
285 * gtk according to the state of the @a valid bitmask.
287 * After an initial success, the parent handshaker does not need to
288 * concern itself with rekeying; the WPA common code takes care of
291 struct wpa_common_ctx
293 /** 802.11 device we are authenticating for */
294 struct net80211_device *dev;
296 /** The Pairwise Master Key to use in handshaking
298 * This is set either by running the PBKDF2 algorithm on a
299 * passphrase with the SSID as salt to generate a pre-shared
300 * key, or by copying the first 32 bytes of the EAP Master
301 * Session Key in 802.1X-served authentication.
305 /** Length of the Pairwise Master Key
307 * This is always 32 except with one EAP method which only
312 /** State of EAPOL-Key handshaking */
313 enum wpa_state state;
315 /** Replay counter for this association
317 * This stores the replay counter value for the most recent
318 * packet we've accepted. It is initially initialised to ~0 to
319 * show we'll accept anything.
323 /** Mask of valid keys after authentication success
325 * If the PTK is not valid, the GTK should be used for both
326 * unicast and multicast decryption; if the GTK is not valid,
327 * multicast packets cannot be decrypted.
329 enum wpa_keymask valid;
331 /** The cipher to use for unicast RX and all TX */
332 enum net80211_crypto_alg crypt;
334 /** The cipher to use for broadcast and multicast RX */
335 enum net80211_crypto_alg gcrypt;
337 /** The Pairwise Transient Key derived from the handshake */
340 /** The Group Transient Key derived from the handshake */
343 /** Authenticator-provided nonce */
344 u8 Anonce[WPA_NONCE_LEN];
346 /** Supplicant-generated nonce (that's us) */
347 u8 Snonce[WPA_NONCE_LEN];
349 /** Whether we should refrain from generating another SNonce */
352 /** Data in WPA or RSN IE from AP's beacon frame */
355 /** Length of @a ap_rsn_ie */
358 /** Whether @a ap_rsn_ie is an RSN IE (as opposed to old WPA) */
362 struct list_head list;
366 /** WPA handshake key integrity and encryption handler
368 * Note that due to the structure of the 4-Way Handshake we never
369 * actually need to encrypt key data, only decrypt it.
372 /** Value of version bits in EAPOL-Key info field for which to use
374 * This should be one of the @c EAPOL_KEY_VERSION_* constants.
378 /** Calculate MIC over message
380 * @v kck Key Confirmation Key, 16 bytes
381 * @v msg Message to calculate MIC over
382 * @v len Number of bytes to calculate MIC over
383 * @ret mic Calculated MIC, 16 bytes long
385 * The @a mic return may point within @a msg, so it must not
386 * be filled until the calculation has been performed.
388 void ( * mic ) ( const void *kck, const void *msg, size_t len,
393 * @v kek Key Encryption Key, 16 bytes
394 * @v iv Initialisation vector for encryption, 16 bytes
395 * @v msg Message to decrypt (Key Data field)
396 * @v len Length of message
397 * @ret msg Decrypted message in place of original
398 * @ret len Updated to reflect encrypted length
399 * @ret rc Return status code
401 * The decrypted message is written over the encrypted one.
403 int ( * decrypt ) ( const void *kek, const void *iv, void *msg,
407 #define WPA_KIES __table ( struct wpa_kie, "wpa_kies" )
408 #define __wpa_kie __table_entry ( WPA_KIES, 01 )
413 * @defgroup wpa_kde Key descriptor element types
417 /** Payload structure of the GTK-encapsulating KDE
419 * This does not include the IE type, length, or OUI bytes, which are
420 * generic to all KDEs.
422 struct wpa_kde_gtk_encap
424 /** Key ID and TX bit */
430 /** Encapsulated group transient key */
432 } __attribute__ (( packed ));
434 /** Mask for Key ID in wpa_kde_gtk::id field */
435 #define WPA_GTK_KID 0x03
437 /** Mask for Tx bit in wpa_kde_gtk::id field */
438 #define WPA_GTK_TXBIT 0x04
441 /** KDE type for an encapsulated Group Transient Key (requires encryption) */
442 #define WPA_KDE_GTK _MKOUI ( 0x00, 0x0F, 0xAC, 0x01 )
444 /** KDE type for a MAC address */
445 #define WPA_KDE_MAC _MKOUI ( 0x00, 0x0F, 0xAC, 0x03 )
447 /** KDE type for a PMKID */
448 #define WPA_KDE_PMKID _MKOUI ( 0x00, 0x0F, 0xAC, 0x04 )
450 /** KDE type for a nonce */
451 #define WPA_KDE_NONCE _MKOUI ( 0x00, 0x0F, 0xAC, 0x06 )
453 /** KDE type for a lifetime value */
454 #define WPA_KDE_LIFETIME _MKOUI ( 0x00, 0x0F, 0xAC, 0x07 )
457 /** Any key descriptor element type
459 * KDEs follow the 802.11 information element format of a type byte
460 * (in this case "vendor-specific", with the requisite OUI+subtype
461 * after length) and a length byte whose value does not include the
462 * length of the type and length bytes.
466 /** Information element type: always 0xDD (IEEE80211_IE_VENDOR) */
469 /** Length, not including ie_type and length fields */
472 /** OUI + type byte */
477 /** For GTK-type KDEs, encapsulated GTK */
478 struct wpa_kde_gtk_encap gtk_encap;
480 /** For MAC-type KDEs, the MAC address */
483 /** For PMKID-type KDEs, the PMKID */
484 u8 pmkid[WPA_PMKID_LEN];
486 /** For Nonce-type KDEs, the nonce */
487 u8 nonce[WPA_NONCE_LEN];
489 /** For Lifetime-type KDEs, the lifetime in seconds
491 * This is in network byte order!
495 } __attribute__ (( packed ));
499 int wpa_make_rsn_ie ( struct net80211_device *dev, union ieee80211_ie **ie );
500 int wpa_start ( struct net80211_device *dev, struct wpa_common_ctx *ctx,
501 const void *pmk, size_t pmk_len );
502 void wpa_stop ( struct net80211_device *dev );
504 #endif /* _IPXE_WPA_H */