qemu/roms/ipxe/src/include/ipxe/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., 51 Franklin Street, Fifth Floor, Boston, MA
  17  * 02110-1301, USA.
  18  */
  19
  20 #ifndef _IPXE_WPA_H
  21 #define _IPXE_WPA_H
  22
  23 #include <ipxe/ieee80211.h>
  24 #include <ipxe/list.h>
  25
  26 FILE_LICENCE ( GPL2_OR_LATER );
  27
  28 /** @file
  29  *
  30  * Common definitions for all types of WPA-protected networks.
  31  */
  32
  33
  34 /** EAPOL-Key type field for modern 802.11i/RSN WPA packets */
  35 #define EAPOL_KEY_TYPE_RSN      2
  36
  37 /** Old EAPOL-Key type field used by WPA1 hardware before 802.11i ratified */
  38 #define EAPOL_KEY_TYPE_WPA      254
  39
  40
  41 /**
  42  * @defgroup eapol_key_info EAPOL-Key Info field bits
  43  * @{
  44  */
  45
  46 /** Key descriptor version, indicating WPA or WPA2 */
  47 #define EAPOL_KEY_INFO_VERSION  0x0007
  48
  49 /** Key type bit, indicating pairwise or group */
  50 #define EAPOL_KEY_INFO_TYPE     0x0008
  51
  52 /** Key install bit; set on message 3 except when legacy hacks are used */
  53 #define EAPOL_KEY_INFO_INSTALL  0x0040
  54
  55 /** Key ACK bit; set when a response is required, on all messages except #4 */
  56 #define EAPOL_KEY_INFO_KEY_ACK  0x0080
  57
  58 /** Key MIC bit; set when the MIC field is valid, on messages 3 and 4 */
  59 #define EAPOL_KEY_INFO_KEY_MIC  0x0100
  60
  61 /** Secure bit; set when both sides have both keys, on messages 3 and 4 */
  62 #define EAPOL_KEY_INFO_SECURE   0x0200
  63
  64 /** Error bit; set on a MIC failure for TKIP */
  65 #define EAPOL_KEY_INFO_ERROR    0x0400
  66
  67 /** Request bit; set when authentication is initiated by the Peer (unusual) */
  68 #define EAPOL_KEY_INFO_REQUEST  0x0800
  69
  70 /** Key Encrypted bit; set when the Key Data field is encrypted */
  71 #define EAPOL_KEY_INFO_KEY_ENC  0x1000
  72
  73 /** SMC Message bit; set when this frame is part of an IBSS SMK handshake */
  74 #define EAPOL_KEY_INFO_SMC_MESS 0x2000
  75
  76
  77 /** Key descriptor version field value for WPA (TKIP) */
  78 #define EAPOL_KEY_VERSION_WPA   1
  79
  80 /** Key descriptor version field value for WPA2 (CCMP) */
  81 #define EAPOL_KEY_VERSION_WPA2  2
  82
  83 /** Key type field value for a PTK (pairwise) key handshake */
  84 #define EAPOL_KEY_TYPE_PTK      0x0008
  85
  86 /** Key type field value for a GTK (group) key handshake */
  87 #define EAPOL_KEY_TYPE_GTK      0x0000
  88
  89 /** @} */
  90
  91
  92
  93 /** An EAPOL-Key packet.
  94  *
  95  * These are used for the WPA 4-Way Handshake, whether or not prior
  96  * authentication has been performed using EAP.
  97  *
  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.
 100  *
 101  * Unlike 802.11 frame headers, the fields in this structure are
 102  * stored in big-endian!
 103  */
 104 struct eapol_key_pkt
 105 {
 106         /** One of the EAPOL_KEY_TYPE_* defines. */
 107         u8 type;
 108
 109         /** Bitfield of key characteristics, network byte order */
 110         u16 info;
 111
 112         /** Length of encryption key to be used, network byte order
 113          *
 114          * This is 16 for CCMP, 32 for TKIP, and 5 or 13 for WEP.
 115          */
 116         u16 keysize;
 117
 118         /** Monotonically increasing value for EAPOL-Key conversations
 119          *
 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.
 123          */
 124         u64 replay;
 125
 126         /** Nonce value
 127          *
 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.
 130          */
 131         u8 nonce[32];
 132
 133         /** Initialization vector
 134          *
 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.
 138          */
 139         u8 iv[16];
 140
 141         /** Receive sequence counter for GTK
 142          *
 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.
 147          */
 148         u8 rsc[8];
 149
 150         /** Reserved bytes */
 151         u8 _reserved[8];
 152
 153         /** Message integrity code over the entire EAPOL frame
 154          *
 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
 158          * is 2.
 159          */
 160         u8 mic[16];
 161
 162         /** Length of the @a data field in bytes, network byte order */
 163         u16 datalen;
 164
 165         /** Key data
 166          *
 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.
 170          */
 171         u8 data[0];
 172 } __attribute__ (( packed ));
 173
 174
 175 /** WPA handshaking state */
 176 enum wpa_state {
 177         /** Waiting for PMK to be set */
 178         WPA_WAITING = 0,
 179
 180         /** Ready for 4-Way Handshake */
 181         WPA_READY,
 182
 183         /** Performing 4-Way Handshake */
 184         WPA_WORKING,
 185
 186         /** 4-Way Handshake succeeded */
 187         WPA_SUCCESS,
 188
 189         /** 4-Way Handshake failed */
 190         WPA_FAILURE,
 191 };
 192
 193 /** Bitfield indicating a selection of WPA transient keys */
 194 enum wpa_keymask {
 195         /** Pairwise transient key */
 196         WPA_PTK = 1,
 197
 198         /** Group transient key */
 199         WPA_GTK = 2,
 200 };
 201
 202
 203 /** Length of a nonce */
 204 #define WPA_NONCE_LEN           32
 205
 206 /** Length of a TKIP main key */
 207 #define WPA_TKIP_KEY_LEN        16
 208
 209 /** Length of a TKIP MIC key */
 210 #define WPA_TKIP_MIC_KEY_LEN    8
 211
 212 /** Length of a CCMP key */
 213 #define WPA_CCMP_KEY_LEN        16
 214
 215 /** Length of an EAPOL Key Confirmation Key */
 216 #define WPA_KCK_LEN             16
 217
 218 /** Length of an EAPOL Key Encryption Key */
 219 #define WPA_KEK_LEN             16
 220
 221 /** Usual length of a Pairwise Master Key */
 222 #define WPA_PMK_LEN             32
 223
 224 /** Length of a PMKID */
 225 #define WPA_PMKID_LEN           16
 226
 227
 228 /** Structure of the Temporal Key for TKIP encryption */
 229 struct tkip_tk
 230 {
 231         /** Main key: input to TKIP Phase 1 and Phase 2 key mixing functions */
 232         u8 key[WPA_TKIP_KEY_LEN];
 233
 234         /** Michael MIC keys */
 235         struct {
 236                 /** MIC key for packets from the AP */
 237                 u8 rx[WPA_TKIP_MIC_KEY_LEN];
 238
 239                 /** MIC key for packets to the AP */
 240                 u8 tx[WPA_TKIP_MIC_KEY_LEN];
 241         } __attribute__ (( packed )) mic;
 242 } __attribute__ (( packed ));
 243
 244 /** Structure of a generic Temporal Key */
 245 union wpa_tk
 246 {
 247         /** CCMP key */
 248         u8 ccmp[WPA_CCMP_KEY_LEN];
 249
 250         /** TKIP keys */
 251         struct tkip_tk tkip;
 252 };
 253
 254 /** Structure of the Pairwise Transient Key */
 255 struct wpa_ptk
 256 {
 257         /** EAPOL-Key Key Confirmation Key (KCK) */
 258         u8 kck[WPA_KCK_LEN];
 259
 260         /** EAPOL-Key Key Encryption Key (KEK) */
 261         u8 kek[WPA_KEK_LEN];
 262
 263         /** Temporal key */
 264         union wpa_tk tk;
 265 } __attribute__ (( packed ));
 266
 267 /** Structure of the Group Transient Key */
 268 struct wpa_gtk
 269 {
 270         /** Temporal key */
 271         union wpa_tk tk;
 272 } __attribute__ (( packed ));
 273
 274
 275 /** Common context for WPA security handshaking
 276  *
 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.
 286  *
 287  * After an initial success, the parent handshaker does not need to
 288  * concern itself with rekeying; the WPA common code takes care of
 289  * that.
 290  */
 291 struct wpa_common_ctx
 292 {
 293         /** 802.11 device we are authenticating for */
 294         struct net80211_device *dev;
 295
 296         /** The Pairwise Master Key to use in handshaking
 297          *
 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.
 302          */
 303         u8 pmk[WPA_PMK_LEN];
 304
 305         /** Length of the Pairwise Master Key
 306          *
 307          * This is always 32 except with one EAP method which only
 308          * gives 16 bytes.
 309          */
 310         int pmk_len;
 311
 312         /** State of EAPOL-Key handshaking */
 313         enum wpa_state state;
 314
 315         /** Replay counter for this association
 316          *
 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.
 320          */
 321         u64 replay;
 322
 323         /** Mask of valid keys after authentication success
 324          *
 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.
 328          */
 329         enum wpa_keymask valid;
 330
 331         /** The cipher to use for unicast RX and all TX */
 332         enum net80211_crypto_alg crypt;
 333
 334         /** The cipher to use for broadcast and multicast RX */
 335         enum net80211_crypto_alg gcrypt;
 336
 337         /** The Pairwise Transient Key derived from the handshake */
 338         struct wpa_ptk ptk;
 339
 340         /** The Group Transient Key derived from the handshake */
 341         struct wpa_gtk gtk;
 342
 343         /** Authenticator-provided nonce */
 344         u8 Anonce[WPA_NONCE_LEN];
 345
 346         /** Supplicant-generated nonce (that's us) */
 347         u8 Snonce[WPA_NONCE_LEN];
 348
 349         /** Whether we should refrain from generating another SNonce */
 350         int have_Snonce;
 351
 352         /** Data in WPA or RSN IE from AP's beacon frame */
 353         void *ap_rsn_ie;
 354
 355         /** Length of @a ap_rsn_ie */
 356         int ap_rsn_ie_len;
 357
 358         /** Whether @a ap_rsn_ie is an RSN IE (as opposed to old WPA) */
 359         int ap_rsn_is_rsn;
 360
 361         /** List entry */
 362         struct list_head list;
 363 };
 364
 365
 366 /** WPA handshake key integrity and encryption handler
 367  *
 368  * Note that due to the structure of the 4-Way Handshake we never
 369  * actually need to encrypt key data, only decrypt it.
 370  */
 371 struct wpa_kie {
 372         /** Value of version bits in EAPOL-Key info field for which to use
 373          *
 374          * This should be one of the @c EAPOL_KEY_VERSION_* constants.
 375          */
 376         int version;
 377
 378         /** Calculate MIC over message
 379          *
 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
 384          *
 385          * The @a mic return may point within @a msg, so it must not
 386          * be filled until the calculation has been performed.
 387          */
 388         void ( * mic ) ( const void *kck, const void *msg, size_t len,
 389                          void *mic );
 390
 391         /** Decrypt key data
 392          *
 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
 400          *
 401          * The decrypted message is written over the encrypted one.
 402          */
 403         int ( * decrypt ) ( const void *kek, const void *iv, void *msg,
 404                             u16 *len );
 405 };
 406
 407 #define WPA_KIES        __table ( struct wpa_kie, "wpa_kies" )
 408 #define __wpa_kie       __table_entry ( WPA_KIES, 01 )
 409
 410
 411
 412 /**
 413  * @defgroup wpa_kde Key descriptor element types
 414  * @{
 415  */
 416
 417 /** Payload structure of the GTK-encapsulating KDE
 418  *
 419  * This does not include the IE type, length, or OUI bytes, which are
 420  * generic to all KDEs.
 421  */
 422 struct wpa_kde_gtk_encap
 423 {
 424         /** Key ID and TX bit */
 425         u8 id;
 426
 427         /** Reserved byte */
 428         u8 _rsvd;
 429
 430         /** Encapsulated group transient key */
 431         struct wpa_gtk gtk;
 432 } __attribute__ (( packed ));
 433
 434 /** Mask for Key ID in wpa_kde_gtk::id field */
 435 #define WPA_GTK_KID     0x03
 436
 437 /** Mask for Tx bit in wpa_kde_gtk::id field */
 438 #define WPA_GTK_TXBIT   0x04
 439
 440
 441 /** KDE type for an encapsulated Group Transient Key (requires encryption) */
 442 #define WPA_KDE_GTK     _MKOUI ( 0x00, 0x0F, 0xAC, 0x01 )
 443
 444 /** KDE type for a MAC address */
 445 #define WPA_KDE_MAC     _MKOUI ( 0x00, 0x0F, 0xAC, 0x03 )
 446
 447 /** KDE type for a PMKID */
 448 #define WPA_KDE_PMKID   _MKOUI ( 0x00, 0x0F, 0xAC, 0x04 )
 449
 450 /** KDE type for a nonce */
 451 #define WPA_KDE_NONCE   _MKOUI ( 0x00, 0x0F, 0xAC, 0x06 )
 452
 453 /** KDE type for a lifetime value */
 454 #define WPA_KDE_LIFETIME _MKOUI ( 0x00, 0x0F, 0xAC, 0x07 )
 455
 456
 457 /** Any key descriptor element type
 458  *
 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.
 463  */
 464 struct wpa_kde
 465 {
 466         /** Information element type: always 0xDD (IEEE80211_IE_VENDOR) */
 467         u8 ie_type;
 468
 469         /** Length, not including ie_type and length fields */
 470         u8 len;
 471
 472         /** OUI + type byte */
 473         u32 oui_type;
 474
 475         /** Payload data */
 476         union {
 477                 /** For GTK-type KDEs, encapsulated GTK */
 478                 struct wpa_kde_gtk_encap gtk_encap;
 479
 480                 /** For MAC-type KDEs, the MAC address */
 481                 u8 mac[ETH_ALEN];
 482
 483                 /** For PMKID-type KDEs, the PMKID */
 484                 u8 pmkid[WPA_PMKID_LEN];
 485
 486                 /** For Nonce-type KDEs, the nonce */
 487                 u8 nonce[WPA_NONCE_LEN];
 488
 489                 /** For Lifetime-type KDEs, the lifetime in seconds
 490                  *
 491                  * This is in network byte order!
 492                  */
 493                 u32 lifetime;
 494         };
 495 } __attribute__ (( packed ));
 496
 497 /** @} */
 498
 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 );
 503
 504 #endif /* _IPXE_WPA_H */