Documentation/networking/xfrm_device.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ===============================================
   4 XFRM device - offloading the IPsec computations
   5 ===============================================
   6
   7 Shannon Nelson <shannon.nelson@oracle.com>
   8
   9
  10 Overview
  11 ========
  12
  13 IPsec is a useful feature for securing network traffic, but the
  14 computational cost is high: a 10Gbps link can easily be brought down
  15 to under 1Gbps, depending on the traffic and link configuration.
  16 Luckily, there are NICs that offer a hardware based IPsec offload which
  17 can radically increase throughput and decrease CPU utilization.  The XFRM
  18 Device interface allows NIC drivers to offer to the stack access to the
  19 hardware offload.
  20
  21 Userland access to the offload is typically through a system such as
  22 libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can
  23 be handy when experimenting.  An example command might look something
  24 like 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
  32 Yes, that's ugly, but that's what shell scripts and/or libreswan are for.
  33
  34
  35
  36 Callbacks 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
  51 The NIC driver offering ipsec offload will need to implement these
  52 callbacks to make the offload available to the network stack's
  53 XFRM subsystem.  Additionally, the feature bits NETIF_F_HW_ESP and
  54 NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload.
  55
  56
  57
  58 Flow
  59 ====
  60
  61 At probe time and before the call to register_netdev(), the driver should
  62 set up local data structures and XFRM callbacks, and set the feature bits.
  63 The 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
  71 When new SAs are set up with a request for "offload" feature, the
  72 driver's xdo_dev_state_add() will be given the new SA to be offloaded
  73 and 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
  86 The driver can also set an offload_handle in the SA, an opaque void pointer
  87 that can be used to convey context into the fast-path offload requests::
  88
  89                 xs->xso.offload_handle = context;
  90
  91
  92 When the network stack is preparing an IPsec packet for an SA that has
  93 been setup for offload, it first calls into xdo_dev_offload_ok() with
  94 the skb and the intended offload state to ask the driver if the offload
  95 will serviceable.  This can check the packet information to be sure the
  96 offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and
  97 return true of false to signify its support.
  98
  99 When ready to send, the driver needs to inspect the Tx packet for the
 100 offload information, including the opaque context, and set up the packet
 101 send accordingly::
 102
 103                 xs = xfrm_input_state(skb);
 104                 context = xs->xso.offload_handle;
 105                 set up HW for send
 106
 107 The stack has already inserted the appropriate IPsec headers in the
 108 packet data, the offload just needs to do the encryption and fix up the
 109 header values.
 110
 111
 112 When a packet is received and the HW has indicated that it offloaded a
 113 decryption, the driver needs to add a reference to the decoded SA into
 114 the packet's skb.  At this point the data should be decrypted but the
 115 IPsec headers are still in the packet data; they are removed later up
 116 the 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
 139 In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn().
 140 Driver will check packet seq number and update HW ESN state machine if needed.
 141
 142 When the SA is removed by the user, the driver's xdo_dev_state_delete()
 143 is asked to disable the offload.  Later, xdo_dev_state_free() is called
 144 from a garbage collection routine after all reference counts to the state
 145 have been removed and any remaining resources can be cleared for the
 146 offload state.  How these are used by the driver will depend on specific
 147 hardware needs.
 148
 149 As a netdev is set to DOWN the XFRM stack's netdev listener will call
 150 xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded
 151 states.