/share/man/man9/ieee80211_crypto.9

https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 260 lines · 260 code · 0 blank · 0 comment · 0 complexity · 2c636b16a435df230b72624814a73c23 MD5 · raw file

  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
  115. The
  116. .Nm net80211
  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
  126. .Nm net80211
  127. cipher modules register their services using
  128. .Fn ieee80211_crypto_register
  129. and supply a template that describes their operation.
  130. This
  131. .Vt ieee80211_cipher
  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.
  135. .Pp
  136. Cipher modules can associate private state to each key through the
  137. .Vt wk_private
  138. structure member.
  139. If state is setup by the module it will be called before a key is destroyed
  140. so it can reclaim resources.
  141. .Pp
  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.
  146. When a
  147. .Dv TKIP
  148. Michael failure is detected
  149. .Fn ieee80211_notify_michael_failure
  150. can be invoked.
  151. Drivers may also use these routines to signal events detected by the
  152. hardware.
  153. .Sh CRYPTO KEY MANAGEMENT
  154. The
  155. .Nm net80211
  156. layer implements a per-vap 4-element
  157. .Dq global key table
  158. and a per-station
  159. .Dq unicast key
  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.
  167. .Pp
  168. .Nm net80211
  169. provides
  170. .Xr ioctl 2
  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.
  175. .Pp
  176. .Fn ieee80211_crypto_newkey
  177. is used to allocate a new
  178. .Nm net80211
  179. key or reconfigure an existing key.
  180. The cipher must be specified along with any fixed key index.
  181. The
  182. .Nm net80211
  183. layer will handle allocating cipher and driver resources to support the key.
  184. .Pp
  185. Once a key is allocated it's contents can be set using
  186. .Fn ieee80211_crypto_setkey
  187. and deleted with
  188. .Fn ieee80211_crypto_delkey
  189. (with any cipher and driver resources reclaimed).
  190. .Pp
  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
  194. .Nm net80211
  195. layer.
  196. .Pp
  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
  202. .Vt ic_cryptocaps
  203. field of the
  204. .Vt ieee80211com
  205. structure.
  206. If hardware support is available then a driver should also fill in the
  207. .Dv iv_key_alloc ,
  208. .Dv iv_key_set ,
  209. and
  210. .Dv iv_key_delete
  211. methods of each
  212. .Vt ieee80211vap
  213. created for use with the device.
  214. In addition the methods
  215. .Dv iv_key_update_begin
  216. and
  217. .Dv iv_key_update_end
  218. can be setup to handle synchronization requirements
  219. for updating hardware key state.
  220. .Pp
  221. When
  222. .Nm net80211
  223. allocates a software key and the driver can accelerate the
  224. cipher operations the
  225. .Dv iv_key_alloc
  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
  231. .Nm net80211
  232. will arrange to do the work in software and pass frames
  233. to the driver that are already prepared for transmission.
  234. .Pp
  235. For receive, drivers mark frames with the
  236. .Dv M_WEP
  237. mbuf flag to indicate the hardware has decrypted the payload.
  238. If frames have the
  239. .Dv IEEE80211_FC1_WEP
  240. bit marked in their 802.11 header and are not tagged with
  241. .Dv M_WEP
  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.
  246. .Pp
  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
  251. and
  252. .Fn ieee80211_key_update_end .
  253. These calls also synchronize hardware key state update
  254. when 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