1 2=============================================== 3XFRM device - offloading the IPsec computations 4=============================================== 5Shannon Nelson <shannon.nelson@oracle.com> 6 7 8Overview 9======== 10 11IPsec is a useful feature for securing network traffic, but the 12computational cost is high: a 10Gbps link can easily be brought down 13to under 1Gbps, depending on the traffic and link configuration. 14Luckily, there are NICs that offer a hardware based IPsec offload which 15can radically increase throughput and decrease CPU utilization. The XFRM 16Device interface allows NIC drivers to offer to the stack access to the 17hardware offload. 18 19Userland access to the offload is typically through a system such as 20libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can 21be handy when experimenting. An example command might look something 22like this: 23 24 ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \ 25 reqid 0x07 replay-window 32 \ 26 aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \ 27 sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ 28 offload dev eth4 dir in 29 30Yes, that's ugly, but that's what shell scripts and/or libreswan are for. 31 32 33 34Callbacks to implement 35====================== 36 37/* from include/linux/netdevice.h */ 38struct xfrmdev_ops { 39 int (*xdo_dev_state_add) (struct xfrm_state *x); 40 void (*xdo_dev_state_delete) (struct xfrm_state *x); 41 void (*xdo_dev_state_free) (struct xfrm_state *x); 42 bool (*xdo_dev_offload_ok) (struct sk_buff *skb, 43 struct xfrm_state *x); 44 void (*xdo_dev_state_advance_esn) (struct xfrm_state *x); 45}; 46 47The NIC driver offering ipsec offload will need to implement these 48callbacks to make the offload available to the network stack's 49XFRM subsytem. Additionally, the feature bits NETIF_F_HW_ESP and 50NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload. 51 52 53 54Flow 55==== 56 57At probe time and before the call to register_netdev(), the driver should 58set up local data structures and XFRM callbacks, and set the feature bits. 59The XFRM code's listener will finish the setup on NETDEV_REGISTER. 60 61 adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops; 62 adapter->netdev->features |= NETIF_F_HW_ESP; 63 adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP; 64 65When new SAs are set up with a request for "offload" feature, the 66driver's xdo_dev_state_add() will be given the new SA to be offloaded 67and an indication of whether it is for Rx or Tx. The driver should 68 - verify the algorithm is supported for offloads 69 - store the SA information (key, salt, target-ip, protocol, etc) 70 - enable the HW offload of the SA 71 - return status value: 72 0 success 73 -EOPNETSUPP offload not supported, try SW IPsec 74 other fail the request 75 76The driver can also set an offload_handle in the SA, an opaque void pointer 77that can be used to convey context into the fast-path offload requests. 78 79 xs->xso.offload_handle = context; 80 81 82When the network stack is preparing an IPsec packet for an SA that has 83been setup for offload, it first calls into xdo_dev_offload_ok() with 84the skb and the intended offload state to ask the driver if the offload 85will serviceable. This can check the packet information to be sure the 86offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and 87return true of false to signify its support. 88 89When ready to send, the driver needs to inspect the Tx packet for the 90offload information, including the opaque context, and set up the packet 91send accordingly. 92 93 xs = xfrm_input_state(skb); 94 context = xs->xso.offload_handle; 95 set up HW for send 96 97The stack has already inserted the appropriate IPsec headers in the 98packet data, the offload just needs to do the encryption and fix up the 99header values. 100 101 102When a packet is received and the HW has indicated that it offloaded a 103decryption, the driver needs to add a reference to the decoded SA into 104the packet's skb. At this point the data should be decrypted but the 105IPsec headers are still in the packet data; they are removed later up 106the stack in xfrm_input(). 107 108 find and hold the SA that was used to the Rx skb 109 get spi, protocol, and destination IP from packet headers 110 xs = find xs from (spi, protocol, dest_IP) 111 xfrm_state_hold(xs); 112 113 store the state information into the skb 114 sp = secpath_set(skb); 115 if (!sp) return; 116 sp->xvec[sp->len++] = xs; 117 sp->olen++; 118 119 indicate the success and/or error status of the offload 120 xo = xfrm_offload(skb); 121 xo->flags = CRYPTO_DONE; 122 xo->status = crypto_status; 123 124 hand the packet to napi_gro_receive() as usual 125 126In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn(). 127Driver will check packet seq number and update HW ESN state machine if needed. 128 129When the SA is removed by the user, the driver's xdo_dev_state_delete() 130is asked to disable the offload. Later, xdo_dev_state_free() is called 131from a garbage collection routine after all reference counts to the state 132have been removed and any remaining resources can be cleared for the 133offload state. How these are used by the driver will depend on specific 134hardware needs. 135 136As a netdev is set to DOWN the XFRM stack's netdev listener will call 137xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded 138states. 139 140 141