1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>Chapter 8. Hardware crypto acceleration</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="The 802.11 subsystems – for kernel developers"><link rel="up" href="advanced.html" title="Part II. Advanced driver interface"><link rel="prev" href="API-ieee80211-create-tpt-led-trigger.html" title="ieee80211_create_tpt_led_trigger"><link rel="next" href="API-enum-set-key-cmd.html" title="enum set_key_cmd"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 8. Hardware crypto acceleration</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-ieee80211-create-tpt-led-trigger.html">Prev</a> </td><th width="60%" align="center">Part II. Advanced driver interface</th><td width="20%" align="right"> <a accesskey="n" href="API-enum-set-key-cmd.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="hardware-crypto-offload"></a>Chapter 8. Hardware crypto acceleration</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="refentrytitle"><a href="API-enum-set-key-cmd.html"><span class="phrase">enum set_key_cmd</span></a></span><span class="refpurpose"> — 2 key command 3 </span></dt><dt><span class="refentrytitle"><a href="API-struct-ieee80211-key-conf.html"><span class="phrase">struct ieee80211_key_conf</span></a></span><span class="refpurpose"> — 4 key information 5 </span></dt><dt><span class="refentrytitle"><a href="API-enum-ieee80211-key-flags.html"><span class="phrase">enum ieee80211_key_flags</span></a></span><span class="refpurpose"> — 6 key flags 7 </span></dt><dt><span class="refentrytitle"><a href="API-ieee80211-get-tkip-p1k.html"><span class="phrase">ieee80211_get_tkip_p1k</span></a></span><span class="refpurpose"> — 8 get a TKIP phase 1 key 9 </span></dt><dt><span class="refentrytitle"><a href="API-ieee80211-get-tkip-p1k-iv.html"><span class="phrase">ieee80211_get_tkip_p1k_iv</span></a></span><span class="refpurpose"> — 10 get a TKIP phase 1 key for IV32 11 </span></dt><dt><span class="refentrytitle"><a href="API-ieee80211-get-tkip-p2k.html"><span class="phrase">ieee80211_get_tkip_p2k</span></a></span><span class="refpurpose"> — 12 get a TKIP phase 2 key 13 </span></dt></dl></div><p> 14 </p><p> 15 mac80211 is capable of taking advantage of many hardware 16 acceleration designs for encryption and decryption operations. 17 </p><p> 18 The <code class="function">set_key</code> callback in the <span class="structname">struct ieee80211_ops</span> for a given 19 device is called to enable hardware acceleration of encryption and 20 decryption. The callback takes a <em class="parameter"><code>sta</code></em> parameter that will be NULL 21 for default keys or keys used for transmission only, or point to 22 the station information for the peer for individual keys. 23 Multiple transmission keys with the same key index may be used when 24 VLANs are configured for an access point. 25 </p><p> 26 When transmitting, the TX control data will use the <em class="parameter"><code>hw_key_idx</code></em> 27 selected by the driver by modifying the <span class="structname">struct ieee80211_key_conf</span> 28 pointed to by the <em class="parameter"><code>key</code></em> parameter to the <code class="function">set_key</code> function. 29 </p><p> 30 The <code class="function">set_key</code> call for the <code class="constant">SET_KEY</code> command should return 0 if 31 the key is now in use, -<code class="constant">EOPNOTSUPP</code> or -<code class="constant">ENOSPC</code> if it couldn't be 32 added; if you return 0 then hw_key_idx must be assigned to the 33 hardware key index, you are free to use the full u8 range. 34 </p><p> 35 Note that in the case that the <em class="parameter"><code>IEEE80211_HW_SW_CRYPTO_CONTROL</code></em> flag is 36 set, mac80211 will not automatically fall back to software crypto if 37 enabling hardware crypto failed. The <code class="function">set_key</code> call may also return the 38 value 1 to permit this specific key/algorithm to be done in software. 39 </p><p> 40 When the cmd is <code class="constant">DISABLE_KEY</code> then it must succeed. 41 </p><p> 42 Note that it is permissible to not decrypt a frame even if a key 43 for it has been uploaded to hardware, the stack will not make any 44 decision based on whether a key has been uploaded or not but rather 45 based on the receive flags. 46 </p><p> 47 The <span class="structname">struct ieee80211_key_conf</span> structure pointed to by the <em class="parameter"><code>key</code></em> 48 parameter is guaranteed to be valid until another call to <code class="function">set_key</code> 49 removes it, but it can only be used as a cookie to differentiate 50 keys. 51 </p><p> 52 In TKIP some HW need to be provided a phase 1 key, for RX decryption 53 acceleration (i.e. iwlwifi). Those drivers should provide update_tkip_key 54 handler. 55 The <code class="function">update_tkip_key</code> call updates the driver with the new phase 1 key. 56 This happens every time the iv16 wraps around (every 65536 packets). The 57 <code class="function">set_key</code> call will happen only once for each key (unless the AP did 58 rekeying), it will not include a valid phase 1 key. The valid phase 1 key is 59 provided by update_tkip_key only. The trigger that makes mac80211 call this 60 handler is software decryption with wrap around of iv16. 61 </p><p> 62 The <code class="function">set_default_unicast_key</code> call updates the default WEP key index 63 configured to the hardware for WEP encryption type. This is required 64 for devices that support offload of data packets (e.g. ARP responses). 65</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-ieee80211-create-tpt-led-trigger.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="advanced.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-enum-set-key-cmd.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">ieee80211_create_tpt_led_trigger</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">enum set_key_cmd</span></td></tr></table></div></body></html> 66