[linux-2.6-block.git] / Documentation / networking / xfrm_device.rst

.. SPDX-License-Identifier: GPL-2.0

===============================================
XFRM device - offloading the IPsec computations
===============================================

Shannon Nelson <shannon.nelson@oracle.com>


Overview
========

IPsec is a useful feature for securing network traffic, but the
computational cost is high: a 10Gbps link can easily be brought down
to under 1Gbps, depending on the traffic and link configuration.
Luckily, there are NICs that offer a hardware based IPsec offload which
can radically increase throughput and decrease CPU utilization.  The XFRM
Device interface allows NIC drivers to offer to the stack access to the
hardware offload.

Userland access to the offload is typically through a system such as
libreswan or KAME/raccoon, but the iproute2 'ip xfrm' command set can
be handy when experimenting.  An example command might look something
like this::

  ip x s add proto esp dst 14.0.0.70 src 14.0.0.52 spi 0x07 mode transport \
     reqid 0x07 replay-window 32 \
     aead 'rfc4106(gcm(aes))' 0x44434241343332312423222114131211f4f3f2f1 128 \
     sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \
     offload dev eth4 dir in

Yes, that's ugly, but that's what shell scripts and/or libreswan are for.


Callbacks to implement
======================

::

  /* from include/linux/netdevice.h */
  struct xfrmdev_ops {
	int	(*xdo_dev_state_add) (struct xfrm_state *x);
	void	(*xdo_dev_state_delete) (struct xfrm_state *x);
	void	(*xdo_dev_state_free) (struct xfrm_state *x);
	bool	(*xdo_dev_offload_ok) (struct sk_buff *skb,
				       struct xfrm_state *x);
	void    (*xdo_dev_state_advance_esn) (struct xfrm_state *x);
  };

The NIC driver offering ipsec offload will need to implement these
callbacks to make the offload available to the network stack's
XFRM subsystem.  Additionally, the feature bits NETIF_F_HW_ESP and
NETIF_F_HW_ESP_TX_CSUM will signal the availability of the offload.


Flow
====

At probe time and before the call to register_netdev(), the driver should
set up local data structures and XFRM callbacks, and set the feature bits.
The XFRM code's listener will finish the setup on NETDEV_REGISTER.

::

		adapter->netdev->xfrmdev_ops = &ixgbe_xfrmdev_ops;
		adapter->netdev->features |= NETIF_F_HW_ESP;
		adapter->netdev->hw_enc_features |= NETIF_F_HW_ESP;

When new SAs are set up with a request for "offload" feature, the
driver's xdo_dev_state_add() will be given the new SA to be offloaded
and an indication of whether it is for Rx or Tx.  The driver should

	- verify the algorithm is supported for offloads
	- store the SA information (key, salt, target-ip, protocol, etc)
	- enable the HW offload of the SA
	- return status value:

		===========   ===================================
		0             success
		-EOPNETSUPP   offload not supported, try SW IPsec
		other         fail the request
		===========   ===================================

The driver can also set an offload_handle in the SA, an opaque void pointer
that can be used to convey context into the fast-path offload requests::

		xs->xso.offload_handle = context;


When the network stack is preparing an IPsec packet for an SA that has
been setup for offload, it first calls into xdo_dev_offload_ok() with
the skb and the intended offload state to ask the driver if the offload
will serviceable.  This can check the packet information to be sure the
offload can be supported (e.g. IPv4 or IPv6, no IPv4 options, etc) and
return true of false to signify its support.

When ready to send, the driver needs to inspect the Tx packet for the
offload information, including the opaque context, and set up the packet
send accordingly::

		xs = xfrm_input_state(skb);
		context = xs->xso.offload_handle;
		set up HW for send

The stack has already inserted the appropriate IPsec headers in the
packet data, the offload just needs to do the encryption and fix up the
header values.


When a packet is received and the HW has indicated that it offloaded a
decryption, the driver needs to add a reference to the decoded SA into
the packet's skb.  At this point the data should be decrypted but the
IPsec headers are still in the packet data; they are removed later up
the stack in xfrm_input().

	find and hold the SA that was used to the Rx skb::

		get spi, protocol, and destination IP from packet headers
		xs = find xs from (spi, protocol, dest_IP)
		xfrm_state_hold(xs);

	store the state information into the skb::

		sp = secpath_set(skb);
		if (!sp) return;
		sp->xvec[sp->len++] = xs;
		sp->olen++;

	indicate the success and/or error status of the offload::

		xo = xfrm_offload(skb);
		xo->flags = CRYPTO_DONE;
		xo->status = crypto_status;

	hand the packet to napi_gro_receive() as usual

In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn().
Driver will check packet seq number and update HW ESN state machine if needed.

When the SA is removed by the user, the driver's xdo_dev_state_delete()
is asked to disable the offload.  Later, xdo_dev_state_free() is called
from a garbage collection routine after all reference counts to the state
have been removed and any remaining resources can be cleared for the
offload state.  How these are used by the driver will depend on specific
hardware needs.

As a netdev is set to DOWN the XFRM stack's netdev listener will call
xdo_dev_state_delete() and xdo_dev_state_free() on any remaining offloaded
states.
Commit	Line	Data
c4a0eb93	1	.. SPDX-License-Identifier: GPL-2.0
5c0bb261 SN	2
	3	===============================================
	4	XFRM device - offloading the IPsec computations
	5	===============================================
c4a0eb93	6
5c0bb261 SN	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
c4a0eb93	24	like this::
5c0bb261 SN	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
c4a0eb93 MCC	39	::
	40
	41	/* from include/linux/netdevice.h */
	42	struct xfrmdev_ops {
5c0bb261 SN	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);
50bd870a	48	void (xdo_dev_state_advance_esn) (struct xfrm_state x);
c4a0eb93	49	};
5c0bb261 SN	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
87d77e59	53	XFRM subsystem. Additionally, the feature bits NETIF_F_HW_ESP and
5c0bb261 SN	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
c4a0eb93 MCC	65	::
c4a0eb93 MCC	66
5c0bb261 SN	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
c4a0eb93	74
5c0bb261 SN	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
4a132095	78	- return status value:
c4a0eb93 MCC	79
c4a0eb93 MCC	80	=========== ===================================
4a132095 SN	81	0 success
	82	-EOPNETSUPP offload not supported, try SW IPsec
	83	other fail the request
c4a0eb93	84	=========== ===================================
5c0bb261 SN	85
5c0bb261 SN	86	The driver can also set an offload_handle in the SA, an opaque void pointer
c4a0eb93	87	that can be used to convey context into the fast-path offload requests::
5c0bb261 SN	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
c4a0eb93	101	send accordingly::
5c0bb261 SN	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
c4a0eb93 MCC	118	find and hold the SA that was used to the Rx skb::
c4a0eb93 MCC	119
5c0bb261 SN	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
c4a0eb93 MCC	124	store the state information into the skb::
c4a0eb93 MCC	125
4165079b FW	126	sp = secpath_set(skb);
	127	if (!sp) return;
	128	sp->xvec[sp->len++] = xs;
	129	sp->olen++;
5c0bb261	130
c4a0eb93 MCC	131	indicate the success and/or error status of the offload::
c4a0eb93 MCC	132
5c0bb261 SN	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
50bd870a YE	139	In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn().
50bd870a YE	140	Driver will check packet seq number and update HW ESN state machine if needed.
5c0bb261 SN	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.