From 10a11861943902fda74f37f456b45183b2bca270 Mon Sep 17 00:00:00 2001 From: Jianbo Liu Date: Tue, 21 Oct 2025 04:35:42 +0300 Subject: xfrm: Refactor xfrm_input lock to reduce contention with RSS With newer NICs like mlx5 supporting RSS for IPsec crypto offload, packets for a single Security Association (SA) are scattered across multiple CPU cores for parallel processing. The xfrm_state spinlock (x->lock) is held for each packet during xfrm processing. When multiple connections or flows share the same SA, this parallelism causes high lock contention on x->lock, creating a performance bottleneck and limiting scalability. The original xfrm_input() function exacerbated this issue by releasing and immediately re-acquiring x->lock. For hardware crypto offload paths, this unlock/relock sequence is unnecessary and introduces significant overhead. This patch refactors the function to relocate the type_offload->input_tail call for the offload path, performing all necessary work while continuously holding the lock. This reordering is safe, since packets which don't pass the checks below will still fail them with the new code. Performance testing with iperf using multiple parallel streams over a single IPsec SA shows significant improvement in throughput as the number of queues (and thus CPU cores) increases: +-----------+---------------+--------------+-----------------+ | RX queues | Before (Gbps) | After (Gbps) | Improvement (%) | +-----------+---------------+--------------+-----------------+ | 2 | 32.3 | 34.4 | 6.5 | | 4 | 34.4 | 40.0 | 16.3 | | 6 | 24.5 | 38.3 | 56.3 | | 8 | 23.1 | 38.3 | 65.8 | | 12 | 18.1 | 29.9 | 65.2 | | 16 | 16.0 | 25.2 | 57.5 | +-----------+---------------+--------------+-----------------+ Signed-off-by: Jianbo Liu Reviewed-by: Cosmin Ratiu Signed-off-by: Steffen Klassert --- net/xfrm/xfrm_input.c | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/net/xfrm/xfrm_input.c b/net/xfrm/xfrm_input.c index c9ddef869aa5..257935cbd221 100644 --- a/net/xfrm/xfrm_input.c +++ b/net/xfrm/xfrm_input.c @@ -505,6 +505,7 @@ int xfrm_input(struct sk_buff *skb, int nexthdr, __be32 spi, int encap_type) async = 1; dev_put(skb->dev); seq = XFRM_SKB_CB(skb)->seq.input.low; + spin_lock(&x->lock); goto resume; } /* GRO call */ @@ -541,6 +542,8 @@ int xfrm_input(struct sk_buff *skb, int nexthdr, __be32 spi, int encap_type) XFRM_INC_STATS(net, LINUX_MIB_XFRMINHDRERROR); goto drop; } + + nexthdr = x->type_offload->input_tail(x, skb); } goto lock; @@ -638,11 +641,9 @@ lock: goto drop_unlock; } - spin_unlock(&x->lock); - if (xfrm_tunnel_check(skb, x, family)) { XFRM_INC_STATS(net, LINUX_MIB_XFRMINSTATEMODEERROR); - goto drop; + goto drop_unlock; } seq_hi = htonl(xfrm_replay_seqhi(x, seq)); @@ -650,9 +651,8 @@ lock: XFRM_SKB_CB(skb)->seq.input.low = seq; XFRM_SKB_CB(skb)->seq.input.hi = seq_hi; - if (crypto_done) { - nexthdr = x->type_offload->input_tail(x, skb); - } else { + if (!crypto_done) { + spin_unlock(&x->lock); dev_hold(skb->dev); nexthdr = x->type->input(x, skb); @@ -660,9 +660,9 @@ lock: return 0; dev_put(skb->dev); + spin_lock(&x->lock); } resume: - spin_lock(&x->lock); if (nexthdr < 0) { if (nexthdr == -EBADMSG) { xfrm_audit_state_icvfail(x, skb, -- cgit v1.2.3 From b427c0c3bc40cca268a5d54a1cdf6166cb1360e2 Mon Sep 17 00:00:00 2001 From: Jianbo Liu Date: Tue, 21 Oct 2025 04:35:43 +0300 Subject: xfrm: Skip redundant replay recheck for the hardware offload path The xfrm_replay_recheck() function was introduced to handle the issues arising from asynchronous crypto algorithms. The crypto offload path is now effectively synchronous, as it holds the state lock throughout its operation. This eliminates the race condition, making the recheck an unnecessary overhead. This patch improves performance by skipping the redundant call when crypto_done is true. Additionally, the sequence number assignment is moved to an earlier point in the function. This improves performance by reducing lock contention and places the logic at a more appropriate point, as the full sequence number (including the higher-order bits) can be determined as soon as the packet is received. Signed-off-by: Jianbo Liu Reviewed-by: Cosmin Ratiu Signed-off-by: Steffen Klassert --- net/xfrm/xfrm_input.c | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/net/xfrm/xfrm_input.c b/net/xfrm/xfrm_input.c index 257935cbd221..4ed346e682c7 100644 --- a/net/xfrm/xfrm_input.c +++ b/net/xfrm/xfrm_input.c @@ -546,7 +546,7 @@ int xfrm_input(struct sk_buff *skb, int nexthdr, __be32 spi, int encap_type) nexthdr = x->type_offload->input_tail(x, skb); } - goto lock; + goto process; } family = XFRM_SPI_SKB_CB(skb)->family; @@ -614,7 +614,12 @@ int xfrm_input(struct sk_buff *skb, int nexthdr, __be32 spi, int encap_type) goto drop; } -lock: +process: + seq_hi = htonl(xfrm_replay_seqhi(x, seq)); + + XFRM_SKB_CB(skb)->seq.input.low = seq; + XFRM_SKB_CB(skb)->seq.input.hi = seq_hi; + spin_lock(&x->lock); if (unlikely(x->km.state != XFRM_STATE_VALID)) { @@ -646,11 +651,6 @@ lock: goto drop_unlock; } - seq_hi = htonl(xfrm_replay_seqhi(x, seq)); - - XFRM_SKB_CB(skb)->seq.input.low = seq; - XFRM_SKB_CB(skb)->seq.input.hi = seq_hi; - if (!crypto_done) { spin_unlock(&x->lock); dev_hold(skb->dev); @@ -676,7 +676,7 @@ resume: /* only the first xfrm gets the encap type */ encap_type = 0; - if (xfrm_replay_recheck(x, skb, seq)) { + if (!crypto_done && xfrm_replay_recheck(x, skb, seq)) { XFRM_INC_STATS(net, LINUX_MIB_XFRMINSTATESEQERROR); goto drop_unlock; } -- cgit v1.2.3 From 6b3b6e59c4f8584806cbed63b1593fd56d54cb71 Mon Sep 17 00:00:00 2001 From: Steffen Klassert Date: Tue, 28 Oct 2025 07:29:09 +0100 Subject: pfkey: Deprecate pfkey The pfkey user configuration interface was replaced by the netlink user configuration interface more than a decade ago. In between all maintained IKE implementations moved to the netlink interface. So let config NET_KEY default to no in Kconfig. The pfkey code will be removed in a second step. Signed-off-by: Steffen Klassert Reviewed-by: Sabrina Dubroca Acked-by: Antony Antony Acked-by: Tobias Brunner Acked-by: Herbert Xu Acked-by: Tuomo Soini Acked-by: Paul Wouters --- net/key/af_key.c | 2 ++ net/xfrm/Kconfig | 11 +++++++---- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/net/key/af_key.c b/net/key/af_key.c index 2ebde0352245..571200433aa9 100644 --- a/net/key/af_key.c +++ b/net/key/af_key.c @@ -3903,6 +3903,8 @@ static int __init ipsec_pfkey_init(void) { int err = proto_register(&key_proto, 0); + pr_warn_once("PFKEY is deprecated and scheduled to be removed in 2027, " + "please contact the netdev mailing list\n"); if (err != 0) goto out; diff --git a/net/xfrm/Kconfig b/net/xfrm/Kconfig index f0157702718f..4a62817a88f8 100644 --- a/net/xfrm/Kconfig +++ b/net/xfrm/Kconfig @@ -110,14 +110,17 @@ config XFRM_IPCOMP select CRYPTO_DEFLATE config NET_KEY - tristate "PF_KEY sockets" + tristate "PF_KEY sockets (deprecated)" select XFRM_ALGO help PF_KEYv2 socket family, compatible to KAME ones. - They are required if you are going to use IPsec tools ported - from KAME. - Say Y unless you know what you are doing. + The PF_KEYv2 socket interface is deprecated and + scheduled for removal. All maintained IKE daemons + no longer need PF_KEY sockets. Please use the netlink + interface (XFRM_USER) to configure IPsec. + + If unsure, say N. config NET_KEY_MIGRATE bool "PF_KEY MIGRATE" -- cgit v1.2.3 From 68ec5df1d8946dd805d6ab67666a38331223f3a1 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:22 +0700 Subject: Documentation: xfrm_device: Wrap iproute2 snippets in literal code block iproute2 snippets (ip x) are shown in long-running definition lists instead. Format them as literal code blocks that do the semantic job better. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_device.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 122204da0fff..7a13075b5bf0 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -34,7 +34,7 @@ Right now, there are two types of hardware offload that kernel supports. 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 for crypto offload: +like this for crypto offload:: 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 \ @@ -42,7 +42,7 @@ like this for crypto offload: sel src 14.0.0.52/24 dst 14.0.0.70/24 proto tcp \ offload dev eth4 dir in -and for packet offload +and for packet offload:: 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 \ -- cgit v1.2.3 From 340e2a73866557ad1f902273d534e9a81efccbd2 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:23 +0700 Subject: Documentation: xfrm_device: Use numbered list for offloading steps Format xfrm offloading steps as numbered list. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_device.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 7a13075b5bf0..86db3f42552d 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -153,26 +153,26 @@ 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:: +1. Find and hold the SA that was used to the Rx skb:: - get spi, protocol, and destination IP from packet headers + /* 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:: +2. 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:: +3. 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 +4. Hand the packet to napi_gro_receive() as usual. In ESN mode, xdo_dev_state_advance_esn() is called from xfrm_replay_advance_esn() for RX, and xfrm_replay_overflow_offload_esn for TX. -- cgit v1.2.3 From 840188d276a34e8883fd4b64a4a39f7b3eec0f28 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:24 +0700 Subject: Documentation: xfrm_device: Separate hardware offload sublists Sublists of hardware offload type lists are rendered in combined paragraph due to lack of separator from their parent list. Add it. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_device.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst index 86db3f42552d..b0d85a5f57d1 100644 --- a/Documentation/networking/xfrm_device.rst +++ b/Documentation/networking/xfrm_device.rst @@ -20,11 +20,15 @@ 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. -Right now, there are two types of hardware offload that kernel supports. +Right now, there are two types of hardware offload that kernel supports: + * IPsec crypto offload: + * NIC performs encrypt/decrypt * Kernel does everything else + * IPsec packet offload: + * NIC performs encrypt/decrypt * NIC does encapsulation * Kernel and NIC have SA and policy in-sync -- cgit v1.2.3 From a397b259c17379f74158b86dd7fc4e3a7d53fc57 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:25 +0700 Subject: Documentation: xfrm_sync: Properly reindent list text List texts are currently aligned at the start of column, rather than after the list marker. Reindent them. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_sync.rst | 77 ++++++++++++++++++---------------- 1 file changed, 40 insertions(+), 37 deletions(-) diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm_sync.rst index 6246503ceab2..c811c3edfa57 100644 --- a/Documentation/networking/xfrm_sync.rst +++ b/Documentation/networking/xfrm_sync.rst @@ -88,23 +88,23 @@ to get notified of these events. a) byte value (XFRMA_LTIME_VAL) -This TLV carries the running/current counter for byte lifetime since -last event. + This TLV carries the running/current counter for byte lifetime since + last event. -b)replay value (XFRMA_REPLAY_VAL) +b) replay value (XFRMA_REPLAY_VAL) -This TLV carries the running/current counter for replay sequence since -last event. + This TLV carries the running/current counter for replay sequence since + last event. -c)replay threshold (XFRMA_REPLAY_THRESH) +c) replay threshold (XFRMA_REPLAY_THRESH) -This TLV carries the threshold being used by the kernel to trigger events -when the replay sequence is exceeded. + This TLV carries the threshold being used by the kernel to trigger events + when the replay sequence is exceeded. d) expiry timer (XFRMA_ETIMER_THRESH) -This is a timer value in milliseconds which is used as the nagle -value to rate limit the events. + This is a timer value in milliseconds which is used as the nagle + value to rate limit the events. 3) Default configurations for the parameters: --------------------------------------------- @@ -121,12 +121,14 @@ in case they are not specified. the two sysctls/proc entries are: a) /proc/sys/net/core/sysctl_xfrm_aevent_etime -used to provide default values for the XFRMA_ETIMER_THRESH in incremental -units of time of 100ms. The default is 10 (1 second) + + Used to provide default values for the XFRMA_ETIMER_THRESH in incremental + units of time of 100ms. The default is 10 (1 second) b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth -used to provide default values for XFRMA_REPLAY_THRESH parameter -in incremental packet count. The default is two packets. + + Used to provide default values for XFRMA_REPLAY_THRESH parameter + in incremental packet count. The default is two packets. 4) Message types ---------------- @@ -134,42 +136,43 @@ in incremental packet count. The default is two packets. a) XFRM_MSG_GETAE issued by user-->kernel. XFRM_MSG_GETAE does not carry any TLVs. -The response is a XFRM_MSG_NEWAE which is formatted based on what -XFRM_MSG_GETAE queried for. + The response is a XFRM_MSG_NEWAE which is formatted based on what + XFRM_MSG_GETAE queried for. + + The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -* if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved -* if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved + * if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved + * if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved b) XFRM_MSG_NEWAE is issued by either user space to configure or kernel to announce events or respond to a XFRM_MSG_GETAE. -i) user --> kernel to configure a specific SA. + i) user --> kernel to configure a specific SA. -any of the values or threshold parameters can be updated by passing the -appropriate TLV. + any of the values or threshold parameters can be updated by passing the + appropriate TLV. -A response is issued back to the sender in user space to indicate success -or failure. + A response is issued back to the sender in user space to indicate success + or failure. -In the case of success, additionally an event with -XFRM_MSG_NEWAE is also issued to any listeners as described in iii). + In the case of success, additionally an event with + XFRM_MSG_NEWAE is also issued to any listeners as described in iii). -ii) kernel->user direction as a response to XFRM_MSG_GETAE + ii) kernel->user direction as a response to XFRM_MSG_GETAE -The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -The threshold TLVs will be included if explicitly requested in -the XFRM_MSG_GETAE message. + The threshold TLVs will be included if explicitly requested in + the XFRM_MSG_GETAE message. -iii) kernel->user to report as event if someone sets any values or - thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). - In such a case XFRM_AE_CU flag is set to inform the user that - the change happened as a result of an update. - The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + iii) kernel->user to report as event if someone sets any values or + thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). + In such a case XFRM_AE_CU flag is set to inform the user that + the change happened as a result of an update. + The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -iv) kernel->user to report event when replay threshold or a timeout - is exceeded. + iv) kernel->user to report event when replay threshold or a timeout + is exceeded. In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout happened) is set to inform the user what happened. -- cgit v1.2.3 From 01ad7831fbb28b3903fa3eb4e029f5a5d6690924 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:26 +0700 Subject: Documentation: xfrm_sync: Trim excess section heading characters The first section "Message Structure" has excess underline, while the second and third one ("TLVS reflect the different parameters" and "Default configurations for the parameters") have trailing colon. Trim them. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Suggested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_sync.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm_sync.rst index c811c3edfa57..de4da4707037 100644 --- a/Documentation/networking/xfrm_sync.rst +++ b/Documentation/networking/xfrm_sync.rst @@ -36,7 +36,7 @@ is not driven by packet arrival. - the replay sequence for both inbound and outbound 1) Message Structure ----------------------- +-------------------- nlmsghdr:aevent_id:optional-TLVs. @@ -83,8 +83,8 @@ when going from kernel to user space) A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS to get notified of these events. -2) TLVS reflect the different parameters: ------------------------------------------ +2) TLVS reflect the different parameters +---------------------------------------- a) byte value (XFRMA_LTIME_VAL) @@ -106,8 +106,8 @@ d) expiry timer (XFRMA_ETIMER_THRESH) This is a timer value in milliseconds which is used as the nagle value to rate limit the events. -3) Default configurations for the parameters: ---------------------------------------------- +3) Default configurations for the parameters +-------------------------------------------- By default these events should be turned off unless there is at least one listener registered to listen to the multicast -- cgit v1.2.3 From c08b786b8295fbbd1e8ac99320126fd5dd8b965c Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:27 +0700 Subject: Documentation: xfrm_sysctl: Trim trailing colon in section heading The sole section heading ("/proc/sys/net/core/xfrm_* Variables") has trailing colon. Trim it. Suggested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_sysctl.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/networking/xfrm_sysctl.rst b/Documentation/networking/xfrm_sysctl.rst index 47b9bbdd0179..7d0c4b17c0bd 100644 --- a/Documentation/networking/xfrm_sysctl.rst +++ b/Documentation/networking/xfrm_sysctl.rst @@ -4,8 +4,8 @@ XFRM Syscall ============ -/proc/sys/net/core/xfrm_* Variables: -==================================== +/proc/sys/net/core/xfrm_* Variables +=================================== xfrm_acq_expires - INTEGER default 30 - hard timeout in seconds for acquire requests -- cgit v1.2.3 From 7276e7ae569b1ce2ac2e3341107703216a290398 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:28 +0700 Subject: Documentation: xfrm_sync: Number the fifth section Number the fifth section ("Exception to threshold settings") to be consistent with the rest of sections. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Suggested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/xfrm_sync.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm_sync.rst index de4da4707037..112f7c102ad0 100644 --- a/Documentation/networking/xfrm_sync.rst +++ b/Documentation/networking/xfrm_sync.rst @@ -179,8 +179,8 @@ happened) is set to inform the user what happened. Note the two flags are mutually exclusive. The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. -Exceptions to threshold settings --------------------------------- +5) Exceptions to threshold settings +----------------------------------- If you have an SA that is getting hit by traffic in bursts such that there is a period where the timer threshold expires with no packets -- cgit v1.2.3 From 03e23b18c720bdb628ccfbbb3faf4486c0413354 Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:29 +0700 Subject: net: Move XFRM documentation into its own subdirectory XFRM docs are currently reside in Documentation/networking directory, yet these are distinctive as a group of their own. Move them into xfrm subdirectory. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- Documentation/networking/index.rst | 5 +- Documentation/networking/xfrm/index.rst | 13 ++ Documentation/networking/xfrm/xfrm_device.rst | 206 ++++++++++++++++++++++++++ Documentation/networking/xfrm/xfrm_proc.rst | 119 +++++++++++++++ Documentation/networking/xfrm/xfrm_sync.rst | 192 ++++++++++++++++++++++++ Documentation/networking/xfrm/xfrm_sysctl.rst | 11 ++ Documentation/networking/xfrm_device.rst | 206 -------------------------- Documentation/networking/xfrm_proc.rst | 119 --------------- Documentation/networking/xfrm_sync.rst | 192 ------------------------ Documentation/networking/xfrm_sysctl.rst | 11 -- 10 files changed, 542 insertions(+), 532 deletions(-) create mode 100644 Documentation/networking/xfrm/index.rst create mode 100644 Documentation/networking/xfrm/xfrm_device.rst create mode 100644 Documentation/networking/xfrm/xfrm_proc.rst create mode 100644 Documentation/networking/xfrm/xfrm_sync.rst create mode 100644 Documentation/networking/xfrm/xfrm_sysctl.rst delete mode 100644 Documentation/networking/xfrm_device.rst delete mode 100644 Documentation/networking/xfrm_proc.rst delete mode 100644 Documentation/networking/xfrm_sync.rst delete mode 100644 Documentation/networking/xfrm_sysctl.rst diff --git a/Documentation/networking/index.rst b/Documentation/networking/index.rst index c775cababc8c..75db2251649b 100644 --- a/Documentation/networking/index.rst +++ b/Documentation/networking/index.rst @@ -131,10 +131,7 @@ Contents: vxlan x25 x25-iface - xfrm_device - xfrm_proc - xfrm_sync - xfrm_sysctl + xfrm/index xdp-rx-metadata xsk-tx-metadata diff --git a/Documentation/networking/xfrm/index.rst b/Documentation/networking/xfrm/index.rst new file mode 100644 index 000000000000..7d866da836fe --- /dev/null +++ b/Documentation/networking/xfrm/index.rst @@ -0,0 +1,13 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============== +XFRM Framework +============== + +.. toctree:: + :maxdepth: 2 + + xfrm_device + xfrm_proc + xfrm_sync + xfrm_sysctl diff --git a/Documentation/networking/xfrm/xfrm_device.rst b/Documentation/networking/xfrm/xfrm_device.rst new file mode 100644 index 000000000000..b0d85a5f57d1 --- /dev/null +++ b/Documentation/networking/xfrm/xfrm_device.rst @@ -0,0 +1,206 @@ +.. SPDX-License-Identifier: GPL-2.0 +.. _xfrm_device: + +=============================================== +XFRM device - offloading the IPsec computations +=============================================== + +Shannon Nelson +Leon Romanovsky + + +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. + +Right now, there are two types of hardware offload that kernel supports: + + * IPsec crypto offload: + + * NIC performs encrypt/decrypt + * Kernel does everything else + + * IPsec packet offload: + + * NIC performs encrypt/decrypt + * NIC does encapsulation + * Kernel and NIC have SA and policy in-sync + * NIC handles the SA and policies states + * The Kernel talks to the keymanager + +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 for crypto offload:: + + 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 + +and for packet offload:: + + 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 packet dev eth4 dir in + + ip x p add src 14.0.0.70 dst 14.0.0.52 offload packet dev eth4 dir in + tmpl src 14.0.0.70 dst 14.0.0.52 proto esp reqid 10000 mode transport + +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 { + /* Crypto and Packet offload callbacks */ + int (*xdo_dev_state_add)(struct net_device *dev, + struct xfrm_state *x, + struct netlink_ext_ack *extack); + void (*xdo_dev_state_delete)(struct net_device *dev, + struct xfrm_state *x); + void (*xdo_dev_state_free)(struct net_device *dev, + 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); + void (*xdo_dev_state_update_stats) (struct xfrm_state *x); + + /* Solely packet offload callbacks */ + int (*xdo_dev_policy_add) (struct xfrm_policy *x, struct netlink_ext_ack *extack); + void (*xdo_dev_policy_delete) (struct xfrm_policy *x); + void (*xdo_dev_policy_free) (struct xfrm_policy *x); + }; + +The NIC driver offering ipsec offload will need to implement callbacks +relevant to supported offload 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, + not applicable for packet offload mode + 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 or false to signify its support. In case driver doesn't implement +this callback, the stack provides reasonable defaults. + +Crypto offload mode: +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(). + +1. 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); + +2. Store the state information into the skb:: + + sp = secpath_set(skb); + if (!sp) return; + sp->xvec[sp->len++] = xs; + sp->olen++; + +3. Indicate the success and/or error status of the offload:: + + xo = xfrm_offload(skb); + xo->flags = CRYPTO_DONE; + xo->status = crypto_status; + +4. Hand the packet to napi_gro_receive() as usual. + +In ESN mode, xdo_dev_state_advance_esn() is called from +xfrm_replay_advance_esn() for RX, and xfrm_replay_overflow_offload_esn for TX. +Driver will check packet seq number and update HW ESN state machine if needed. + +Packet offload mode: +HW adds and deletes XFRM headers. So in RX path, XFRM stack is bypassed if HW +reported success. In TX path, the packet lefts kernel without extra header +and not encrypted, the HW is responsible to perform it. + +When the SA is removed by the user, the driver's xdo_dev_state_delete() +and xdo_dev_policy_delete() are asked to disable the offload. Later, +xdo_dev_state_free() and xdo_dev_policy_free() are called from a garbage +collection routine after all reference counts to the state and policy +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(), xdo_dev_policy_delete(), xdo_dev_state_free() and +xdo_dev_policy_free() on any remaining offloaded states. + +Outcome of HW handling packets, the XFRM core can't count hard, soft limits. +The HW/driver are responsible to perform it and provide accurate data when +xdo_dev_state_update_stats() is called. In case of one of these limits +occuried, the driver needs to call to xfrm_state_check_expire() to make sure +that XFRM performs rekeying sequence. diff --git a/Documentation/networking/xfrm/xfrm_proc.rst b/Documentation/networking/xfrm/xfrm_proc.rst new file mode 100644 index 000000000000..973d1571acac --- /dev/null +++ b/Documentation/networking/xfrm/xfrm_proc.rst @@ -0,0 +1,119 @@ +.. SPDX-License-Identifier: GPL-2.0 + +================================== +XFRM proc - /proc/net/xfrm_* files +================================== + +Masahide NAKAMURA + + +Transformation Statistics +------------------------- + +The xfrm_proc code is a set of statistics showing numbers of packets +dropped by the transformation code and why. These counters are defined +as part of the linux private MIB. These counters can be viewed in +/proc/net/xfrm_stat. + + +Inbound errors +~~~~~~~~~~~~~~ + +XfrmInError: + All errors which is not matched others + +XfrmInBufferError: + No buffer is left + +XfrmInHdrError: + Header error + +XfrmInNoStates: + No state is found + i.e. Either inbound SPI, address, or IPsec protocol at SA is wrong + +XfrmInStateProtoError: + Transformation protocol specific error + e.g. SA key is wrong + +XfrmInStateModeError: + Transformation mode specific error + +XfrmInStateSeqError: + Sequence error + i.e. Sequence number is out of window + +XfrmInStateExpired: + State is expired + +XfrmInStateMismatch: + State has mismatch option + e.g. UDP encapsulation type is mismatch + +XfrmInStateInvalid: + State is invalid + +XfrmInTmplMismatch: + No matching template for states + e.g. Inbound SAs are correct but SP rule is wrong + +XfrmInNoPols: + No policy is found for states + e.g. Inbound SAs are correct but no SP is found + +XfrmInPolBlock: + Policy discards + +XfrmInPolError: + Policy error + +XfrmAcquireError: + State hasn't been fully acquired before use + +XfrmFwdHdrError: + Forward routing of a packet is not allowed + +XfrmInStateDirError: + State direction mismatch (lookup found an output state on the input path, expected input or no direction) + +Outbound errors +~~~~~~~~~~~~~~~ +XfrmOutError: + All errors which is not matched others + +XfrmOutBundleGenError: + Bundle generation error + +XfrmOutBundleCheckError: + Bundle check error + +XfrmOutNoStates: + No state is found + +XfrmOutStateProtoError: + Transformation protocol specific error + +XfrmOutStateModeError: + Transformation mode specific error + +XfrmOutStateSeqError: + Sequence error + i.e. Sequence number overflow + +XfrmOutStateExpired: + State is expired + +XfrmOutPolBlock: + Policy discards + +XfrmOutPolDead: + Policy is dead + +XfrmOutPolError: + Policy error + +XfrmOutStateInvalid: + State is invalid, perhaps expired + +XfrmOutStateDirError: + State direction mismatch (lookup found an input state on the output path, expected output or no direction) diff --git a/Documentation/networking/xfrm/xfrm_sync.rst b/Documentation/networking/xfrm/xfrm_sync.rst new file mode 100644 index 000000000000..dfc2ec0df380 --- /dev/null +++ b/Documentation/networking/xfrm/xfrm_sync.rst @@ -0,0 +1,192 @@ +.. SPDX-License-Identifier: GPL-2.0 + +========= +XFRM sync +========= + +The sync patches work is based on initial patches from +Krisztian and others and additional patches +from Jamal . + +The end goal for syncing is to be able to insert attributes + generate +events so that the SA can be safely moved from one machine to another +for HA purposes. +The idea is to synchronize the SA so that the takeover machine can do +the processing of the SA as accurate as possible if it has access to it. + +We already have the ability to generate SA add/del/upd events. +These patches add ability to sync and have accurate lifetime byte (to +ensure proper decay of SAs) and replay counters to avoid replay attacks +with as minimal loss at failover time. +This way a backup stays as closely up-to-date as an active member. + +Because the above items change for every packet the SA receives, +it is possible for a lot of the events to be generated. +For this reason, we also add a nagle-like algorithm to restrict +the events. i.e we are going to set thresholds to say "let me +know if the replay sequence threshold is reached or 10 secs have passed" +These thresholds are set system-wide via sysctls or can be updated +per SA. + +The identified items that need to be synchronized are: +- the lifetime byte counter +note that: lifetime time limit is not important if you assume the failover +machine is known ahead of time since the decay of the time countdown +is not driven by packet arrival. +- the replay sequence for both inbound and outbound + +1) Message Structure +-------------------- + +nlmsghdr:aevent_id:optional-TLVs. + +The netlink message types are: + +XFRM_MSG_NEWAE and XFRM_MSG_GETAE. + +A XFRM_MSG_GETAE does not have TLVs. + +A XFRM_MSG_NEWAE will have at least two TLVs (as is +discussed further below). + +aevent_id structure looks like:: + + struct xfrm_aevent_id { + struct xfrm_usersa_id sa_id; + xfrm_address_t saddr; + __u32 flags; + __u32 reqid; + }; + +The unique SA is identified by the combination of xfrm_usersa_id, +reqid and saddr. + +flags are used to indicate different things. The possible +flags are:: + + XFRM_AE_RTHR=1, /* replay threshold*/ + XFRM_AE_RVAL=2, /* replay value */ + XFRM_AE_LVAL=4, /* lifetime value */ + XFRM_AE_ETHR=8, /* expiry timer threshold */ + XFRM_AE_CR=16, /* Event cause is replay update */ + XFRM_AE_CE=32, /* Event cause is timer expiry */ + XFRM_AE_CU=64, /* Event cause is policy update */ + +How these flags are used is dependent on the direction of the +message (kernel<->user) as well the cause (config, query or event). +This is described below in the different messages. + +The pid will be set appropriately in netlink to recognize direction +(0 to the kernel and pid = processid that created the event +when going from kernel to user space) + +A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS +to get notified of these events. + +2) TLVS reflect the different parameters +---------------------------------------- + +a) byte value (XFRMA_LTIME_VAL) + + This TLV carries the running/current counter for byte lifetime since + last event. + +b) replay value (XFRMA_REPLAY_VAL) + + This TLV carries the running/current counter for replay sequence since + last event. + +c) replay threshold (XFRMA_REPLAY_THRESH) + + This TLV carries the threshold being used by the kernel to trigger events + when the replay sequence is exceeded. + +d) expiry timer (XFRMA_ETIMER_THRESH) + + This is a timer value in milliseconds which is used as the nagle + value to rate limit the events. + +3) Default configurations for the parameters +-------------------------------------------- + +By default these events should be turned off unless there is +at least one listener registered to listen to the multicast +group XFRMNLGRP_AEVENTS. + +Programs installing SAs will need to specify the two thresholds, however, +in order to not change existing applications such as racoon +we also provide default threshold values for these different parameters +in case they are not specified. + +the two sysctls/proc entries are: + +a) /proc/sys/net/core/sysctl_xfrm_aevent_etime + + Used to provide default values for the XFRMA_ETIMER_THRESH in incremental + units of time of 100ms. The default is 10 (1 second) + +b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth + + Used to provide default values for XFRMA_REPLAY_THRESH parameter + in incremental packet count. The default is two packets. + +4) Message types +---------------- + +a) XFRM_MSG_GETAE issued by user-->kernel. + XFRM_MSG_GETAE does not carry any TLVs. + + The response is a XFRM_MSG_NEWAE which is formatted based on what + XFRM_MSG_GETAE queried for. + + The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + + * if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved + * if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved + +b) XFRM_MSG_NEWAE is issued by either user space to configure + or kernel to announce events or respond to a XFRM_MSG_GETAE. + + i) user --> kernel to configure a specific SA. + + any of the values or threshold parameters can be updated by passing the + appropriate TLV. + + A response is issued back to the sender in user space to indicate success + or failure. + + In the case of success, additionally an event with + XFRM_MSG_NEWAE is also issued to any listeners as described in iii). + + ii) kernel->user direction as a response to XFRM_MSG_GETAE + + The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + + The threshold TLVs will be included if explicitly requested in + the XFRM_MSG_GETAE message. + + iii) kernel->user to report as event if someone sets any values or + thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). + In such a case XFRM_AE_CU flag is set to inform the user that + the change happened as a result of an update. + The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + + iv) kernel->user to report event when replay threshold or a timeout + is exceeded. + +In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout +happened) is set to inform the user what happened. +Note the two flags are mutually exclusive. +The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. + +5) Exceptions to threshold settings +----------------------------------- + +If you have an SA that is getting hit by traffic in bursts such that +there is a period where the timer threshold expires with no packets +seen, then an odd behavior is seen as follows: +The first packet arrival after a timer expiry will trigger a timeout +event; i.e we don't wait for a timeout period or a packet threshold +to be reached. This is done for simplicity and efficiency reasons. + +-JHS diff --git a/Documentation/networking/xfrm/xfrm_sysctl.rst b/Documentation/networking/xfrm/xfrm_sysctl.rst new file mode 100644 index 000000000000..7d0c4b17c0bd --- /dev/null +++ b/Documentation/networking/xfrm/xfrm_sysctl.rst @@ -0,0 +1,11 @@ +.. SPDX-License-Identifier: GPL-2.0 + +============ +XFRM Syscall +============ + +/proc/sys/net/core/xfrm_* Variables +=================================== + +xfrm_acq_expires - INTEGER + default 30 - hard timeout in seconds for acquire requests diff --git a/Documentation/networking/xfrm_device.rst b/Documentation/networking/xfrm_device.rst deleted file mode 100644 index b0d85a5f57d1..000000000000 --- a/Documentation/networking/xfrm_device.rst +++ /dev/null @@ -1,206 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 -.. _xfrm_device: - -=============================================== -XFRM device - offloading the IPsec computations -=============================================== - -Shannon Nelson -Leon Romanovsky - - -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. - -Right now, there are two types of hardware offload that kernel supports: - - * IPsec crypto offload: - - * NIC performs encrypt/decrypt - * Kernel does everything else - - * IPsec packet offload: - - * NIC performs encrypt/decrypt - * NIC does encapsulation - * Kernel and NIC have SA and policy in-sync - * NIC handles the SA and policies states - * The Kernel talks to the keymanager - -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 for crypto offload:: - - 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 - -and for packet offload:: - - 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 packet dev eth4 dir in - - ip x p add src 14.0.0.70 dst 14.0.0.52 offload packet dev eth4 dir in - tmpl src 14.0.0.70 dst 14.0.0.52 proto esp reqid 10000 mode transport - -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 { - /* Crypto and Packet offload callbacks */ - int (*xdo_dev_state_add)(struct net_device *dev, - struct xfrm_state *x, - struct netlink_ext_ack *extack); - void (*xdo_dev_state_delete)(struct net_device *dev, - struct xfrm_state *x); - void (*xdo_dev_state_free)(struct net_device *dev, - 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); - void (*xdo_dev_state_update_stats) (struct xfrm_state *x); - - /* Solely packet offload callbacks */ - int (*xdo_dev_policy_add) (struct xfrm_policy *x, struct netlink_ext_ack *extack); - void (*xdo_dev_policy_delete) (struct xfrm_policy *x); - void (*xdo_dev_policy_free) (struct xfrm_policy *x); - }; - -The NIC driver offering ipsec offload will need to implement callbacks -relevant to supported offload 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, - not applicable for packet offload mode - 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 or false to signify its support. In case driver doesn't implement -this callback, the stack provides reasonable defaults. - -Crypto offload mode: -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(). - -1. 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); - -2. Store the state information into the skb:: - - sp = secpath_set(skb); - if (!sp) return; - sp->xvec[sp->len++] = xs; - sp->olen++; - -3. Indicate the success and/or error status of the offload:: - - xo = xfrm_offload(skb); - xo->flags = CRYPTO_DONE; - xo->status = crypto_status; - -4. Hand the packet to napi_gro_receive() as usual. - -In ESN mode, xdo_dev_state_advance_esn() is called from -xfrm_replay_advance_esn() for RX, and xfrm_replay_overflow_offload_esn for TX. -Driver will check packet seq number and update HW ESN state machine if needed. - -Packet offload mode: -HW adds and deletes XFRM headers. So in RX path, XFRM stack is bypassed if HW -reported success. In TX path, the packet lefts kernel without extra header -and not encrypted, the HW is responsible to perform it. - -When the SA is removed by the user, the driver's xdo_dev_state_delete() -and xdo_dev_policy_delete() are asked to disable the offload. Later, -xdo_dev_state_free() and xdo_dev_policy_free() are called from a garbage -collection routine after all reference counts to the state and policy -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(), xdo_dev_policy_delete(), xdo_dev_state_free() and -xdo_dev_policy_free() on any remaining offloaded states. - -Outcome of HW handling packets, the XFRM core can't count hard, soft limits. -The HW/driver are responsible to perform it and provide accurate data when -xdo_dev_state_update_stats() is called. In case of one of these limits -occuried, the driver needs to call to xfrm_state_check_expire() to make sure -that XFRM performs rekeying sequence. diff --git a/Documentation/networking/xfrm_proc.rst b/Documentation/networking/xfrm_proc.rst deleted file mode 100644 index 973d1571acac..000000000000 --- a/Documentation/networking/xfrm_proc.rst +++ /dev/null @@ -1,119 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -================================== -XFRM proc - /proc/net/xfrm_* files -================================== - -Masahide NAKAMURA - - -Transformation Statistics -------------------------- - -The xfrm_proc code is a set of statistics showing numbers of packets -dropped by the transformation code and why. These counters are defined -as part of the linux private MIB. These counters can be viewed in -/proc/net/xfrm_stat. - - -Inbound errors -~~~~~~~~~~~~~~ - -XfrmInError: - All errors which is not matched others - -XfrmInBufferError: - No buffer is left - -XfrmInHdrError: - Header error - -XfrmInNoStates: - No state is found - i.e. Either inbound SPI, address, or IPsec protocol at SA is wrong - -XfrmInStateProtoError: - Transformation protocol specific error - e.g. SA key is wrong - -XfrmInStateModeError: - Transformation mode specific error - -XfrmInStateSeqError: - Sequence error - i.e. Sequence number is out of window - -XfrmInStateExpired: - State is expired - -XfrmInStateMismatch: - State has mismatch option - e.g. UDP encapsulation type is mismatch - -XfrmInStateInvalid: - State is invalid - -XfrmInTmplMismatch: - No matching template for states - e.g. Inbound SAs are correct but SP rule is wrong - -XfrmInNoPols: - No policy is found for states - e.g. Inbound SAs are correct but no SP is found - -XfrmInPolBlock: - Policy discards - -XfrmInPolError: - Policy error - -XfrmAcquireError: - State hasn't been fully acquired before use - -XfrmFwdHdrError: - Forward routing of a packet is not allowed - -XfrmInStateDirError: - State direction mismatch (lookup found an output state on the input path, expected input or no direction) - -Outbound errors -~~~~~~~~~~~~~~~ -XfrmOutError: - All errors which is not matched others - -XfrmOutBundleGenError: - Bundle generation error - -XfrmOutBundleCheckError: - Bundle check error - -XfrmOutNoStates: - No state is found - -XfrmOutStateProtoError: - Transformation protocol specific error - -XfrmOutStateModeError: - Transformation mode specific error - -XfrmOutStateSeqError: - Sequence error - i.e. Sequence number overflow - -XfrmOutStateExpired: - State is expired - -XfrmOutPolBlock: - Policy discards - -XfrmOutPolDead: - Policy is dead - -XfrmOutPolError: - Policy error - -XfrmOutStateInvalid: - State is invalid, perhaps expired - -XfrmOutStateDirError: - State direction mismatch (lookup found an input state on the output path, expected output or no direction) diff --git a/Documentation/networking/xfrm_sync.rst b/Documentation/networking/xfrm_sync.rst deleted file mode 100644 index 112f7c102ad0..000000000000 --- a/Documentation/networking/xfrm_sync.rst +++ /dev/null @@ -1,192 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -==== -XFRM -==== - -The sync patches work is based on initial patches from -Krisztian and others and additional patches -from Jamal . - -The end goal for syncing is to be able to insert attributes + generate -events so that the SA can be safely moved from one machine to another -for HA purposes. -The idea is to synchronize the SA so that the takeover machine can do -the processing of the SA as accurate as possible if it has access to it. - -We already have the ability to generate SA add/del/upd events. -These patches add ability to sync and have accurate lifetime byte (to -ensure proper decay of SAs) and replay counters to avoid replay attacks -with as minimal loss at failover time. -This way a backup stays as closely up-to-date as an active member. - -Because the above items change for every packet the SA receives, -it is possible for a lot of the events to be generated. -For this reason, we also add a nagle-like algorithm to restrict -the events. i.e we are going to set thresholds to say "let me -know if the replay sequence threshold is reached or 10 secs have passed" -These thresholds are set system-wide via sysctls or can be updated -per SA. - -The identified items that need to be synchronized are: -- the lifetime byte counter -note that: lifetime time limit is not important if you assume the failover -machine is known ahead of time since the decay of the time countdown -is not driven by packet arrival. -- the replay sequence for both inbound and outbound - -1) Message Structure --------------------- - -nlmsghdr:aevent_id:optional-TLVs. - -The netlink message types are: - -XFRM_MSG_NEWAE and XFRM_MSG_GETAE. - -A XFRM_MSG_GETAE does not have TLVs. - -A XFRM_MSG_NEWAE will have at least two TLVs (as is -discussed further below). - -aevent_id structure looks like:: - - struct xfrm_aevent_id { - struct xfrm_usersa_id sa_id; - xfrm_address_t saddr; - __u32 flags; - __u32 reqid; - }; - -The unique SA is identified by the combination of xfrm_usersa_id, -reqid and saddr. - -flags are used to indicate different things. The possible -flags are:: - - XFRM_AE_RTHR=1, /* replay threshold*/ - XFRM_AE_RVAL=2, /* replay value */ - XFRM_AE_LVAL=4, /* lifetime value */ - XFRM_AE_ETHR=8, /* expiry timer threshold */ - XFRM_AE_CR=16, /* Event cause is replay update */ - XFRM_AE_CE=32, /* Event cause is timer expiry */ - XFRM_AE_CU=64, /* Event cause is policy update */ - -How these flags are used is dependent on the direction of the -message (kernel<->user) as well the cause (config, query or event). -This is described below in the different messages. - -The pid will be set appropriately in netlink to recognize direction -(0 to the kernel and pid = processid that created the event -when going from kernel to user space) - -A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS -to get notified of these events. - -2) TLVS reflect the different parameters ----------------------------------------- - -a) byte value (XFRMA_LTIME_VAL) - - This TLV carries the running/current counter for byte lifetime since - last event. - -b) replay value (XFRMA_REPLAY_VAL) - - This TLV carries the running/current counter for replay sequence since - last event. - -c) replay threshold (XFRMA_REPLAY_THRESH) - - This TLV carries the threshold being used by the kernel to trigger events - when the replay sequence is exceeded. - -d) expiry timer (XFRMA_ETIMER_THRESH) - - This is a timer value in milliseconds which is used as the nagle - value to rate limit the events. - -3) Default configurations for the parameters --------------------------------------------- - -By default these events should be turned off unless there is -at least one listener registered to listen to the multicast -group XFRMNLGRP_AEVENTS. - -Programs installing SAs will need to specify the two thresholds, however, -in order to not change existing applications such as racoon -we also provide default threshold values for these different parameters -in case they are not specified. - -the two sysctls/proc entries are: - -a) /proc/sys/net/core/sysctl_xfrm_aevent_etime - - Used to provide default values for the XFRMA_ETIMER_THRESH in incremental - units of time of 100ms. The default is 10 (1 second) - -b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth - - Used to provide default values for XFRMA_REPLAY_THRESH parameter - in incremental packet count. The default is two packets. - -4) Message types ----------------- - -a) XFRM_MSG_GETAE issued by user-->kernel. - XFRM_MSG_GETAE does not carry any TLVs. - - The response is a XFRM_MSG_NEWAE which is formatted based on what - XFRM_MSG_GETAE queried for. - - The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. - - * if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved - * if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved - -b) XFRM_MSG_NEWAE is issued by either user space to configure - or kernel to announce events or respond to a XFRM_MSG_GETAE. - - i) user --> kernel to configure a specific SA. - - any of the values or threshold parameters can be updated by passing the - appropriate TLV. - - A response is issued back to the sender in user space to indicate success - or failure. - - In the case of success, additionally an event with - XFRM_MSG_NEWAE is also issued to any listeners as described in iii). - - ii) kernel->user direction as a response to XFRM_MSG_GETAE - - The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. - - The threshold TLVs will be included if explicitly requested in - the XFRM_MSG_GETAE message. - - iii) kernel->user to report as event if someone sets any values or - thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). - In such a case XFRM_AE_CU flag is set to inform the user that - the change happened as a result of an update. - The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. - - iv) kernel->user to report event when replay threshold or a timeout - is exceeded. - -In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout -happened) is set to inform the user what happened. -Note the two flags are mutually exclusive. -The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. - -5) Exceptions to threshold settings ------------------------------------ - -If you have an SA that is getting hit by traffic in bursts such that -there is a period where the timer threshold expires with no packets -seen, then an odd behavior is seen as follows: -The first packet arrival after a timer expiry will trigger a timeout -event; i.e we don't wait for a timeout period or a packet threshold -to be reached. This is done for simplicity and efficiency reasons. - --JHS diff --git a/Documentation/networking/xfrm_sysctl.rst b/Documentation/networking/xfrm_sysctl.rst deleted file mode 100644 index 7d0c4b17c0bd..000000000000 --- a/Documentation/networking/xfrm_sysctl.rst +++ /dev/null @@ -1,11 +0,0 @@ -.. SPDX-License-Identifier: GPL-2.0 - -============ -XFRM Syscall -============ - -/proc/sys/net/core/xfrm_* Variables -=================================== - -xfrm_acq_expires - INTEGER - default 30 - hard timeout in seconds for acquire requests -- cgit v1.2.3 From 939ba8c5b81cbaf37781d7aa4849170860124a5e Mon Sep 17 00:00:00 2001 From: Bagas Sanjaya Date: Mon, 3 Nov 2025 08:50:30 +0700 Subject: MAINTAINERS: Add entry for XFRM documentation XFRM patches are supposed to be sent to maintainers under "NETWORKING [IPSEC]" heading, but it doesn't cover XFRM docs yet. Add the entry. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Bagas Sanjaya Signed-off-by: Steffen Klassert --- MAINTAINERS | 1 + 1 file changed, 1 insertion(+) diff --git a/MAINTAINERS b/MAINTAINERS index d652f4f27756..4f33daad40be 100644 --- a/MAINTAINERS +++ b/MAINTAINERS @@ -18041,6 +18041,7 @@ L: netdev@vger.kernel.org S: Maintained T: git git://git.kernel.org/pub/scm/linux/kernel/git/klassert/ipsec.git T: git git://git.kernel.org/pub/scm/linux/kernel/git/klassert/ipsec-next.git +F: Documentation/networking/xfrm/ F: include/net/xfrm.h F: include/uapi/linux/xfrm.h F: net/ipv4/ah4.c -- cgit v1.2.3