Documentation/networking/xfrm_sync.rst

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