1 .. SPDX-License-Identifier: GPL-2.0
2
3 ====
4 XFRM
5 ====
6
7 The sync patches work is based on initial patc
8 Krisztian <hidden@balabit.hu> and others and ad
9 from Jamal <hadi@cyberus.ca>.
10
11 The end goal for syncing is to be able to inse
12 events so that the SA can be safely moved from
13 for HA purposes.
14 The idea is to synchronize the SA so that the
15 the processing of the SA as accurate as possib
16
17 We already have the ability to generate SA add
18 These patches add ability to sync and have acc
19 ensure proper decay of SAs) and replay counter
20 with as minimal loss at failover time.
21 This way a backup stays as closely up-to-date
22
23 Because the above items change for every packe
24 it is possible for a lot of the events to be g
25 For this reason, we also add a nagle-like algo
26 the events. i.e we are going to set thresholds
27 know if the replay sequence threshold is reach
28 These thresholds are set system-wide via sysct
29 per SA.
30
31 The identified items that need to be synchroni
32 - the lifetime byte counter
33 note that: lifetime time limit is not importan
34 machine is known ahead of time since the decay
35 is not driven by packet arrival.
36 - the replay sequence for both inbound and out
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 (
50 discussed further below).
51
52 aevent_id structure looks like::
53
54 struct xfrm_aevent_id {
55 struct xfrm_usersa_id s
56 xfrm_address_t s
57 __u32 f
58 __u32 r
59 };
60
61 The unique SA is identified by the combination
62 reqid and saddr.
63
64 flags are used to indicate different things. T
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 thresh
71 XFRM_AE_CR=16, /* Event cause is repla
72 XFRM_AE_CE=32, /* Event cause is timer
73 XFRM_AE_CU=64, /* Event cause is polic
74
75 How these flags are used is dependent on the d
76 message (kernel<->user) as well the cause (con
77 This is described below in the different messa
78
79 The pid will be set appropriately in netlink t
80 (0 to the kernel and pid = processid that crea
81 when going from kernel to user space)
82
83 A program needs to subscribe to multicast grou
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 f
92 last event.
93
94 b)replay value (XFRMA_REPLAY_VAL)
95
96 This TLV carries the running/current counter f
97 last event.
98
99 c)replay threshold (XFRMA_REPLAY_THRESH)
100
101 This TLV carries the threshold being used by t
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
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 u
113 at least one listener registered to listen to
114 group XFRMNLGRP_AEVENTS.
115
116 Programs installing SAs will need to specify t
117 in order to not change existing applications s
118 we also provide default threshold values for t
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_E
125 units of time of 100ms. The default is 10 (1 s
126
127 b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqt
128 used to provide default values for XFRMA_REPLA
129 in incremental packet count. The default is tw
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 form
138 XFRM_MSG_GETAE queried for.
139
140 The response will always have XFRMA_LTIME_VAL
141 * if XFRM_AE_RTHR flag is set, then XFRMA_REPL
142 * if XFRM_AE_ETHR flag is set, then XFRMA_ETIM
143
144 b) XFRM_MSG_NEWAE is issued by either user spa
145 or kernel to announce events or respond to
146
147 i) user --> kernel to configure a specific SA.
148
149 any of the values or threshold parameters can
150 appropriate TLV.
151
152 A response is issued back to the sender in use
153 or failure.
154
155 In the case of success, additionally an event
156 XFRM_MSG_NEWAE is also issued to any listeners
157
158 ii) kernel->user direction as a response to XF
159
160 The response will always have XFRMA_LTIME_VAL
161
162 The threshold TLVs will be included if explici
163 the XFRM_MSG_GETAE message.
164
165 iii) kernel->user to report as event if someon
166 thresholds for an SA using XFRM_MSG_NEWAE
167 In such a case XFRM_AE_CU flag is set to
168 the change happened as a result of an upd
169 The message will always have XFRMA_LTIME_
170
171 iv) kernel->user to report event when replay t
172 is exceeded.
173
174 In such a case either XFRM_AE_CR (replay excee
175 happened) is set to inform the user what happe
176 Note the two flags are mutually exclusive.
177 The message will always have XFRMA_LTIME_VAL a
178
179 Exceptions to threshold settings
180 --------------------------------
181
182 If you have an SA that is getting hit by traff
183 there is a period where the timer threshold ex
184 seen, then an odd behavior is seen as follows:
185 The first packet arrival after a timer expiry
186 event; i.e we don't wait for a timeout period
187 to be reached. This is done for simplicity and
188
189 -JHS
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.