Commit | Line | Data |
---|---|---|
a5cfea33 MCC |
1 | .. SPDX-License-Identifier: GPL-2.0 |
2 | ||
3 | ==== | |
4 | XFRM | |
5 | ==== | |
b8a99520 JHS |
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 | |
edb9a1b8 | 12 | events so that the SA can be safely moved from one machine to another |
b8a99520 JHS |
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. | |
edb9a1b8 | 21 | This way a backup stays as closely up-to-date as an active member. |
b8a99520 JHS |
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. | |
a5cfea33 | 48 | |
b8a99520 JHS |
49 | A XFRM_MSG_NEWAE will have at least two TLVs (as is |
50 | discussed further below). | |
51 | ||
a5cfea33 | 52 | aevent_id structure looks like:: |
b8a99520 JHS |
53 | |
54 | struct xfrm_aevent_id { | |
a5cfea33 MCC |
55 | struct xfrm_usersa_id sa_id; |
56 | xfrm_address_t saddr; | |
57 | __u32 flags; | |
58 | __u32 reqid; | |
b8a99520 JHS |
59 | }; |
60 | ||
2b5f6dcc JHS |
61 | The unique SA is identified by the combination of xfrm_usersa_id, |
62 | reqid and saddr. | |
b8a99520 JHS |
63 | |
64 | flags are used to indicate different things. The possible | |
a5cfea33 MCC |
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 */ | |
b8a99520 JHS |
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) | |
a5cfea33 | 90 | |
b8a99520 JHS |
91 | This TLV carries the running/current counter for byte lifetime since |
92 | last event. | |
93 | ||
94 | b)replay value (XFRMA_REPLAY_VAL) | |
a5cfea33 | 95 | |
b8a99520 JHS |
96 | This TLV carries the running/current counter for replay sequence since |
97 | last event. | |
98 | ||
99 | c)replay threshold (XFRMA_REPLAY_THRESH) | |
a5cfea33 | 100 | |
b8a99520 JHS |
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) | |
a5cfea33 | 105 | |
b8a99520 JHS |
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: | |
a5cfea33 | 110 | --------------------------------------------- |
b8a99520 JHS |
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: | |
a5cfea33 | 122 | |
b8a99520 JHS |
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. | |
a5cfea33 MCC |
135 | XFRM_MSG_GETAE does not carry any TLVs. |
136 | ||
b8a99520 JHS |
137 | The response is a XFRM_MSG_NEWAE which is formatted based on what |
138 | XFRM_MSG_GETAE queried for. | |
a5cfea33 | 139 | |
b8a99520 | 140 | The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. |
a5cfea33 MCC |
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 | |
b8a99520 JHS |
143 | |
144 | b) XFRM_MSG_NEWAE is issued by either user space to configure | |
a5cfea33 | 145 | or kernel to announce events or respond to a XFRM_MSG_GETAE. |
b8a99520 JHS |
146 | |
147 | i) user --> kernel to configure a specific SA. | |
a5cfea33 | 148 | |
b8a99520 JHS |
149 | any of the values or threshold parameters can be updated by passing the |
150 | appropriate TLV. | |
a5cfea33 | 151 | |
b8a99520 JHS |
152 | A response is issued back to the sender in user space to indicate success |
153 | or failure. | |
a5cfea33 | 154 | |
b8a99520 JHS |
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 | |
a5cfea33 | 159 | |
b8a99520 | 160 | The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs. |
a5cfea33 | 161 | |
b8a99520 JHS |
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 | |
a5cfea33 MCC |
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. | |
b8a99520 JHS |
170 | |
171 | iv) kernel->user to report event when replay threshold or a timeout | |
a5cfea33 MCC |
172 | is exceeded. |
173 | ||
b8a99520 JHS |
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 | |
edb9a1b8 | 186 | event; i.e we don't wait for a timeout period or a packet threshold |
b8a99520 JHS |
187 | to be reached. This is done for simplicity and efficiency reasons. |
188 | ||
189 | -JHS |