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