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