iPXE
Data Structures | Defines | Enumerations | Functions | Variables
wpa.h File Reference

Common definitions for all types of WPA-protected networks. More...

#include <ipxe/ieee80211.h>
#include <ipxe/list.h>

Go to the source code of this file.

Data Structures

struct  eapol_key_pkt
 An EAPOL-Key packet. More...
struct  tkip_tk
 Structure of the Temporal Key for TKIP encryption. More...
union  wpa_tk
 Structure of a generic Temporal Key. More...
struct  wpa_ptk
 Structure of the Pairwise Transient Key. More...
struct  wpa_gtk
 Structure of the Group Transient Key. More...
struct  wpa_common_ctx
 Common context for WPA security handshaking. More...
struct  wpa_kie
 WPA handshake key integrity and encryption handler. More...
struct  wpa_kde_gtk_encap
 Payload structure of the GTK-encapsulating KDE. More...
struct  wpa_kde
 Any key descriptor element type. More...

Defines

#define EAPOL_KEY_TYPE_RSN   2
 EAPOL-Key type field for modern 802.11i/RSN WPA packets.
#define EAPOL_KEY_TYPE_WPA   254
 Old EAPOL-Key type field used by WPA1 hardware before 802.11i ratified.
#define EAPOL_KEY_INFO_VERSION   0x0007
 Key descriptor version, indicating WPA or WPA2.
#define EAPOL_KEY_INFO_TYPE   0x0008
 Key type bit, indicating pairwise or group.
#define EAPOL_KEY_INFO_INSTALL   0x0040
 Key install bit; set on message 3 except when legacy hacks are used.
#define EAPOL_KEY_INFO_KEY_ACK   0x0080
 Key ACK bit; set when a response is required, on all messages except #4.
#define EAPOL_KEY_INFO_KEY_MIC   0x0100
 Key MIC bit; set when the MIC field is valid, on messages 3 and 4.
#define EAPOL_KEY_INFO_SECURE   0x0200
 Secure bit; set when both sides have both keys, on messages 3 and 4.
#define EAPOL_KEY_INFO_ERROR   0x0400
 Error bit; set on a MIC failure for TKIP.
#define EAPOL_KEY_INFO_REQUEST   0x0800
 Request bit; set when authentication is initiated by the Peer (unusual)
#define EAPOL_KEY_INFO_KEY_ENC   0x1000
 Key Encrypted bit; set when the Key Data field is encrypted.
#define EAPOL_KEY_INFO_SMC_MESS   0x2000
 SMC Message bit; set when this frame is part of an IBSS SMK handshake.
#define EAPOL_KEY_VERSION_WPA   1
 Key descriptor version field value for WPA (TKIP)
#define EAPOL_KEY_VERSION_WPA2   2
 Key descriptor version field value for WPA2 (CCMP)
#define EAPOL_KEY_TYPE_PTK   0x0008
 Key type field value for a PTK (pairwise) key handshake.
#define EAPOL_KEY_TYPE_GTK   0x0000
 Key type field value for a GTK (group) key handshake.
#define WPA_NONCE_LEN   32
 Length of a nonce.
#define WPA_TKIP_KEY_LEN   16
 Length of a TKIP main key.
#define WPA_TKIP_MIC_KEY_LEN   8
 Length of a TKIP MIC key.
#define WPA_CCMP_KEY_LEN   16
 Length of a CCMP key.
#define WPA_KCK_LEN   16
 Length of an EAPOL Key Confirmation Key.
#define WPA_KEK_LEN   16
 Length of an EAPOL Key Encryption Key.
#define WPA_PMK_LEN   32
 Usual length of a Pairwise Master Key.
#define WPA_PMKID_LEN   16
 Length of a PMKID.
#define WPA_KIES   __table ( struct wpa_kie, "wpa_kies" )
#define __wpa_kie   __table_entry ( WPA_KIES, 01 )
#define WPA_GTK_KID   0x03
 Mask for Key ID in wpa_kde_gtk::id field.
#define WPA_GTK_TXBIT   0x04
 Mask for Tx bit in wpa_kde_gtk::id field.
#define WPA_KDE_GTK   _MKOUI ( 0x00, 0x0F, 0xAC, 0x01 )
 KDE type for an encapsulated Group Transient Key (requires encryption)
#define WPA_KDE_MAC   _MKOUI ( 0x00, 0x0F, 0xAC, 0x03 )
 KDE type for a MAC address.
#define WPA_KDE_PMKID   _MKOUI ( 0x00, 0x0F, 0xAC, 0x04 )
 KDE type for a PMKID.
#define WPA_KDE_NONCE   _MKOUI ( 0x00, 0x0F, 0xAC, 0x06 )
 KDE type for a nonce.
#define WPA_KDE_LIFETIME   _MKOUI ( 0x00, 0x0F, 0xAC, 0x07 )
 KDE type for a lifetime value.

Enumerations

enum  wpa_state {
  WPA_WAITING = 0, WPA_READY, WPA_WORKING, WPA_SUCCESS,
  WPA_FAILURE
}
 WPA handshaking state. More...
enum  wpa_keymask { WPA_PTK = 1, WPA_GTK = 2 }
 Bitfield indicating a selection of WPA transient keys. More...

Functions

 FILE_LICENCE (GPL2_OR_LATER)
struct eapol_key_pkt __attribute__ ((packed)) mic
 Michael MIC keys.
int wpa_make_rsn_ie (struct net80211_device *dev, union ieee80211_ie **ie)
 Construct RSN or WPA information element.
int wpa_start (struct net80211_device *dev, struct wpa_common_ctx *ctx, const void *pmk, size_t pmk_len)
 Set up generic WPA support to handle 4-Way Handshake.
void wpa_stop (struct net80211_device *dev)
 Disable handling of received WPA handshake frames.

Variables

u8 type
 One of the EAPOL_KEY_TYPE_* defines.
u16 info
 Bitfield of key characteristics, network byte order.
u16 keysize
 Length of encryption key to be used, network byte order.
u64 replay
 Monotonically increasing value for EAPOL-Key conversations.
u8 nonce [32]
 Nonce value.
u8 iv [16]
 Initialization vector.
u8 rsc [8]
 Receive sequence counter for GTK.
u8 _reserved [8]
 Reserved bytes.
u8 mic [16]
 Message integrity code over the entire EAPOL frame.
u16 datalen
 Length of the data field in bytes, network byte order.
u8 data [0]
 Key data.
enum wpa_state __attribute__
u8 rx [WPA_TKIP_MIC_KEY_LEN]
 MIC key for packets from the AP.
u8 tx [WPA_TKIP_MIC_KEY_LEN]
 MIC key for packets to the AP.
u8 key [WPA_TKIP_KEY_LEN]
 Main key: input to TKIP Phase 1 and Phase 2 key mixing functions.
u8 kck [WPA_KCK_LEN]
 EAPOL-Key Key Confirmation Key (KCK)
u8 kek [WPA_KEK_LEN]
 EAPOL-Key Key Encryption Key (KEK)
union wpa_tk tk
 Temporal key.
u8 id
 Key ID and TX bit.
u8 _rsvd
 Reserved byte.
struct wpa_gtk gtk
 Encapsulated group transient key.
u8 ie_type
 Information element type: always 0xDD (IEEE80211_IE_VENDOR)
u8 len
 Length, not including ie_type and length fields.
u32 oui_type
 OUI + type byte.
union {
   struct wpa_kde_gtk_encap   gtk_encap
 For GTK-type KDEs, encapsulated GTK.
   u8   mac [ETH_ALEN]
 For MAC-type KDEs, the MAC address.
   u8   pmkid [WPA_PMKID_LEN]
 For PMKID-type KDEs, the PMKID.
   u8   nonce [WPA_NONCE_LEN]
 For Nonce-type KDEs, the nonce.
   u32   lifetime
 For Lifetime-type KDEs, the lifetime in seconds.
}; 
 Payload data.

Detailed Description

Common definitions for all types of WPA-protected networks.

Definition in file wpa.h.


Define Documentation

#define EAPOL_KEY_TYPE_RSN   2

EAPOL-Key type field for modern 802.11i/RSN WPA packets.

Definition at line 35 of file wpa.h.

Referenced by eapol_key_rx().

#define EAPOL_KEY_TYPE_WPA   254

Old EAPOL-Key type field used by WPA1 hardware before 802.11i ratified.

Definition at line 38 of file wpa.h.

Referenced by eapol_key_rx().

#define WPA_NONCE_LEN   32

Length of a nonce.

Definition at line 204 of file wpa.h.

Referenced by wpa_derive_ptk(), and wpa_handle_3_of_4().

#define WPA_TKIP_KEY_LEN   16

Length of a TKIP main key.

Definition at line 207 of file wpa.h.

#define WPA_TKIP_MIC_KEY_LEN   8

Length of a TKIP MIC key.

Definition at line 210 of file wpa.h.

#define WPA_CCMP_KEY_LEN   16

Length of a CCMP key.

Definition at line 213 of file wpa.h.

#define WPA_KCK_LEN   16

Length of an EAPOL Key Confirmation Key.

Definition at line 216 of file wpa.h.

#define WPA_KEK_LEN   16

Length of an EAPOL Key Encryption Key.

Definition at line 219 of file wpa.h.

#define WPA_PMK_LEN   32

Usual length of a Pairwise Master Key.

Definition at line 222 of file wpa.h.

Referenced by wpa_psk_start().

#define WPA_PMKID_LEN   16

Length of a PMKID.

Definition at line 225 of file wpa.h.

#define WPA_KIES   __table ( struct wpa_kie, "wpa_kies" )

Definition at line 407 of file wpa.h.

Referenced by wpa_find_kie().

#define __wpa_kie   __table_entry ( WPA_KIES, 01 )

Definition at line 408 of file wpa.h.


Enumeration Type Documentation

enum wpa_state

WPA handshaking state.

Enumerator:
WPA_WAITING 

Waiting for PMK to be set.

WPA_READY 

Ready for 4-Way Handshake.

WPA_WORKING 

Performing 4-Way Handshake.

WPA_SUCCESS 

4-Way Handshake succeeded

WPA_FAILURE 

4-Way Handshake failed

Definition at line 176 of file wpa.h.

               {
        /** Waiting for PMK to be set */
        WPA_WAITING = 0,

        /** Ready for 4-Way Handshake */
        WPA_READY,

        /** Performing 4-Way Handshake */
        WPA_WORKING,

        /** 4-Way Handshake succeeded */
        WPA_SUCCESS,

        /** 4-Way Handshake failed */
        WPA_FAILURE,
};

Bitfield indicating a selection of WPA transient keys.

Enumerator:
WPA_PTK 

Pairwise transient key.

WPA_GTK 

Group transient key.

Definition at line 194 of file wpa.h.

                 {
        /** Pairwise transient key */
        WPA_PTK = 1,

        /** Group transient key */
        WPA_GTK = 2,
};

Function Documentation

FILE_LICENCE ( GPL2_OR_LATER  )
int wpa_make_rsn_ie ( struct net80211_device dev,
union ieee80211_ie **  ie_ret 
)

Construct RSN or WPA information element.

Parameters:
dev802.11 device
Return values:
ie_retRSN or WPA information element
rcReturn status code

This function allocates, fills, and returns a RSN or WPA information element suitable for including in an association request frame to the network identified by dev->associating. If it is impossible to construct an information element consistent with iPXE's capabilities that is compatible with that network, or if none should be sent because that network's beacon included no security information, returns an error indication and leaves ie_ret unchanged.

The returned IE will be of the same type (RSN or WPA) as was included in the beacon for the network it is destined for.

Definition at line 124 of file wpa.c.

References ieee80211_ie_rsn::akm_count, ieee80211_ie_rsn::akm_list, net80211_device::associating, net80211_wlan::beacon, net80211_wlan::crypto, io_buffer::data, ieee80211_frame::data, DBG, EINVAL, ENOMEM, ENOTSUP, ieee80211_ie_rsn::group_cipher, group_cipher, net80211_wlan::handshaking, hdr, ieee80211_beacon, IEEE80211_IE_RSN, IEEE80211_IE_VENDOR, ieee80211_rsn_size(), IEEE80211_RSN_VERSION, IEEE80211_WPA_OUI_VEN, malloc(), ieee80211_ie_rsn::pairwise_cipher, ieee80211_ie_rsn::pairwise_count, ieee80211_ie_rsn::pmkid_count, ieee80211_ie_rsn::rsn_capab, sec80211_find_rsn(), sec80211_rsn_get_akm_desc(), sec80211_rsn_get_crypto_desc(), sec80211_rsn_get_net80211_crypt(), io_buffer::tail, ieee80211_ie_rsn::version, and wpa_find_cryptosystem().

Referenced by wpa_psk_init().

{
        u8 *rsn, *rsn_end;
        int is_rsn;
        u32 group_cipher;
        enum net80211_crypto_alg gcrypt;
        int ie_len;
        u8 *iep;
        struct ieee80211_ie_rsn *ie;
        struct ieee80211_frame *hdr;
        struct ieee80211_beacon *beacon;

        if ( ! dev->associating ) {
                DBG ( "WPA: Can't make RSN IE for a non-associating device\n" );
                return -EINVAL;
        }

        hdr = dev->associating->beacon->data;
        beacon = ( struct ieee80211_beacon * ) hdr->data;
        rsn = sec80211_find_rsn ( beacon->info_element,
                                  dev->associating->beacon->tail, &is_rsn,
                                  &rsn_end );
        if ( ! rsn ) {
                DBG ( "WPA: Can't make RSN IE when we didn't get one\n" );
                return -EINVAL;
        }

        rsn += 2;               /* skip version */
        group_cipher = *( u32 * ) rsn;
        gcrypt = sec80211_rsn_get_net80211_crypt ( group_cipher );

        if ( ! wpa_find_cryptosystem ( gcrypt ) ||
             ! wpa_find_cryptosystem ( dev->associating->crypto ) ) {
                DBG ( "WPA: No support for (GC:%d, PC:%d)\n",
                      gcrypt, dev->associating->crypto );
                return -ENOTSUP;
        }

        /* Everything looks good - make our IE. */

        /* WPA IEs need 4 more bytes for the OUI+type */
        ie_len = ieee80211_rsn_size ( 1, 1, 0, is_rsn ) + ( 4 * ! is_rsn );
        iep = malloc ( ie_len );
        if ( ! iep )
                return -ENOMEM;

        *ie_ret = ( union ieee80211_ie * ) iep;

        /* Store ID and length bytes. */
        *iep++ = ( is_rsn ? IEEE80211_IE_RSN : IEEE80211_IE_VENDOR );
        *iep++ = ie_len - 2;

        /* Store OUI+type for WPA IEs. */
        if ( ! is_rsn ) {
                *( u32 * ) iep = IEEE80211_WPA_OUI_VEN;
                iep += 4;
        }

        /* If this is a WPA IE, the id and len bytes in the
           ieee80211_ie_rsn structure will not be valid, but by doing
           the cast we can fill all the other fields much more
           readily. */

        ie = ( struct ieee80211_ie_rsn * ) ( iep - 2 );
        ie->version = IEEE80211_RSN_VERSION;
        ie->group_cipher = group_cipher;
        ie->pairwise_count = 1;
        ie->pairwise_cipher[0] =
                sec80211_rsn_get_crypto_desc ( dev->associating->crypto,
                                               is_rsn );
        ie->akm_count = 1;
        ie->akm_list[0] =
                sec80211_rsn_get_akm_desc ( dev->associating->handshaking,
                                            is_rsn );
        if ( is_rsn ) {
                ie->rsn_capab = 0;
                ie->pmkid_count = 0;
        }

        return 0;
}
int wpa_start ( struct net80211_device dev,
struct wpa_common_ctx ctx,
const void *  pmk,
size_t  pmk_len 
)

Set up generic WPA support to handle 4-Way Handshake.

Parameters:
dev802.11 device
ctxWPA common context
pmkPairwise Master Key to use for session
pmk_lenLength of PMK, almost always 32
Return values:
rcReturn status code

Definition at line 216 of file wpa.c.

References wpa_common_ctx::ap_rsn_ie, wpa_common_ctx::ap_rsn_ie_len, wpa_common_ctx::ap_rsn_is_rsn, net80211_device::associating, net80211_wlan::beacon, wpa_common_ctx::crypt, net80211_wlan::crypto, io_buffer::data, ieee80211_frame::data, wpa_common_ctx::dev, EINVAL, ENOENT, ENOMEM, wpa_common_ctx::gcrypt, hdr, ieee80211_beacon, wpa_common_ctx::list, list_add_tail, malloc(), memcpy(), NET80211_CRYPT_UNKNOWN, NULL, wpa_common_ctx::pmk, wpa_common_ctx::pmk_len, wpa_common_ctx::replay, net80211_device::rsn_ie, sec80211_find_rsn(), wpa_common_ctx::state, io_buffer::tail, and WPA_READY.

Referenced by wpa_psk_start().

{
        struct io_buffer *iob;
        struct ieee80211_frame *hdr;
        struct ieee80211_beacon *beacon;
        u8 *ap_rsn_ie = NULL, *ap_rsn_ie_end;

        if ( ! dev->rsn_ie || ! dev->associating )
                return -EINVAL;

        ctx->dev = dev;
        memcpy ( ctx->pmk, pmk, ctx->pmk_len = pmk_len );
        ctx->state = WPA_READY;
        ctx->replay = ~0ULL;

        iob = dev->associating->beacon;
        hdr = iob->data;
        beacon = ( struct ieee80211_beacon * ) hdr->data;
        ap_rsn_ie = sec80211_find_rsn ( beacon->info_element, iob->tail,
                                        &ctx->ap_rsn_is_rsn, &ap_rsn_ie_end );
        if ( ap_rsn_ie ) {
                ctx->ap_rsn_ie = malloc ( ap_rsn_ie_end - ap_rsn_ie );
                if ( ! ctx->ap_rsn_ie )
                        return -ENOMEM;
                memcpy ( ctx->ap_rsn_ie, ap_rsn_ie, ap_rsn_ie_end - ap_rsn_ie );
                ctx->ap_rsn_ie_len = ap_rsn_ie_end - ap_rsn_ie;
        } else {
                return -ENOENT;
        }

        ctx->crypt = dev->associating->crypto;
        ctx->gcrypt = NET80211_CRYPT_UNKNOWN;

        list_add_tail ( &ctx->list, &wpa_contexts );
        return 0;
}
void wpa_stop ( struct net80211_device dev)

Disable handling of received WPA handshake frames.

Parameters:
dev802.11 device

Definition at line 260 of file wpa.c.

References wpa_common_ctx::ap_rsn_ie, ctx, wpa_common_ctx::dev, free, wpa_common_ctx::list, list_del, list_for_each_entry_safe, and NULL.

Referenced by wpa_psk_stop().

{
        struct wpa_common_ctx *ctx, *tmp;

        list_for_each_entry_safe ( ctx, tmp, &wpa_contexts, list ) {
                if ( ctx->dev == dev ) {
                        free ( ctx->ap_rsn_ie );
                        ctx->ap_rsn_ie = NULL;
                        list_del ( &ctx->list );
                }
        }
}

Variable Documentation

One of the EAPOL_KEY_TYPE_* defines.

Definition at line 174 of file wpa.h.

Bitfield of key characteristics, network byte order.

Definition at line 177 of file wpa.h.

Length of encryption key to be used, network byte order.

This is 16 for CCMP, 32 for TKIP, and 5 or 13 for WEP.

Definition at line 183 of file wpa.h.

Monotonically increasing value for EAPOL-Key conversations.

In another classic demonstration of overengineering, this 8-byte value will rarely be anything above 1. It's stored in network byte order.

Definition at line 191 of file wpa.h.

Nonce value.

For Nonce-type KDEs, the nonce.

This is the authenticator's ANonce in frame 1, the peer's SNonce in frame 2, and 0 in frames 3 and 4.

Definition at line 198 of file wpa.h.

u8 iv[16]

Initialization vector.

This contains the IV used with the Key Encryption Key, or 0 if the key is unencrypted or encrypted using an algorithm that does not require an IV.

Definition at line 206 of file wpa.h.

Referenced by cipher_cost(), tls_assemble_block(), wep_decrypt(), and wep_encrypt().

u8 rsc[8]

Receive sequence counter for GTK.

This is used to synchronize the client's replay counter for ordinary data packets. The first six bytes contain PN0 through PN5 for CCMP mode, or TSC0 through TSC5 for TKIP mode. The last two bytes are zero.

Definition at line 215 of file wpa.h.

Referenced by tkip_init().

Reserved bytes.

Definition at line 218 of file wpa.h.

u8 mic[16]

Message integrity code over the entire EAPOL frame.

This is calculated using HMAC-MD5 when the key descriptor version field in info is 1, and HMAC-SHA1 ignoring the last 4 bytes of the hash when the version field in info is 2.

Definition at line 227 of file wpa.h.

Referenced by ccmp_encrypt(), tkip_decrypt(), and tkip_encrypt().

Length of the data field in bytes, network byte order.

Definition at line 230 of file wpa.h.

Referenced by ccmp_decrypt(), ccmp_encrypt(), tkip_decrypt(), tkip_encrypt(), wep_decrypt(), and wep_encrypt().

u8 data[0]

Key data.

This is formatted as a series of 802.11 information elements, with cryptographic data encapsulated using a "vendor-specific IE" code and an IEEE-specified OUI.

Definition at line 238 of file wpa.h.

MIC key for packets from the AP.

Definition at line 243 of file wpa.h.

MIC key for packets to the AP.

Definition at line 246 of file wpa.h.

Main key: input to TKIP Phase 1 and Phase 2 key mixing functions.

Definition at line 244 of file wpa.h.

EAPOL-Key Key Confirmation Key (KCK)

Definition at line 267 of file wpa.h.

EAPOL-Key Key Encryption Key (KEK)

Definition at line 270 of file wpa.h.

union wpa_tk tk

Temporal key.

Definition at line 273 of file wpa.h.

u8 id

Key ID and TX bit.

Definition at line 434 of file wpa.h.

Reserved byte.

Definition at line 437 of file wpa.h.

struct wpa_gtk gtk

Encapsulated group transient key.

Definition at line 440 of file wpa.h.

Information element type: always 0xDD (IEEE80211_IE_VENDOR)

Definition at line 497 of file wpa.h.

Length, not including ie_type and length fields.

Definition at line 500 of file wpa.h.

OUI + type byte.

Definition at line 503 of file wpa.h.

Referenced by rsn_pick_desc().

For GTK-type KDEs, encapsulated GTK.

Definition at line 508 of file wpa.h.

For MAC-type KDEs, the MAC address.

Definition at line 511 of file wpa.h.

For PMKID-type KDEs, the PMKID.

Definition at line 514 of file wpa.h.

For Lifetime-type KDEs, the lifetime in seconds.

This is in network byte order!

Definition at line 523 of file wpa.h.

Referenced by ndp_register_settings().

union { ... }

Payload data.