/share/man/man9/ieee80211_crypto.9

  1.\"
  2.\" Copyright (c) 2004 Bruce M. Simpson <bms@spc.org>
  3.\" Copyright (c) 2004 Darron Broad <darron@kewl.org>
  4.\" All rights reserved.
  5.\"
  6.\" Redistribution and use in source and binary forms, with or without
  7.\" modification, are permitted provided that the following conditions
  8.\" are met:
  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.
 14.\"
 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
 25.\" SUCH DAMAGE.
 26.\"
 27.\" $FreeBSD$
 28.\" $Id: ieee80211_crypto.9,v 1.3 2004/03/04 10:42:56 bruce Exp $
 29.\"
 30.Dd March 29, 2010
 31.Dt IEEE80211_CRYPTO 9
 32.Os
 33.Sh NAME
 34.Nm ieee80211_crypto
 35.Nd 802.11 cryptographic support
 36.Sh SYNOPSIS
 37.In net80211/ieee80211_var.h
 38.\"
 39.Pp
 40.Ft void
 41.Fn ieee80211_crypto_register "const struct ieee80211_cipher *"
 42.\"
 43.Ft void
 44.Fn ieee80211_crypto_unregister "const struct ieee80211_cipher *"
 45.\"
 46.Ft int
 47.Fn ieee80211_crypto_available "int cipher"
 48.\"
 49.Pp
 50.Ft void
 51.Fo ieee80211_notify_replay_failure
 52.Fa "struct ieee80211vap *"
 53.Fa "const struct ieee80211_frame *"
 54.Fa "const struct ieee80211_key *"
 55.Fa "uint64_t rsc"
 56.Fa "int tid"
 57.Fc
 58.\"
 59.Ft void
 60.Fo ieee80211_notify_michael_failure
 61.Fa "struct ieee80211vap *"
 62.Fa "const struct ieee80211_frame *"
 63.Fa "u_int keyix"
 64.Fc
 65.\"
 66.Ft int
 67.Fo ieee80211_crypto_newkey
 68.Fa "struct ieee80211vap *"
 69.Fa "int cipher"
 70.Fa "int flags"
 71.Fa "struct ieee80211_key *"
 72.Fc
 73.\"
 74.Ft int
 75.Fn ieee80211_crypto_setkey "struct ieee80211vap *" "struct ieee80211_key *"
 76.\"
 77.Ft int
 78.Fn ieee80211_crypto_delkey "struct ieee80211vap *" "struct ieee80211_key *"
 79.\"
 80.Ft void
 81.Fn ieee80211_key_update_begin "struct ieee80211vap *"
 82.\"
 83.Ft void
 84.Fn ieee80211_key_update_end "struct ieee80211vap *"
 85.\"
 86.Ft void
 87.Fn ieee80211_crypto_delglobalkeys "struct ieee80211vap *"
 88.\"
 89.Ft void
 90.Fn ieee80211_crypto_reload_keys "struct ieee80211com *"
 91.\"
 92.Pp
 93.Ft struct ieee80211_key *
 94.Fn ieee80211_crypto_encap "struct ieee80211_node *" "struct mbuf *"
 95.\"
 96.Ft struct ieee80211_key *
 97.Fn ieee80211_crypto_decap "struct ieee80211_node *" "struct mbuf *" "int flags"
 98.\"
 99.Ft int
100.Fo ieee80211_crypto_demic
101.Fa "struct ieee80211vap *"
102.Fa "struct ieee80211_key *"
103.Fa "struct mbuf *"
104.Fa "int force"
105.Fc
106.\"
107.Ft int
108.Fo ieee80211_crypto_enmic
109.Fa "struct ieee80211vap *"
110.Fa "struct ieee80211_key *"
111.Fa "struct mbuf *"
112.Fa "int force"
113.Fc
114.Sh DESCRIPTION
115The
116.Nm net80211
117layer includes comprehensive cryptographic support for 802.11 protocols.
118Software implementations of ciphers required by
119WPA and 802.11i are provided as well as encap/decap processing of 802.11 frames.
120Software ciphers are written as kernel modules and
121register with the core crypto support.
122The cryptographic framework supports hardware acceleration of ciphers
123by drivers with automatic fall-back to software implementations when a
124driver is unable to provide necessary hardware services.
125.Sh CRYPTO CIPHER MODULES
126.Nm net80211
127cipher modules register their services using
128.Fn ieee80211_crypto_register
129and supply a template that describes their operation.
130This
131.Vt ieee80211_cipher
132structure defines protocol-related state such as the number of bytes
133of space in the 802.11 header to reserve/remove during encap/decap
134and entry points for setting up keys and doing cryptographic operations.
135.Pp
136Cipher modules can associate private state to each key through the
137.Vt wk_private
138structure member.
139If state is setup by the module it will be called before a key is destroyed
140so it can reclaim resources.
141.Pp
142Crypto modules can notify the system of two events.
143When a packet replay event is recognized
144.Fn ieee80211_notify_replay_failure
145can be used to signal the event.
146When a
147.Dv TKIP
148Michael failure is detected
149.Fn ieee80211_notify_michael_failure
150can be invoked.
151Drivers may also use these routines to signal events detected by the
152hardware.
153.Sh CRYPTO KEY MANAGEMENT
154The
155.Nm net80211
156layer implements a per-vap 4-element
157.Dq global key table
158and a per-station
159.Dq unicast key
160for protocols such as WPA, 802.1x, and 802.11i.
161The global key table is designed to support legacy WEP operation
162and Multicast/Group keys,
163though some applications also use it to implement WPA in station mode.
164Keys in the global table are identified by a key index in the range 0-3.
165Per-station keys are identified by the MAC address of the station and
166are typically used for unicast PTK bindings.
167.Pp
168.Nm net80211
169provides
170.Xr ioctl 2
171operations for managing both global and per-station keys.
172Drivers typically do not participate in software key management;
173they are involved only when providing hardware acceleration of
174cryptographic operations.
175.Pp
176.Fn ieee80211_crypto_newkey
177is used to allocate a new
178.Nm net80211
179key or reconfigure an existing key.
180The cipher must be specified along with any fixed key index.
181The
182.Nm net80211
183layer will handle allocating cipher and driver resources to support the key.
184.Pp
185Once a key is allocated it's contents can be set using
186.Fn ieee80211_crypto_setkey
187and deleted with
188.Fn ieee80211_crypto_delkey
189(with any cipher and driver resources reclaimed).
190.Pp
191.Fn ieee80211_crypto_delglobalkeys
192is used to reclaim all keys in the global key table for a vap; it
193typically is used only within the
194.Nm net80211
195layer.
196.Pp
197.Fn ieee80211_crypto_reload_keys
198handles hardware key state reloading from software key state, such
199as required after a suspend/resume cycle.
200.Sh DRIVER CRYPTO SUPPORT
201Drivers identify ciphers they have hardware support for through the
202.Vt ic_cryptocaps
203field of the
204.Vt ieee80211com
205structure.
206If hardware support is available then a driver should also fill in the
207.Dv iv_key_alloc ,
208.Dv iv_key_set ,
209and
210.Dv iv_key_delete
211methods of each
212.Vt ieee80211vap
213created for use with the device.
214In addition the methods
215.Dv iv_key_update_begin
216and
217.Dv iv_key_update_end
218can be setup to handle synchronization requirements
219for updating hardware key state.
220.Pp
221When
222.Nm net80211
223allocates a software key and the driver can accelerate the
224cipher operations the
225.Dv iv_key_alloc
226method will be invoked.
227Drivers may return a token that is associated with outbound traffic
228(for use in encrypting frames).
229Otherwise, e.g. if hardware resources are not available, the driver will
230not return a token and
231.Nm net80211
232will arrange to do the work in software and pass frames
233to the driver that are already prepared for transmission.
234.Pp
235For receive, drivers mark frames with the
236.Dv M_WEP
237mbuf flag to indicate the hardware has decrypted the payload.
238If frames have the
239.Dv IEEE80211_FC1_WEP
240bit marked in their 802.11 header and are not tagged with
241.Dv M_WEP
242then decryption is done in software.
243For more complicated scenarios the software key state is consulted; e.g.
244to decide if Michael verification needs to be done in software after
245the hardware has handled TKIP decryption.
246.Pp
247Drivers that manage complicated key data structures, e.g. faulting
248software keys into a hardware key cache, can safely manipulate software
249key state by bracketing their work with calls to
250.Fn ieee80211_key_update_begin
251and
252.Fn ieee80211_key_update_end .
253These calls also synchronize hardware key state update
254when receive traffic is active.
255.Sh SEE ALSO
256.Xr ieee80211 9 ,
257.Xr ioctl 2 ,
258.Xr wlan_ccmp 4 ,
259.Xr wlan_tkip 4 ,
260.Xr wlan_wep 4