Fix some it's -> its typos in our manual pages.
[dragonfly.git] / 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: 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
117 The
118 .Nm net80211
119 layer includes comprehensive cryptographic support for 802.11 protocols.
120 Software implementations of ciphers required by
121 WPA and 802.11i are provided as well as encap/decap processing of 802.11 frames.
122 Software ciphers are written as kernel modules and
123 register with the core crypto support.
124 The cryptographic framework supports hardware acceleration of ciphers
125 by drivers with automatic fall-back to software implementations when a
126 driver is unable to provide necessary hardware services.
127 .Sh CRYPTO CIPHER MODULES
128 .Nm net80211
129 cipher modules register their services using
130 .Fn ieee80211_crypto_register
131 and supply a template that describes their operation.
132 This
133 .Vt ieee80211_cipher
134 structure defines protocol-related state such as the number of bytes
135 of space in the 802.11 header to reserve/remove during encap/decap
136 and entry points for setting up keys and doing cryptographic operations.
137 .Pp
138 Cipher modules can associate private state to each key through the
139 .Vt wk_private
140 structure member.
141 If state is setup by the module it will be called before a key is destroyed
142 so it can reclaim resources.
143 .Pp
144 Crypto modules can notify the system of two events.
145 When a packet replay event is recognized
146 .Fn ieee80211_notify_replay_failure
147 can be used to signal the event.
148 When a
149 .Dv TKIP
150 Michael failure is detected
151 .Fn ieee80211_notify_michael_failure
152 can be invoked.
153 Drivers may also use these routines to signal events detected by the
154 hardware.
155 .Sh CRYPTO KEY MANAGEMENT
156 The
157 .Nm net80211
158 layer implements a per-vap 4-element
159 .Dq global key table
160 and a per-station
161 .Dq unicast key
162 for protocols such as WPA, 802.1x, and 802.11i.
163 The global key table is designed to support legacy WEP operation
164 and Multicast/Group keys,
165 though some applications also use it to implement WPA in station mode.
166 Keys in the global table are identified by a key index in the range 0-3.
167 Per-station keys are identified by the MAC address of the station and
168 are typically used for unicast PTK bindings.
169 .Pp
170 .Nm net80211
171 provides
172 .Xr ioctl 2
173 operations for managing both global and per-station keys.
174 Drivers typically do not participate in software key management;
175 they are involved only when providing hardware acceleration of
176 cryptographic operations.
177 .Pp
178 .Fn ieee80211_crypto_newkey
179 is used to allocate a new
180 .Nm net80211
181 key or reconfigure an existing key.
182 The cipher must be specified along with any fixed key index.
183 The
184 .Nm net80211
185 layer will handle allocating cipher and driver resources to support the key.
186 .Pp
187 Once a key is allocated it.Fn ieee80211_crypto_setkey
188 and deleted with
189 .Fn ieee80211_crypto_delkey
190 (with any cipher and driver resources reclaimed).
191 .Pp
192 .Fn ieee80211_crypto_delglobalkeys
193 is used to reclaim all keys in the global key table for a vap; it
194 typically is used only within the
195 .Nm net80211
196 layer.
197 .Pp
198 .Fn ieee80211_crypto_reload_keys
199 handles hardware key state reloading from software key state, such
200 as required after a suspend/resume cycle.
201 .Sh DRIVER CRYPTO SUPPORT
202 Drivers identify ciphers they have hardware support for through the
203 .Vt ic_cryptocaps
204 field of the
205 .Vt ieee80211com
206 structure.
207 If hardware support is available then a driver should also fill in the
208 .Dv iv_key_alloc ,
209 .Dv iv_key_set ,
210 and
211 .Dv iv_key_delete
212 methods of each
213 .Vt ieee80211vap
214 created for use with the device.
215 In addition the methods
216 .Dv iv_key_update_begin
217 and
218 .Dv iv_key_update_end
219 can be setup to handle synchronization requirements
220 for updating hardware key state.
221 .Pp
222 When
223 .Nm net80211
224 allocates a software key and the driver can accelerate the
225 cipher operations the
226 .Dv iv_key_alloc
227 method will be invoked.
228 Drivers may return a token that is associated with outbound traffic
229 (for use in encrypting frames).
230 Otherwise, e.g. if hardware resources are not available, the driver will
231 not return a token and
232 .Nm net80211
233 will arrange to do the work in software and pass frames
234 to the driver that are already prepared for transmission.
235 .Pp
236 For receive, drivers mark frames with the
237 .Dv M_WEP
238 mbuf flag to indicate the hardware has decrypted the payload.
239 If frames have the
240 .Dv IEEE80211_FC1_PROTECTED
241 bit marked in their 802.11 header and are not tagged with
242 .Dv M_WEP
243 then decryption is done in software.
244 For more complicated scenarios the software key state is consulted; e.g.
245 to decide if Michael verification needs to be done in software after
246 the hardware has handled TKIP decryption.
247 .Pp
248 Drivers that manage complicated key data structures, e.g. faulting
249 software keys into a hardware key cache, can safely manipulate software
250 key state by bracketing their work with calls to
251 .Fn ieee80211_key_update_begin
252 and
253 .Fn ieee80211_key_update_end .
254 These calls also synchronize hardware key state update
255 when receive traffic is active.
256 .Sh SEE ALSO
257 .Xr ioctl 2 ,
258 .Xr wlan_ccmp 4 ,
259 .Xr wlan_tkip 4 ,
260 .Xr wlan_wep 4 ,
261 .Xr ieee80211 9