iPXE
wpa.h
Go to the documentation of this file.
00001 /*
00002  * Copyright (c) 2009 Joshua Oreman <oremanj@rwcr.net>.
00003  *
00004  * This program is free software; you can redistribute it and/or
00005  * modify it under the terms of the GNU General Public License as
00006  * published by the Free Software Foundation; either version 2 of the
00007  * License, or any later version.
00008  *
00009  * This program is distributed in the hope that it will be useful, but
00010  * WITHOUT ANY WARRANTY; without even the implied warranty of
00011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00012  * General Public License for more details.
00013  *
00014  * You should have received a copy of the GNU General Public License
00015  * along with this program; if not, write to the Free Software
00016  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
00017  * 02110-1301, USA.
00018  */
00019 
00020 #ifndef _IPXE_WPA_H
00021 #define _IPXE_WPA_H
00022 
00023 #include <ipxe/ieee80211.h>
00024 #include <ipxe/list.h>
00025 
00026 FILE_LICENCE ( GPL2_OR_LATER );
00027 
00028 /** @file
00029  *
00030  * Common definitions for all types of WPA-protected networks.
00031  */
00032 
00033 
00034 /** EAPOL-Key type field for modern 802.11i/RSN WPA packets */
00035 #define EAPOL_KEY_TYPE_RSN      2
00036 
00037 /** Old EAPOL-Key type field used by WPA1 hardware before 802.11i ratified */
00038 #define EAPOL_KEY_TYPE_WPA      254
00039 
00040 
00041 /**
00042  * @defgroup eapol_key_info EAPOL-Key Info field bits
00043  * @{
00044  */
00045 
00046 /** Key descriptor version, indicating WPA or WPA2 */
00047 #define EAPOL_KEY_INFO_VERSION  0x0007
00048 
00049 /** Key type bit, indicating pairwise or group */
00050 #define EAPOL_KEY_INFO_TYPE     0x0008
00051 
00052 /** Key install bit; set on message 3 except when legacy hacks are used */
00053 #define EAPOL_KEY_INFO_INSTALL  0x0040
00054 
00055 /** Key ACK bit; set when a response is required, on all messages except #4 */
00056 #define EAPOL_KEY_INFO_KEY_ACK  0x0080
00057 
00058 /** Key MIC bit; set when the MIC field is valid, on messages 3 and 4 */
00059 #define EAPOL_KEY_INFO_KEY_MIC  0x0100
00060 
00061 /** Secure bit; set when both sides have both keys, on messages 3 and 4 */
00062 #define EAPOL_KEY_INFO_SECURE   0x0200
00063 
00064 /** Error bit; set on a MIC failure for TKIP */
00065 #define EAPOL_KEY_INFO_ERROR    0x0400
00066 
00067 /** Request bit; set when authentication is initiated by the Peer (unusual) */
00068 #define EAPOL_KEY_INFO_REQUEST  0x0800
00069 
00070 /** Key Encrypted bit; set when the Key Data field is encrypted */
00071 #define EAPOL_KEY_INFO_KEY_ENC  0x1000
00072 
00073 /** SMC Message bit; set when this frame is part of an IBSS SMK handshake */
00074 #define EAPOL_KEY_INFO_SMC_MESS 0x2000
00075 
00076 
00077 /** Key descriptor version field value for WPA (TKIP) */
00078 #define EAPOL_KEY_VERSION_WPA   1
00079 
00080 /** Key descriptor version field value for WPA2 (CCMP) */
00081 #define EAPOL_KEY_VERSION_WPA2  2
00082 
00083 /** Key type field value for a PTK (pairwise) key handshake */
00084 #define EAPOL_KEY_TYPE_PTK      0x0008
00085 
00086 /** Key type field value for a GTK (group) key handshake */
00087 #define EAPOL_KEY_TYPE_GTK      0x0000
00088 
00089 /** @} */
00090 
00091 
00092 
00093 /** An EAPOL-Key packet.
00094  *
00095  * These are used for the WPA 4-Way Handshake, whether or not prior
00096  * authentication has been performed using EAP.
00097  *
00098  * On LANs, an eapol_key_pkt is always encapsulated in the data field
00099  * of an eapol_frame, with the frame's type code set to EAPOL_TYPE_KEY.
00100  *
00101  * Unlike 802.11 frame headers, the fields in this structure are
00102  * stored in big-endian!
00103  */
00104 struct eapol_key_pkt
00105 {
00106         /** One of the EAPOL_KEY_TYPE_* defines. */
00107         u8 type;
00108 
00109         /** Bitfield of key characteristics, network byte order */
00110         u16 info;
00111 
00112         /** Length of encryption key to be used, network byte order
00113          *
00114          * This is 16 for CCMP, 32 for TKIP, and 5 or 13 for WEP.
00115          */
00116         u16 keysize;
00117 
00118         /** Monotonically increasing value for EAPOL-Key conversations
00119          *
00120          * In another classic demonstration of overengineering, this
00121          * 8-byte value will rarely be anything above 1. It's stored
00122          * in network byte order.
00123          */
00124         u64 replay;
00125 
00126         /** Nonce value
00127          *
00128          * This is the authenticator's ANonce in frame 1, the peer's
00129          * SNonce in frame 2, and 0 in frames 3 and 4.
00130          */
00131         u8 nonce[32];
00132 
00133         /** Initialization vector
00134          *
00135          * This contains the IV used with the Key Encryption Key, or 0
00136          * if the key is unencrypted or encrypted using an algorithm
00137          * that does not require an IV.
00138          */
00139         u8 iv[16];
00140 
00141         /** Receive sequence counter for GTK
00142          *
00143          * This is used to synchronize the client's replay counter for
00144          * ordinary data packets. The first six bytes contain PN0
00145          * through PN5 for CCMP mode, or TSC0 through TSC5 for TKIP
00146          * mode. The last two bytes are zero.
00147          */
00148         u8 rsc[8];
00149 
00150         /** Reserved bytes */
00151         u8 _reserved[8];
00152 
00153         /** Message integrity code over the entire EAPOL frame
00154          *
00155          * This is calculated using HMAC-MD5 when the key descriptor
00156          * version field in @a info is 1, and HMAC-SHA1 ignoring the
00157          * last 4 bytes of the hash when the version field in @a info
00158          * is 2.
00159          */
00160         u8 mic[16];
00161 
00162         /** Length of the @a data field in bytes, network byte order */
00163         u16 datalen;
00164 
00165         /** Key data
00166          *
00167          * This is formatted as a series of 802.11 information
00168          * elements, with cryptographic data encapsulated using a
00169          * "vendor-specific IE" code and an IEEE-specified OUI.
00170          */
00171         u8 data[0];
00172 } __attribute__ (( packed ));
00173 
00174 
00175 /** WPA handshaking state */
00176 enum wpa_state {
00177         /** Waiting for PMK to be set */
00178         WPA_WAITING = 0,
00179 
00180         /** Ready for 4-Way Handshake */
00181         WPA_READY,
00182 
00183         /** Performing 4-Way Handshake */
00184         WPA_WORKING,
00185 
00186         /** 4-Way Handshake succeeded */
00187         WPA_SUCCESS,
00188 
00189         /** 4-Way Handshake failed */
00190         WPA_FAILURE,
00191 };
00192 
00193 /** Bitfield indicating a selection of WPA transient keys */
00194 enum wpa_keymask {
00195         /** Pairwise transient key */
00196         WPA_PTK = 1,
00197 
00198         /** Group transient key */
00199         WPA_GTK = 2,
00200 };
00201 
00202 
00203 /** Length of a nonce */
00204 #define WPA_NONCE_LEN           32
00205 
00206 /** Length of a TKIP main key */
00207 #define WPA_TKIP_KEY_LEN        16
00208 
00209 /** Length of a TKIP MIC key */
00210 #define WPA_TKIP_MIC_KEY_LEN    8
00211 
00212 /** Length of a CCMP key */
00213 #define WPA_CCMP_KEY_LEN        16
00214 
00215 /** Length of an EAPOL Key Confirmation Key */
00216 #define WPA_KCK_LEN             16
00217 
00218 /** Length of an EAPOL Key Encryption Key */
00219 #define WPA_KEK_LEN             16
00220 
00221 /** Usual length of a Pairwise Master Key */
00222 #define WPA_PMK_LEN             32
00223 
00224 /** Length of a PMKID */
00225 #define WPA_PMKID_LEN           16
00226 
00227 
00228 /** Structure of the Temporal Key for TKIP encryption */
00229 struct tkip_tk
00230 {
00231         /** Main key: input to TKIP Phase 1 and Phase 2 key mixing functions */
00232         u8 key[WPA_TKIP_KEY_LEN];
00233 
00234         /** Michael MIC keys */
00235         struct {
00236                 /** MIC key for packets from the AP */
00237                 u8 rx[WPA_TKIP_MIC_KEY_LEN];
00238 
00239                 /** MIC key for packets to the AP */
00240                 u8 tx[WPA_TKIP_MIC_KEY_LEN];
00241         } __attribute__ (( packed )) mic;
00242 } __attribute__ (( packed ));
00243 
00244 /** Structure of a generic Temporal Key */
00245 union wpa_tk
00246 {
00247         /** CCMP key */
00248         u8 ccmp[WPA_CCMP_KEY_LEN];
00249 
00250         /** TKIP keys */
00251         struct tkip_tk tkip;
00252 };
00253 
00254 /** Structure of the Pairwise Transient Key */
00255 struct wpa_ptk
00256 {
00257         /** EAPOL-Key Key Confirmation Key (KCK) */
00258         u8 kck[WPA_KCK_LEN];
00259 
00260         /** EAPOL-Key Key Encryption Key (KEK) */
00261         u8 kek[WPA_KEK_LEN];
00262 
00263         /** Temporal key */
00264         union wpa_tk tk;
00265 } __attribute__ (( packed ));
00266 
00267 /** Structure of the Group Transient Key */
00268 struct wpa_gtk
00269 {
00270         /** Temporal key */
00271         union wpa_tk tk;
00272 } __attribute__ (( packed ));
00273 
00274 
00275 /** Common context for WPA security handshaking
00276  *
00277  * Any implementor of a particular handshaking type (e.g. PSK or EAP)
00278  * must include this structure at the very beginning of their private
00279  * data context structure, to allow the EAPOL-Key handling code to
00280  * work. When the preliminary authentication is done, it is necessary
00281  * to call wpa_start(), passing the PMK (derived from PSK or EAP MSK)
00282  * as an argument. The handshaker can use its @a step function to
00283  * monitor @a state in this wpa_ctx structure for success or
00284  * failure. On success, the keys will be available in @a ptk and @a
00285  * gtk according to the state of the @a valid bitmask.
00286  *
00287  * After an initial success, the parent handshaker does not need to
00288  * concern itself with rekeying; the WPA common code takes care of
00289  * that.
00290  */
00291 struct wpa_common_ctx
00292 {
00293         /** 802.11 device we are authenticating for */
00294         struct net80211_device *dev;
00295 
00296         /** The Pairwise Master Key to use in handshaking
00297          *
00298          * This is set either by running the PBKDF2 algorithm on a
00299          * passphrase with the SSID as salt to generate a pre-shared
00300          * key, or by copying the first 32 bytes of the EAP Master
00301          * Session Key in 802.1X-served authentication.
00302          */
00303         u8 pmk[WPA_PMK_LEN];
00304 
00305         /** Length of the Pairwise Master Key
00306          *
00307          * This is always 32 except with one EAP method which only
00308          * gives 16 bytes.
00309          */
00310         int pmk_len;
00311 
00312         /** State of EAPOL-Key handshaking */
00313         enum wpa_state state;
00314 
00315         /** Replay counter for this association
00316          *
00317          * This stores the replay counter value for the most recent
00318          * packet we've accepted. It is initially initialised to ~0 to
00319          * show we'll accept anything.
00320          */
00321         u64 replay;
00322 
00323         /** Mask of valid keys after authentication success
00324          *
00325          * If the PTK is not valid, the GTK should be used for both
00326          * unicast and multicast decryption; if the GTK is not valid,
00327          * multicast packets cannot be decrypted.
00328          */
00329         enum wpa_keymask valid;
00330 
00331         /** The cipher to use for unicast RX and all TX */
00332         enum net80211_crypto_alg crypt;
00333 
00334         /** The cipher to use for broadcast and multicast RX */
00335         enum net80211_crypto_alg gcrypt;
00336 
00337         /** The Pairwise Transient Key derived from the handshake */
00338         struct wpa_ptk ptk;
00339 
00340         /** The Group Transient Key derived from the handshake */
00341         struct wpa_gtk gtk;
00342 
00343         /** Authenticator-provided nonce */
00344         u8 Anonce[WPA_NONCE_LEN];
00345 
00346         /** Supplicant-generated nonce (that's us) */
00347         u8 Snonce[WPA_NONCE_LEN];
00348 
00349         /** Whether we should refrain from generating another SNonce */
00350         int have_Snonce;
00351 
00352         /** Data in WPA or RSN IE from AP's beacon frame */
00353         void *ap_rsn_ie;
00354 
00355         /** Length of @a ap_rsn_ie */
00356         int ap_rsn_ie_len;
00357 
00358         /** Whether @a ap_rsn_ie is an RSN IE (as opposed to old WPA) */
00359         int ap_rsn_is_rsn;
00360 
00361         /** List entry */
00362         struct list_head list;
00363 };
00364 
00365 
00366 /** WPA handshake key integrity and encryption handler
00367  *
00368  * Note that due to the structure of the 4-Way Handshake we never
00369  * actually need to encrypt key data, only decrypt it.
00370  */
00371 struct wpa_kie {
00372         /** Value of version bits in EAPOL-Key info field for which to use
00373          *
00374          * This should be one of the @c EAPOL_KEY_VERSION_* constants.
00375          */
00376         int version;
00377 
00378         /** Calculate MIC over message
00379          *
00380          * @v kck       Key Confirmation Key, 16 bytes
00381          * @v msg       Message to calculate MIC over
00382          * @v len       Number of bytes to calculate MIC over
00383          * @ret mic     Calculated MIC, 16 bytes long
00384          *
00385          * The @a mic return may point within @a msg, so it must not
00386          * be filled until the calculation has been performed.
00387          */
00388         void ( * mic ) ( const void *kck, const void *msg, size_t len,
00389                          void *mic );
00390 
00391         /** Decrypt key data
00392          *
00393          * @v kek       Key Encryption Key, 16 bytes
00394          * @v iv        Initialisation vector for encryption, 16 bytes
00395          * @v msg       Message to decrypt (Key Data field)
00396          * @v len       Length of message
00397          * @ret msg     Decrypted message in place of original
00398          * @ret len     Updated to reflect encrypted length
00399          * @ret rc      Return status code
00400          *
00401          * The decrypted message is written over the encrypted one.
00402          */
00403         int ( * decrypt ) ( const void *kek, const void *iv, void *msg,
00404                             u16 *len );
00405 };
00406 
00407 #define WPA_KIES        __table ( struct wpa_kie, "wpa_kies" )
00408 #define __wpa_kie       __table_entry ( WPA_KIES, 01 )
00409 
00410 
00411 
00412 /**
00413  * @defgroup wpa_kde Key descriptor element types
00414  * @{
00415  */
00416 
00417 /** Payload structure of the GTK-encapsulating KDE
00418  *
00419  * This does not include the IE type, length, or OUI bytes, which are
00420  * generic to all KDEs.
00421  */
00422 struct wpa_kde_gtk_encap
00423 {
00424         /** Key ID and TX bit */
00425         u8 id;
00426 
00427         /** Reserved byte */
00428         u8 _rsvd;
00429 
00430         /** Encapsulated group transient key */
00431         struct wpa_gtk gtk;
00432 } __attribute__ (( packed ));
00433 
00434 /** Mask for Key ID in wpa_kde_gtk::id field */
00435 #define WPA_GTK_KID     0x03
00436 
00437 /** Mask for Tx bit in wpa_kde_gtk::id field */
00438 #define WPA_GTK_TXBIT   0x04
00439 
00440 
00441 /** KDE type for an encapsulated Group Transient Key (requires encryption) */
00442 #define WPA_KDE_GTK     _MKOUI ( 0x00, 0x0F, 0xAC, 0x01 )
00443 
00444 /** KDE type for a MAC address */
00445 #define WPA_KDE_MAC     _MKOUI ( 0x00, 0x0F, 0xAC, 0x03 )
00446 
00447 /** KDE type for a PMKID */
00448 #define WPA_KDE_PMKID   _MKOUI ( 0x00, 0x0F, 0xAC, 0x04 )
00449 
00450 /** KDE type for a nonce */
00451 #define WPA_KDE_NONCE   _MKOUI ( 0x00, 0x0F, 0xAC, 0x06 )
00452 
00453 /** KDE type for a lifetime value */
00454 #define WPA_KDE_LIFETIME _MKOUI ( 0x00, 0x0F, 0xAC, 0x07 )
00455 
00456 
00457 /** Any key descriptor element type
00458  *
00459  * KDEs follow the 802.11 information element format of a type byte
00460  * (in this case "vendor-specific", with the requisite OUI+subtype
00461  * after length) and a length byte whose value does not include the
00462  * length of the type and length bytes.
00463  */
00464 struct wpa_kde
00465 {
00466         /** Information element type: always 0xDD (IEEE80211_IE_VENDOR) */
00467         u8 ie_type;
00468 
00469         /** Length, not including ie_type and length fields */
00470         u8 len;
00471 
00472         /** OUI + type byte */
00473         u32 oui_type;
00474 
00475         /** Payload data */
00476         union {
00477                 /** For GTK-type KDEs, encapsulated GTK */
00478                 struct wpa_kde_gtk_encap gtk_encap;
00479 
00480                 /** For MAC-type KDEs, the MAC address */
00481                 u8 mac[ETH_ALEN];
00482 
00483                 /** For PMKID-type KDEs, the PMKID */
00484                 u8 pmkid[WPA_PMKID_LEN];
00485 
00486                 /** For Nonce-type KDEs, the nonce */
00487                 u8 nonce[WPA_NONCE_LEN];
00488 
00489                 /** For Lifetime-type KDEs, the lifetime in seconds
00490                  *
00491                  * This is in network byte order!
00492                  */
00493                 u32 lifetime;
00494         };
00495 } __attribute__ (( packed ));
00496 
00497 /** @} */
00498 
00499 int wpa_make_rsn_ie ( struct net80211_device *dev, union ieee80211_ie **ie );
00500 int wpa_start ( struct net80211_device *dev, struct wpa_common_ctx *ctx,
00501                 const void *pmk, size_t pmk_len );
00502 void wpa_stop ( struct net80211_device *dev );
00503 
00504 #endif /* _IPXE_WPA_H */