iwd/doc/wpa-auth.txt

Introduction
============

This document describes the various stages of the authentication / association
process for WPA/WPA2 Networks.  It is intended to give the reader a 'map' of
what pieces come into play and when.

For a more broad overview of authentication procedures, refer to Section
4.10.3 of 802.11.

WPA is an earlier stop-gap solution to WEP security vulnerabilities.
Essentially it is a subset of draft 802.11i.  WPA2 refers to the released
802.11i specification.  WPA2 is more of a marketing term; term used inside
802.11 is RSN (Robust Security Network).  Typically WPA uses TKIP with RC4
(also known as ARC4) stream cipher.  WPA2 uses CCMP with AES stream cipher
which must always be supported.  TKIP with ARC4 is also a supported mode of
operation.


Overview of Getting Connected
=============================

To get connected to a typical WPA2 network the user must first know the
Pre-Shared-Key or PSK.  This key can be generated based on a passphrase
instead of being entered in hex form by the user.  The passphrase generation
is specified in 802.11, Annex M.4.  Since the PSK should be long-lived, it
should not be exposed over-the-air.  For this purpose the PSK is not used
directly; instead a session key is derived.  The process for derivation of
this key is called the 4-Way Handshake.

For the purposes of the 4-Way Handshake below, PSK becomes the PMK (Pairwise
Master Key).  The PMK is also obtained from an EAP exchange, but that is a
different topic.

4-Way Handshake generates a key referred to as the PTK (Pairwise Transient
Key).  PTK is generated by feeding the PMK, AP Nonce (ANonce), STA Nonce
(SNonce), AP MAC Address and the STA MAC Address through a hashing function.
The SNonce and ANonce are randomly generated numbers and are exchanged by the
STA and the AP during the initial two steps of the Four-Way Handshake.  The
third step of the handshake establishes the GTK (Group Temporal Key). The
fourth step serves as the acknowledgement step.

The Four-Way Handshake is accomplished by exchanging EAPoL-Key protocol frames
after performing OPEN_SYSTEM Association to the target AP.


Key Derivation
==============

The PTK obtained from the 4-Way handshake is divided into 3 separate keys:

- 16 byte KCK (Confirmation Key).  The KCK is used in the computation of the
  MIC field used by EAPoL-Key frames.  The KCK is used as input to HMAC-MD5,
  HMAC-SHA1 or CMAC-AES depending on what hashing function is used.

- 16 byte KEK (Encryption Key).  The KEK is used to encrypt data in message 3
  if it contains the GTK.

- 16 byte TK (Temporal Key).  Used to encrypt / decrypt normal packets flowing
  between the STA and the AP.

If TKIP used, then the following elements are also derived from the same PTK:

- 8 byte Michael MIC Authenticator TX Key
- 8 byte Michael MIC Authenticator RX Key

For more details on the Four-Way Handshake, refer to 802.11 Section 11.6.2


Overall Process
===============

- The user selects a network to connect to.  This network can be known
  implicitly or via a scan.  A Probe request or a Beacon must first be
  received and the RSN IE must be stored in order to connect to the AP.  The
  RSN element contains the security parameters supported by the BSS.  This RSN
  element must also be compared against the RSN element received from the AP
  in message 3 of the 4-Way Handshake.

- OPEN_SYSTEM Authentication and Association requests are sent to the AP.  In
  the case of the Association request, the RSN element with the selected
  encryption parameters must be included.

- Once the OPEN_SYSTEM Association is successful, the AP shall send Message 1
  of the 4-Way Handshake.  This comes in the form of EAPoL-Key messages and
  require special privileges / setup in order to be read from the netdev
  device.

- STA records all necessary parameters from Message 1 (ANonce, Key Replay
  Counter).  STA Generates the PTK, constructs Message 2 and sends it to the
  AP.

- Once Message 3 is received from the AP, the STA sanity checks certain
  parameters (Key Replay Counter, ANonce, MIC).  The RSN received from the AP
  is also checked against the one received in Message 3.  If everything checks
  out, then Message 4 is constructed and sent to the AP.

- Based on TK and GTK, the keys are set into the hardware.  The Re-Key offload
  is enabled as well (if supported?)

  Here's an example of how this looks like:

< Request: New Key (0x0b) len 68 [ack]
    Key Data: len 16
        3c 7d 08 8b 94 10 0f 21 06 6d 7b 18 a1 7e e0 ad
    Key Cipher: CCMP (0x000fac04)
    Key Sequence: len 6
        00 00 00 00 00 00
    MAC Address: 24:A2:E1:EC:17:04
    Key Index: 0 (0x00)
    Interface Index: 3 (0x00000003)

< Request: Set Key (0x0a) len 28 [ack]
    Key Index: 0 (0x00)
    Interface Index: 3 (0x00000003)
    Key Default: true
    Key Default Types: len 4
        Unicast: true

< Request: New Key (0x0b) len 64 [ack]
    Key Data: len 16
        2e 15 6e 7c 4e 3d f1 37 09 13 ed bd 62 8e 25 65
    Key Cipher: CCMP (0x000fac04)
    Key Sequence: len 6
        00 00 00 00 00 00
    Key Default Types: len 4
        Multicast: true
    Key Index: 2 (0x02)
    Interface Index: 3

< Request: Set Rekey Offload (0x4f) len 64 [ack]
    Interface Index: 3 (0x00000003)
    Rekey Data: len 52
        14 00 01 00 24 7a 90 94 e5 43 de 1b 1e 3d d4 a0
        5c d0 e7 76 14 00 02 00 28 4d b5 b1 cf bc e4 25
        f4 f5 00 47 64 83 87 bc 0c 00 03 00 00 00 00
	00 00 00 01