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