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