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