[XFRM Doc]: aevent description

[XFRM Doc]: aevent description

[jamal]

[-- Attachment #1: Type: text/plain, Size: 205 bytes --]

Dave,

There is dependency on the previous patch i sent since the issue that
patch fixes is assumed in this text description. It would be a good
idea to apply at the same time as the other.

cheers,
jamal

[-- Attachment #2: xfrm_sync_txt --]
[-- Type: text/plain, Size: 7234 bytes --]


Documentation to describe asynchronous xfrm events to help people
writting HA code in user space.

Signed-off-by: Jamal Hadi Salim <hadi@cyberus.ca>
---

 Documentation/networking/xfrm_sync.txt |  166 ++++++++++++++++++++++++++++++++
 1 files changed, 166 insertions(+), 0 deletions(-)

diff --git a/Documentation/networking/xfrm_sync.txt b/Documentation/networking/xfrm_sync.txt
new file mode 100644
index 0000000..8f474aa
--- /dev/null
+++ b/Documentation/networking/xfrm_sync.txt
@@ -0,0 +1,166 @@
+
+The sync patches work is based on initial patches from 
+Krisztian <hidden@balabit.hu> and others and additional patches
+from Jamal <hadi@cyberus.ca>.
+
+The end goal for syncing is to be able to insert attributes + generate 
+events so that the an SA can be safely moved from one machine to another 
+for HA purposes. 
+The idea is to synchronize the SA so that the takeover machine can do 
+the processing of the SA as accurate as possible if it has access to it.
+
+We already have the ability to generate SA add/del/upd events.
+These patches add ability to sync and have accurate lifetime byte (to 
+ensure proper decay of SAs) and replay counters to avoid replay attacks 
+with as minimal loss at failover time.
+This way a backup stays as closely uptodate as an active member. 
+
+Because the above items change for every packet the SA receives,
+it is possible for a lot of the events to be generated.
+For this reason, we also add a nagle-like algorithm to restrict
+the events. i.e we are going to set thresholds to say "let me
+know if the replay sequence threshold is reached or 10 secs have passed"
+These thresholds are set system-wide via sysctls or can be updated
+per SA.
+
+The identified items that need to be synchronized are:
+- the lifetime byte counter 
+note that: lifetime time limit is not important if you assume the failover 
+machine is known ahead of time since the decay of the time countdown 
+is not driven by packet arrival.
+- the replay sequence for both inbound and outbound
+
+1) Message Structure
+----------------------
+
+nlmsghdr:aevent_id:optional-TLVs.
+
+The netlink message types are:
+
+XFRM_MSG_NEWAE and XFRM_MSG_GETAE.
+
+A XFRM_MSG_GETAE does not have TLVs.
+A XFRM_MSG_NEWAE will have at least two TLVs (as is
+discussed further below).
+
+aevent_id structure looks like:
+
+   struct xfrm_aevent_id {
+             struct xfrm_usersa_id           sa_id;
+             __u32                           flags;
+   };
+
+xfrm_usersa_id in this message layout identifies the SA. 
+
+flags are used to indicate different things. The possible
+flags are:
+        XFRM_AE_RTHR=1, /* replay threshold*/
+        XFRM_AE_RVAL=2, /* replay value */
+        XFRM_AE_LVAL=4, /* lifetime value */
+        XFRM_AE_ETHR=8, /* expiry timer threshold */
+        XFRM_AE_CR=16, /* Event cause is replay update */
+        XFRM_AE_CE=32, /* Event cause is timer expiry */
+        XFRM_AE_CU=64, /* Event cause is policy update */
+
+How these flags are used is dependent on the direction of the
+message (kernel<->user) as well the cause (config, query or event).
+This is described below in the different messages.
+
+The pid will be set appropriately in netlink to recognize direction
+(0 to the kernel and pid = processid that created the event 
+when going from kernel to user space)
+
+A program needs to subscribe to multicast group XFRMNLGRP_AEVENTS
+to get notified of these events.
+
+2) TLVS reflect the different parameters:
+-----------------------------------------
+
+a) byte value (XFRMA_LTIME_VAL)
+This TLV carries the running/current counter for byte lifetime since 
+last event.
+
+b)replay value (XFRMA_REPLAY_VAL)
+This TLV carries the running/current counter for replay sequence since
+last event.
+
+c)replay threshold (XFRMA_REPLAY_THRESH)
+This TLV carries the threshold being used by the kernel to trigger events 
+when the replay sequence is exceeded.
+
+d) expiry timer (XFRMA_ETIMER_THRESH)
+This is a timer value in milliseconds which is used as the nagle
+value to rate limit the events.
+
+3) Default configurations for the parameters:
+----------------------------------------------
+
+By default these events should be turned off unless there is 
+at least one listener registered to listen to the multicast
+group XFRMNLGRP_AEVENTS. 
+
+Programs installing SAs will need to specify the two thresholds, however,
+in order to not change existing applications such as racoon
+we also provide default threshold values for these different parameters
+in case they are not specified.
+
+the two sysctls/proc entries are:
+a) /proc/sys/net/core/sysctl_xfrm_aevent_etime
+used to provide default values for the XFRMA_ETIMER_THRESH in incremental 
+units of time of 100ms. The default is 10 (1 second)
+
+b) /proc/sys/net/core/sysctl_xfrm_aevent_rseqth
+used to provide default values for XFRMA_REPLAY_THRESH parameter
+in incremental packet count. The default is two packets.
+
+4) Message types
+----------------
+
+a) XFRM_MSG_GETAE issued by user-->kernel. 
+XFRM_MSG_GETAE does not carry any TLVs. 
+The response is a XFRM_MSG_NEWAE which is formatted based on what 
+XFRM_MSG_GETAE queried for. 
+The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
+*if XFRM_AE_RTHR flag is set, then XFRMA_REPLAY_THRESH is also retrieved
+*if XFRM_AE_ETHR flag is set, then XFRMA_ETIMER_THRESH is also retrieved
+
+b) XFRM_MSG_NEWAE is issued by either user space to configure
+or kernel to announce events or respond to a XFRM_MSG_GETAE.
+
+i) user --> kernel to configure a specific SA.
+any of the values or threshold parameters can be updated by passing the 
+appropriate TLV. 
+A response is issued back to the sender in user space to indicate success 
+or failure. 
+In the case of success, additionally an event with 
+XFRM_MSG_NEWAE is also issued to any listeners as described in iii).
+
+ii) kernel->user direction as a response to XFRM_MSG_GETAE
+The response will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
+The threshold TLVs will be included if explicitly requested in
+the XFRM_MSG_GETAE message.
+
+iii) kernel->user to report as event if someone sets any values or
+thresholds for an SA using XFRM_MSG_NEWAE (as described in #i above).
+In such a case XFRM_AE_CU flag is set to inform the user that
+the change happened as a result of an update.
+The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
+
+iv) kernel->user to report event when replay threshold or a timeout
+is exceeded.
+In such a case either XFRM_AE_CR (replay exceeded) or XFRM_AE_CE (timeout
+happened) is set to inform the user what happened.
+Note the two flags are mutually exclusive.
+The message will always have XFRMA_LTIME_VAL and XFRMA_REPLAY_VAL TLVs.
+
+Exceptions to threshold settings
+--------------------------------
+
+If you have an SA that is getting hit by traffic in bursts such that
+there is a period where the timer threshold expires with no packets
+seen, then an odd behavior is seen as follows:
+The first packet arrival after a timer expiry will trigger a timeout 
+aevent; i.e we dont wait for a timeout period or a packet threshold
+to be reached. This is done for simplicity and efficiency reasons.
+
+-JHS

Re: [XFRM Doc]: aevent description

[David S. Miller]

From: jamal <hadi@cyberus.ca>
Date: Thu, 13 Apr 2006 09:00:08 -0400

> There is dependency on the previous patch i sent since the issue that
> patch fixes is assumed in this text description. It would be a good
> idea to apply at the same time as the other.

Applied, after fixing 28 lines containing trailing whitespace :-)

Re: [XFRM Doc]: aevent description

[jamal]

On Fri, 2006-14-04 at 15:05 -0700, David S. Miller wrote:
> From: jamal <hadi@cyberus.ca>
> Date: Thu, 13 Apr 2006 09:00:08 -0400
> 
> > There is dependency on the previous patch i sent since the issue that
> > patch fixes is assumed in this text description. It would be a good
> > idea to apply at the same time as the other.
> 
> Applied, after fixing 28 lines containing trailing whitespace :-)

yikes ;->
Ok, so how do i avoid this in the future? Note, this was a _brand new_
file, so it is a little bizarre.

cheers,
jamal 

Re: [XFRM Doc]: aevent description

[David S. Miller]

From: jamal <hadi@cyberus.ca>
Date: Thu, 20 Apr 2006 06:58:45 -0400

> On Fri, 2006-14-04 at 15:05 -0700, David S. Miller wrote:
> > From: jamal <hadi@cyberus.ca>
> > Date: Thu, 13 Apr 2006 09:00:08 -0400
> > 
> > > There is dependency on the previous patch i sent since the issue that
> > > patch fixes is assumed in this text description. It would be a good
> > > idea to apply at the same time as the other.
> > 
> > Applied, after fixing 28 lines containing trailing whitespace :-)
> 
> yikes ;->
> Ok, so how do i avoid this in the future? Note, this was a _brand new_
> file, so it is a little bizarre.

This command:

	git apply --check --whitespace=error-all $1

will spit out errors if your patch adds trailing whitespace
or will not apply cleanly to the current GIT tree.