1.. SPDX-License-Identifier: GPL-2.0 2 3========= 4XFRM sync 5========= 6 7The sync patches work is based on initial patches from 8Krisztian <hidden@balabit.hu> and others and additional patches 9from Jamal <hadi@cyberus.ca>. 10 11The end goal for syncing is to be able to insert attributes + generate 12events so that the SA can be safely moved from one machine to another 13for HA purposes. 14The idea is to synchronize the SA so that the takeover machine can do 15the processing of the SA as accurate as possible if it has access to it. 16 17We already have the ability to generate SA add/del/upd events. 18These patches add ability to sync and have accurate lifetime byte (to 19ensure proper decay of SAs) and replay counters to avoid replay attacks 20with as minimal loss at failover time. 21This way a backup stays as closely up-to-date as an active member. 22 23Because the above items change for every packet the SA receives, 24it is possible for a lot of the events to be generated. 25For this reason, we also add a nagle-like algorithm to restrict 26the events. i.e we are going to set thresholds to say "let me 27know if the replay sequence threshold is reached or 10 secs have passed" 28These thresholds are set system-wide via sysctls or can be updated 29per SA. 30 31The identified items that need to be synchronized are: 32- the lifetime byte counter 33note that: lifetime time limit is not important if you assume the failover 34machine is known ahead of time since the decay of the time countdown 35is not driven by packet arrival. 36- the replay sequence for both inbound and outbound 37 381) Message Structure 39-------------------- 40 41nlmsghdr:aevent_id:optional-TLVs. 42 43The netlink message types are: 44 45XFRM_MSG_NEWAE and XFRM_MSG_GETAE. 46 47A XFRM_MSG_GETAE does not have TLVs. 48 49A XFRM_MSG_NEWAE will have at least two TLVs (as is 50discussed further below). 51 52aevent_id structure looks like:: 53 54 struct xfrm_aevent_id { 55 struct xfrm_usersa_id sa_id; 56 xfrm_address_t saddr; 57 __u32 flags; 58 __u32 reqid; 59 }; 60 61The unique SA is identified by the combination of xfrm_usersa_id, 62reqid and saddr. 63 64flags are used to indicate different things. The possible 65flags are:: 66 67 XFRM_AE_RTHR=1, /* replay threshold*/ 68 XFRM_AE_RVAL=2, /* replay value */ 69 XFRM_AE_LVAL=4, /* lifetime value */ 70 XFRM_AE_ETHR=8, /* expiry timer threshold */ 71 XFRM_AE_CR=16, /* Event cause is replay update */ 72 XFRM_AE_CE=32, /* Event cause is timer expiry */ 73 XFRM_AE_CU=64, /* Event cause is policy update */ 74 75How these flags are used is dependent on the direction of the 76message (kernel<->user) as well the cause (config, query or event). 77This is described below in the different messages. 78 79The pid will be set appropriately in netlink to recognize direction 80(0 to the kernel and pid = processid that created the event 81when going from kernel to user space) 82 83A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS 84to get notified of these events. 85 862) TLVS reflect the different parameters 87---------------------------------------- 88 89a) byte value (XFRMA_LTIME_VAL) 90 91 This TLV carries the running/current counter for byte lifetime since 92 last event. 93 94b) replay value (XFRMA_REPLAY_VAL) 95 96 This TLV carries the running/current counter for replay sequence since 97 last event. 98 99c) replay threshold (XFRMA_REPLAY_THRESH) 100 101 This TLV carries the threshold being used by the kernel to trigger events 102 when the replay sequence is exceeded. 103 104d) expiry timer (XFRMA_ETIMER_THRESH) 105 106 This is a timer value in milliseconds which is used as the nagle 107 value to rate limit the events. 108 1093) Default configurations for the parameters 110-------------------------------------------- 111 112By default these events should be turned off unless there is 113at least one listener registered to listen to the multicast 114group XFRMNLGRP_AEVENTS. 115 116Programs installing SAs will need to specify the two thresholds, however, 117in order to not change existing applications such as racoon 118we also provide default threshold values for these different parameters 119in case they are not specified. 120 121the two sysctls/proc entries are: 122 123a) /proc/sys/net/core/sysctl_xfrm_aevent_etime 124 125 Used to provide default values for the XFRMA_ETIMER_THRESH in incremental 126 units of time of 100ms. The default is 10 (1 second) 127 128b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth 129 130 Used to provide default values for XFRMA_REPLAY_THRESH parameter 131 in incremental packet count. The default is two packets. 132 1334) Message types 134---------------- 135 136a) XFRM_MSG_GETAE issued by user-->kernel. 137 XFRM_MSG_GETAE does not carry any TLVs. 138 139 The response is a XFRM_MSG_NEWAE which is formatted based on what 140 XFRM_MSG_GETAE queried for. 141 142 The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. 143 144 * if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved 145 * if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved 146 147b) XFRM_MSG_NEWAE is issued by either user space to configure 148 or kernel to announce events or respond to a XFRM_MSG_GETAE. 149 150 i) user --> kernel to configure a specific SA. 151 152 any of the values or threshold parameters can be updated by passing the 153 appropriate TLV. 154 155 A response is issued back to the sender in user space to indicate success 156 or failure. 157 158 In the case of success, additionally an event with 159 XFRM_MSG_NEWAE is also issued to any listeners as described in iii). 160 161 ii) kernel->user direction as a response to XFRM_MSG_GETAE 162 163 The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. 164 165 The threshold TLVs will be included if explicitly requested in 166 the XFRM_MSG_GETAE message. 167 168 iii) kernel->user to report as event if someone sets any values or 169 thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above). 170 In such a case XFRM_AE_CU flag is set to inform the user that 171 the change happened as a result of an update. 172 The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. 173 174 iv) kernel->user to report event when replay threshold or a timeout 175 is exceeded. 176 177In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout 178happened) is set to inform the user what happened. 179Note the two flags are mutually exclusive. 180The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. 181 1825) Exceptions to threshold settings 183----------------------------------- 184 185If you have an SA that is getting hit by traffic in bursts such that 186there is a period where the timer threshold expires with no packets 187seen, then an odd behavior is seen as follows: 188The first packet arrival after a timer expiry will trigger a timeout 189event; i.e we don't wait for a timeout period or a packet threshold 190to be reached. This is done for simplicity and efficiency reasons. 191 192-JHS 193