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 */ 504