Linux ip xfrm: What is the purpose of the tmpl?

Question

If we take an example of the Linux ip xfrm command:

 ip xfrm policy add src $LOCAL dst $REMOTE dir out tmpl src $SRC dst $DST proto esp reqid $ID mode tunnel

What does the tmpl do?

---

UPDATE: Of course, I understand we need to specify the $SRC and $DST. But, since those are already specified in the SA, via the ip xfrm state command, why do we need to repeat them in the tmpl? And what is the meaning of calling it a "template"? To me, it seems its just a pointer to a preexisting SA (state).

Answer 1

It tells the kernel how to process packets (for out policies), or where packets must come from (for in policies) when traffic matches this policy (fwd policies are a bit special as they might apply in both directions depending on the selector, see this answer). In your example the policy will send traffic through the ESP tunnel mode SA with endpoint IP addresses $SRC and $DST, and reqid $ID.

Why do we need to repeat them in the tmpl?

To actually find the SA/state. These are stored in a hashtable and the addresses (in particular the destination address) are part of the hash value. For tunnel mode SAs the addresses of the packet that matched the outbound policy don't necessarily match the addresses of the SA (for transport mode you might not have to add the addresses to the template).

And what is the meaning of calling it a "template"?

Not sure, but could be related to acquires, that is, if no matching SA has yet been established the information serves as template for the keying daemon when creating a new SA.

Answer 2

The purpose of the template is to match between policy and state (SA). The source/destination IP in the policy usually are different from what is used in the state, for this reason an additional source/destination IP pair is needed.

It is called a template, because it is used to match the ID (see man ip-xfrm) provided in the state. Here is the definition for template in the manual page:

       TMPL := ID [ mode MODE ] [ reqid REQID ] [ level LEVEL ]

       ID := [ src ADDR ] [ dst ADDR ] [ proto XFRM-PROTO ] [ spi SPI ]

As you can see it must contain an ID, which is exactly the same as within an xfrm state.

Answer 3

Look at the comment about "Organization of SPD aka "XFRM rules"" in net/xfrm.h:

Basic objects:

• policy rule, struct xfrm_policy (=SPD entry)
• bundle of transformations, struct dst_entry == struct xfrm_dst (=SA bundle)
• instance of a transformer, struct xfrm_state (=SA)
• template to clone xfrm_state, struct xfrm_tmpl

... policy entry has list of up to XFRM_MAX_DEPTH transformations, described by templates xfrm_tmpl. Each template is resolved to a complete xfrm_state (see below) and we pack bundle of transformations to a dst_entry returned to requestor.
...
Having this template we search through SAD searching for entries with appropriate mode/proto/algo, permitted by selector. If no appropriate entry found, it is requested from key manager.

So:

1. each tmpl defines one transformation for IP packets.
   Every transformation means one more layer of encapsulation for IP packets.
   Example: to compress traffic and send it over an encrypted tunnel we would specify two tmpls: the 1st for IPComp, the 2nd for ESP.
2. tmpl acts as a template for xfrm_state (=SA) creation.

Detailed definitions and explanations for SP and SA can be found in the IPsec standard (RFC 4301: Security Architecture for the Internet Protocol).

In short your example

ip xfrm policy add src $LOCAL dst $REMOTE dir out tmpl src $SRC dst $DST proto esp reqid $ID mode tunnel

creates an SP for the outgoing traffic which matches selector src $LOCAL dst $REMOTE. Here $REMOTE is an IP address of packets' final destination.

tmpl src $SRC dst $DST proto esp reqid $ID mode tunnel defines one transformation for the matched traffic — a ESP tunnel: every matched IP packet will be wrapped in a ESP packet and sent to $DST. Here $DST is an IP address of the remote end of the ESP tunnel.

Of course, I understand we need to specify the $SRC and $DST. But, since those are already specified in the SA, via the ip xfrm state command, why do we need to repeat them in the tmpl?

Strictly speaking SA do not have to exist when we create SP.
A typical case (it is even described in IPsec standard) is when SP exists on its own and creation of the corresponding SA is only triggered by the first IP packet which matches the SP's selector.

Answer 4

In case of outbound processing, tmpl is used to find SA which is to be used for respective interface's traffic transformation