2 .\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
3 .\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
15 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
16 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
17 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
18 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
19 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
20 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
21 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
22 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" $Id: ieee80211_crypto.9,v 1.3 2004/03/04 10:42:56 bruce Exp $
31 .Dt IEEE80211_CRYPTO 9
35 .Nd 802.11 cryptographic support
37 .In net80211/ieee80211_var.h
41 .Fn ieee80211_crypto_register "const struct ieee80211_cipher *"
44 .Fn ieee80211_crypto_unregister "const struct ieee80211_cipher *"
47 .Fn ieee80211_crypto_available "int cipher"
51 .Fo ieee80211_notify_replay_failure
52 .Fa "struct ieee80211vap *"
53 .Fa "const struct ieee80211_frame *"
54 .Fa "const struct ieee80211_key *"
60 .Fo ieee80211_notify_michael_failure
61 .Fa "struct ieee80211vap *"
62 .Fa "const struct ieee80211_frame *"
67 .Fo ieee80211_crypto_newkey
68 .Fa "struct ieee80211vap *"
71 .Fa "struct ieee80211_key *"
75 .Fn ieee80211_crypto_setkey "struct ieee80211vap *" "struct ieee80211_key *"
78 .Fn ieee80211_crypto_delkey "struct ieee80211vap *" "struct ieee80211_key *"
81 .Fn ieee80211_key_update_begin "struct ieee80211vap *"
84 .Fn ieee80211_key_update_end "struct ieee80211vap *"
87 .Fn ieee80211_crypto_delglobalkeys "struct ieee80211vap *"
90 .Fn ieee80211_crypto_reload_keys "struct ieee80211com *"
93 .Ft struct ieee80211_key *
94 .Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *"
96 .Ft struct ieee80211_key *
97 .Fn ieee80211_crypto_decap "struct ieee80211_node *" "struct mbuf *" "int flags"
100 .Fo ieee80211_crypto_demic
101 .Fa "struct ieee80211vap *"
102 .Fa "struct ieee80211_key *"
108 .Fo ieee80211_crypto_enmic
109 .Fa "struct ieee80211vap *"
110 .Fa "struct ieee80211_key *"
117 layer includes comprehensive cryptographic support for 802.11 protocols.
118 Software implementations of ciphers required by
119 WPA and 802.11i are provided as well as encap/decap processing of 802.11 frames.
120 Software ciphers are written as kernel modules and
121 register with the core crypto support.
122 The cryptographic framework supports hardware acceleration of ciphers
123 by drivers with automatic fall-back to software implementations when a
124 driver is unable to provide necessary hardware services.
125 .Sh CRYPTO CIPHER MODULES
127 cipher modules register their services using
128 .Fn ieee80211_crypto_register
129 and supply a template that describes their operation.
132 structure defines protocol-related state such as the number of bytes
133 of space in the 802.11 header to reserve/remove during encap/decap
134 and entry points for setting up keys and doing cryptographic operations.
136 Cipher modules can associate private state to each key through the
139 If state is setup by the module it will be called before a key is destroyed
140 so it can reclaim resources.
142 Crypto modules can notify the system of two events.
143 When a packet replay event is recognized
144 .Fn ieee80211_notify_replay_failure
145 can be used to signal the event.
148 Michael failure is detected
149 .Fn ieee80211_notify_michael_failure
151 Drivers may also use these routines to signal events detected by the
153 .Sh CRYPTO KEY MANAGEMENT
156 layer implements a per-vap 4-element
160 for protocols such as WPA, 802.1x, and 802.11i.
161 The global key table is designed to support legacy WEP operation
162 and Multicast/Group keys,
163 though some applications also use it to implement WPA in station mode.
164 Keys in the global table are identified by a key index in the range 0-3.
165 Per-station keys are identified by the MAC address of the station and
166 are typically used for unicast PTK bindings.
171 operations for managing both global and per-station keys.
172 Drivers typically do not participate in software key management;
173 they are involved only when providing hardware acceleration of
174 cryptographic operations.
176 .Fn ieee80211_crypto_newkey
177 is used to allocate a new
179 key or reconfigure an existing key.
180 The cipher must be specified along with any fixed key index.
183 layer will handle allocating cipher and driver resources to support the key.
185 Once a key is allocated it's contents can be set using
186 .Fn ieee80211_crypto_setkey
188 .Fn ieee80211_crypto_delkey
189 (with any cipher and driver resources reclaimed).
191 .Fn ieee80211_crypto_delglobalkeys
192 is used to reclaim all keys in the global key table for a vap; it
193 typically is used only within the
197 .Fn ieee80211_crypto_reload_keys
198 handles hardware key state reloading from software key state, such
199 as required after a suspend/resume cycle.
200 .Sh DRIVER CRYPTO SUPPORT
201 Drivers identify ciphers they have hardware support for through the
206 If hardware support is available then a driver should also fill in the
213 created for use with the device.
214 In addition the methods
215 .Dv iv_key_update_begin
217 .Dv iv_key_update_end
218 can be setup to handle synchronization requirements
219 for updating hardware key state.
223 allocates a software key and the driver can accelerate the
224 cipher operations the
226 method will be invoked.
227 Drivers may return a token that is associated with outbound traffic
228 (for use in encrypting frames).
229 Otherwise, e.g. if hardware resources are not available, the driver will
230 not return a token and
232 will arrange to do the work in software and pass frames
233 to the driver that are already prepared for transmission.
235 For receive, drivers mark frames with the
237 mbuf flag to indicate the hardware has decrypted the payload.
239 .Dv IEEE80211_FC1_PROTECTED
240 bit marked in their 802.11 header and are not tagged with
242 then decryption is done in software.
243 For more complicated scenarios the software key state is consulted; e.g.
244 to decide if Michael verification needs to be done in software after
245 the hardware has handled TKIP decryption.
247 Drivers that manage complicated key data structures, e.g. faulting
248 software keys into a hardware key cache, can safely manipulate software
249 key state by bracketing their work with calls to
250 .Fn ieee80211_key_update_begin
252 .Fn ieee80211_key_update_end .
253 These calls also synchronize hardware key state update
254 when receive traffic is active.