DESCRIPTION

The net80211 layer includes comprehensive cryptographic support for
802.11 protocols. Software implementations of ciphers required by WPA
and 802.11i are provided as well as encap/decap processing of 802.11
frames. Software ciphers are written as kernel modules and register with
the core crypto support. The cryptographic framework supports hardware
acceleration of ciphers by drivers with automatic fall-back to software
implementations when a driver is unable to provide necessary hardware
services.

CRYPTOCIPHERMODULES

net80211 cipher modules register their services using
ieee80211_crypto_register() and supply a template that describes their
operation. This ieee80211_cipher structure defines protocol-related
state such as the number of bytes of space in the 802.11 header to
reserve/remove during encap/decap and entry points for setting up keys
and doing cryptographic operations.
Cipher modules can associate private state to each key through the
wk_private structure member. If state is setup by the module it will be
called before a key is destroyed so it can reclaim resources.
Crypto modules can notify the system of two events. When a packet replay
event is recognized ieee80211_notify_replay_failure() can be used to
signal the event. When a TKIP Michael failure is detected
ieee80211_notify_michael_failure() can be invoked. Drivers may also use
these routines to signal events detected by the hardware.

CRYPTOKEYMANAGEMENT

The net80211 layer implements a per-vap 4-element “global key table” and
a per-station “unicast key” for protocols such as WPA, 802.1x, and
802.11i. The global key table is designed to support legacy WEP
operation and Multicast/Group keys, though some applications also use it
to implement WPA in station mode. Keys in the global table are
identified by a key index in the range 0-3. Per-station keys are
identified by the MAC address of the station and are typically used for
unicast PTK bindings.
net80211 provides ioctl(2) operations for managing both global and per-
station keys. Drivers typically do not participate in software key
management; they are involved only when providing hardware acceleration
of cryptographic operations.
ieee80211_crypto_newkey() is used to allocate a new net80211 key or
reconfigure an existing key. The cipher must be specified along with any
fixed key index. The net80211 layer will handle allocating cipher and
driver resources to support the key.
Once a key is allocated it’s contents can be set using
ieee80211_crypto_setkey() and deleted with ieee80211_crypto_delkey()
(with any cipher and driver resources reclaimed).
ieee80211_crypto_delglobalkeys() is used to reclaim all keys in the
global key table for a vap; it typically is used only within the net80211
layer.
ieee80211_crypto_reload_keys() handles hardware key state reloading from
software key state, such as required after a suspend/resume cycle.

DRIVERCRYPTOSUPPORT

Drivers identify ciphers they have hardware support for through the
ic_cryptocaps field of the ieee80211com structure. If hardware support
is available then a driver should also fill in the iv_key_alloc,
iv_key_set, and iv_key_delete methods of each ieee80211vap created for
use with the device. In addition the methods iv_key_update_begin and
iv_key_update_end can be setup to handle synchronization requirements for
updating hardware key state.
When net80211 allocates a software key and the driver can accelerate the
cipher operations the iv_key_alloc method will be invoked. Drivers may
return a token that is associated with outbound traffic (for use in
encrypting frames). Otherwise, e.g. if hardware resources are not
available, the driver will not return a token and net80211 will arrange
to do the work in software and pass frames to the driver that are already
prepared for transmission.
For receive, drivers mark frames with the M_WEP mbuf flag to indicate the
hardware has decrypted the payload. If frames have the IEEE80211_FC1_WEP
bit marked in their 802.11 header and are not tagged with M_WEP then
decryption is done in software. For more complicated scenarios the
software key state is consulted; e.g. to decide if Michael verification
needs to be done in software after the hardware has handled TKIP
decryption.
Drivers that manage complicated key data structures, e.g. faulting
software keys into a hardware key cache, can safely manipulate software
key state by bracketing their work with calls to
ieee80211_key_update_begin() and ieee80211_key_update_end(). These calls
also synchronize hardware key state update when receive traffic is
active.