0001 .. SPDX-License-Identifier: GPL-2.0
0002
0003 ===============================================
0004 XFRM device - offloading the IPsec computations
0005 ===============================================
0006
0007 Shannon Nelson <shannon.nelson@oracle.com>
0008
0009
0010 Overview
0011 ========
0012
0013 IPsec is a useful feature for securing network traffic, but the
0014 computational cost is high: a 10Gbps link can easily be brought down
0015 to under 1Gbps, depending on the traffic and link configuration.
0016 Luckily, there are NICs that offer a hardware based IPsec offload which
0017 can radically increase throughput and decrease CPU utilization. The XFRM
0018 Device interface allows NIC drivers to offer to the stack access to the
0019 hardware offload.
0020
0021 Userland access to the offload is typically through a system such as
0022 libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can
0023 be handy when experimenting. An example command might look something
0024 like this::
0025
0026 ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \
0027 reqid 0x07 replay-window 32 \
0028 aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \
0029 sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \
0030 offload dev eth4 dir in
0031
0032 Yes, that's ugly, but that's what shell scripts and/or libreswan are for.
0033
0034
0035
0036 Callbacks to implement
0037 ======================
0038
0039 ::
0040
0041 /* from include/linux/netdevice.h */
0042 struct xfrmdev_ops {
0043 int (*xdo_dev_state_add) (struct xfrm_state *x);
0044 void (*xdo_dev_state_delete) (struct xfrm_state *x);
0045 void (*xdo_dev_state_free) (struct xfrm_state *x);
0046 bool (*xdo_dev_offload_ok) (struct sk_buff *skb,
0047 struct xfrm_state *x);
0048 void (*xdo_dev_state_advance_esn) (struct xfrm_state *x);
0049 };
0050
0051 The NIC driver offering ipsec offload will need to implement these
0052 callbacks to make the offload available to the network stack's
0053 XFRM subsystem. Additionally, the feature bits NETIF_F_HW_ESP and
0054 NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload.
0055
0056
0057
0058 Flow
0059 ====
0060
0061 At probe time and before the call to register_netdev(), the driver should
0062 set up local data structures and XFRM callbacks, and set the feature bits.
0063 The XFRM code's listener will finish the setup on NETDEV_REGISTER.
0064
0065 ::
0066
0067 adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops;
0068 adapter->netdev->features |= NETIF_F_HW_ESP;
0069 adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP;
0070
0071 When new SAs are set up with a request for "offload" feature, the
0072 driver's xdo_dev_state_add() will be given the new SA to be offloaded
0073 and an indication of whether it is for Rx or Tx. The driver should
0074
0075 - verify the algorithm is supported for offloads
0076 - store the SA information (key, salt, target-ip, protocol, etc)
0077 - enable the HW offload of the SA
0078 - return status value:
0079
0080 =========== ===================================
0081 0 success
0082 -EOPNETSUPP offload not supported, try SW IPsec
0083 other fail the request
0084 =========== ===================================
0085
0086 The driver can also set an offload_handle in the SA, an opaque void pointer
0087 that can be used to convey context into the fast-path offload requests::
0088
0089 xs->xso.offload_handle = context;
0090
0091
0092 When the network stack is preparing an IPsec packet for an SA that has
0093 been setup for offload, it first calls into xdo_dev_offload_ok() with
0094 the skb and the intended offload state to ask the driver if the offload
0095 will serviceable. This can check the packet information to be sure the
0096 offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and
0097 return true of false to signify its support.
0098
0099 When ready to send, the driver needs to inspect the Tx packet for the
0100 offload information, including the opaque context, and set up the packet
0101 send accordingly::
0102
0103 xs = xfrm_input_state(skb);
0104 context = xs->xso.offload_handle;
0105 set up HW for send
0106
0107 The stack has already inserted the appropriate IPsec headers in the
0108 packet data, the offload just needs to do the encryption and fix up the
0109 header values.
0110
0111
0112 When a packet is received and the HW has indicated that it offloaded a
0113 decryption, the driver needs to add a reference to the decoded SA into
0114 the packet's skb. At this point the data should be decrypted but the
0115 IPsec headers are still in the packet data; they are removed later up
0116 the stack in xfrm_input().
0117
0118 find and hold the SA that was used to the Rx skb::
0119
0120 get spi, protocol, and destination IP from packet headers
0121 xs = find xs from (spi, protocol, dest_IP)
0122 xfrm_state_hold(xs);
0123
0124 store the state information into the skb::
0125
0126 sp = secpath_set(skb);
0127 if (!sp) return;
0128 sp->xvec[sp->len++] = xs;
0129 sp->olen++;
0130
0131 indicate the success and/or error status of the offload::
0132
0133 xo = xfrm_offload(skb);
0134 xo->flags = CRYPTO_DONE;
0135 xo->status = crypto_status;
0136
0137 hand the packet to napi_gro_receive() as usual
0138
0139 In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn().
0140 Driver will check packet seq number and update HW ESN state machine if needed.
0141
0142 When the SA is removed by the user, the driver's xdo_dev_state_delete()
0143 is asked to disable the offload. Later, xdo_dev_state_free() is called
0144 from a garbage collection routine after all reference counts to the state
0145 have been removed and any remaining resources can be cleared for the
0146 offload state. How these are used by the driver will depend on specific
0147 hardware needs.
0148
0149 As a netdev is set to DOWN the XFRM stack's netdev listener will call
0150 xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded
0151 states.
