Linux IPsec overview

IPsec is a group of protocols used on top of IP for the purpose of authentication, encryption and secure exchange of encryption keys. These three activities correspond to three different protocols. The Authentication Header protocol, or AH for short, confirms the identity of the sender. Packet encryption is done by Encapsulating Security Payload or ESP. Finally, Internet Key Exchange or IKE is a mechanism for exchanging secret encryption keys used by ESP.

There is also an additional protocol, Payload Compression Protocol (IPComp). As it is next to impossible to achieve efficient compression of encrypted data, IPComp accommodates this shortcoming by compressing packets prior to ESP encryption. So while IPComp isn’t essential for actual security, it is essential for efficient net usage.

With the exception of IKE, all protocols are implemented somewhere in the depths of the Linux kernel. IKE is usually run as user-space daemon. There is an abundance of IKE implementations and there is always an option of putting keys manually.

As a part of the IPsec stack within the Linux kernel there are two databases. They are named Security Policy Database (SPD) and Security Association Database (SAD). Strictly speaking, those two databases look more like two tables than anything like relational databases, but nevertheless they do store data which is vital for IPsec functionality.

SAD stores Security Associations (SA). SA is used as a description of encryption protocols used on IPsec packets. The best analogy to describe security association would be a recipe. Just like a recipe is a list of directions and a set of ingredients for making something, SA is a mixture of directions and ingredients for the encryption of IPsec packets. With SA one can indicate the encryption of the authentication header and of the payload, and the encryption algorithm to be used for both of these tasks.

Like an unused recipe, unused SA doesn’t mean much. The purpose of both becomes apparent with usage. Security Policy (SP) is a mechanism which will put SA to the desired use. SP describes IPsec security procedure for a connection. SP can designate a host or port connection. Once a policy is set for a connection, the kernel will determine which security associations to apply to that connection. Security policies are stored in SPD database.

XFRM

This simple overview of IPsec functionality raises a new question: how to use all those mechanisms within Linux? The end user will probably be satisfied with running an IKE daemon and a front-end through which one can insert all the associations and policies in the kernel. A more advanced user can achieve a similar effect through command-line utilities like setkey or iproute.

As this article is aimed at the most advanced users—the programmers, the population for which “how to use” is an abbreviation for “how to use it from code” things get more complicated. That question is by an order of magnitude harder. To answer this, additional insight into the kernel is needed, to the point where we must introduce a part of the kernel known as XFRM.

Both SAD and SPD are handled by the kernel module known as XFRM. Upon request XFRM will add, get, update or delete entries from SAD or SPD databases. Communicating with XFRM the programmer handles the SAD and SPD databases. Communication is done by passing messages to XFRM. It is also bidirectional. XFRM passes similar messages to the programmer. This happens when some triggered event fires, or more usually as a response to a programmer’s action.

XFRM is located deep within the kernel and it isn’t directly visible to the programmer. It is also an undocumented part of the kernel. The standard way of the communication with XFRM is done trough the Netlink Sockets API which is the standard IPC mechanism for various parts of the kernel. More specifically, the part of Netlink of our interest is NETLINK_XFRM. Unfortunately, that part is complex and also undocumented. An additional API does exist. It is called rtnetlink and is a wrapper API for netlink. It is somewhat easier to use and it is somewhat documented. It is a part of iproute2 project.

Inserting simple Security Policy

The simplest way to add an SA or SP entry is trough command-line utilities like iproute or setkey. We’ll be using iproute. For the list of all functions possible on policies use:

$ip xfrm policy help

Iproute is capable of adding, listing, flushing, deleting or updating policies in the database. The simplest way to add one policy would be:

$ip xfrm policy add dir in

This will add one general SP to SPD. The analog way to do so in C would be this:

int xfrm_policy_add_simple() {
struct rtnl_handle rth;
struct {
   struct nlmsghdr                 n;
   struct xfrm_userpolicy_info     xpinfo;
   char                            buf[ 2048 ];
} req;

memset(&req, 0, sizeof(req));

// nlmsghdr initialization 
req.n.nlmsg_len = NLMSG_LENGTH(sizeof(req.xpinfo));
req.n.nlmsg_flags = NLM_F_REQUEST|NLM_F_CREATE|NLM_F_EXCL;
req.n.nlmsg_type = XFRM_MSG_NEWPOLICY;

// xfrm_userpolicy_info initialization
req.xpinfo.sel.family = AF_INET;
req.xpinfo.lft.soft_byte_limit = XFRM_INF;
req.xpinfo.lft.hard_byte_limit = XFRM_INF;
req.xpinfo.lft.soft_packet_limit = XFRM_INF;
req.xpinfo.lft.hard_packet_limit = XFRM_INF;
req.xpinfo.dir = XFRM_POLICY_IN; 

if (rtnl_open_byproto(&rth, 0, NETLINK_XFRM) < 0)
   exit(1);

if (rtnl_talk(&rth, &req.n, 0, 0, NULL, NULL, NULL) < 0)
   exit(2);

rtnl_close(&rth);

return 0;
}

The code is very simple. A quick explanation follows. In the first line we created an rtnetlink handler. Rtnetlink will take the burden of handling netlink sockets and this handler is used as a marker to those internal structures. That’s all there is to it. A more important part is the creation of the request. It is a structure composed out of three distinct features:

1. a Netlink message header
2. an XFRM message
3. a field of attributes (that 2k char buffer)

All netlink messages consist of the netlink message header (nlmsghdr) and data which it encapsulates. The netlink message header carries some general information about the message like its type or size. As our goal is to add policy to SPD, the message we’ll use is of type XFRM_MSG_NEWPOLICY, which is defined in linux\xfrm.h.

This type of xfrm message is associated with the xfrm_userpolicy_info structure which carries all important data about a policy. It is a quite complex structure because the policy carries quite a lot of information. But for now, as our goal is simple (adding the most general policy), we’ll ignore all those things. Just remember that when you need to add the port, the destination or source address, the way of tunneling, the transport protocol and many other things you’ll add it to xfrm_userpolicy_info. The things we have set here are the expiration times of the policy (which we set to infinity), IP4 as the transport protocol in use (AF_INET), and the direction of the policy to “in” (XFRM_POLICY_IN) as this is default. All these constants are defined in linux\xfrm.h.

The field of attributes is not used in this particular example. However, it is used in more complex tasks like sending a provisional number of policy templates etc. The field of attributes is a standard part of the netlink philosophy, and meant to be handled by RTA macros within netlink which take the burden of proper memory alignment and can’t really be described as the most intuitive thing in the world. After all, this is low-level system programming

The last step is opening a socket (NETLINK_XFRM socket), sending the request, and closing the socket. Upon failure the code will stop. That’s all there is to inserting a new policy into the kernel.

Success of this function can be seen by the use of:

$ip xfrm policy list

The flushing of the policy is done with a very intuitive command:

$ip xfrm policy flush

The actual working code with all the needed headers and such is present here. In later articles we will demonstrate somewhat more complicated handling of security associations and polices, and some general lines of xfrm internals like a general walkthrough of all types of messages and associated structures.

Hibernate offers us three basic ways to map class inheritance to relational database:

1. Table per class hierarchy
2. Table per subclass
3. Table per concrete class

Each of these have it's strengths and limitations and we will make short review of them and present simple examples based on following class hierarchy:

public abstract class Animal {
    private Long m_id;
    private String m_name;
    private BigDecimal m_weight;

    public Long getId() {
        return m_id;
    }
    public String getName() {
        return m_name;
    }
    public void setName(final String p_name) {
        m_name = p_name;
    }
    public BigDecimal getWeight() {
        return m_weight;
    }
    public void setWeight(final BigDecimal p_weight) {
        m_weight = p_weight;
    }
}

public class Bird extends Animal {
    private BigDecimal m_wingsSpan;

    public BigDecimal getWingsSpan() {
        return m_wingsSpan;
    }
    public void setWingsSpan(final BigDecimal p_wingsSpan) {
        m_wingsSpan = p_wingsSpan;
    }
}

public class Dog extends Animal {
    private BigDecimal m_lungsVolume;

    public BigDecimal getLungsVolume() {
        return m_lungsVolume;
    }
    public void setLungsVolume(final BigDecimal p_lungsVolume) {
        m_lungsVolume = p_lungsVolume;
    }
}

public class Fish extends Animal {
}

1. Table per class hierarchy

In this mapping approach we map whole class hierarchy to one database table. It's main feature is it's simplicity, we can read/save our object in just one table and there is no need to multiple create/update sql statements (when we save or update object) or join on multiple tables (when we read object). Main weakness of this approach is that we can't have NOT NULL constraint on any column mapped to property declared in any of subclasses.

<class name="Animal" table="ANIMAL">
        <id name="m_id" type="long" column="ID" access="field">
            <generator class="sequence">
                <param name="sequence">ANIMAL_SEQ</param>
            </generator>
        </id>

        <discriminator column="TYPE"/>

        <property name="name" type="string" length="100" column="NAME" not-null="true"/>
        <property name="weight" type="big_decimal" column="WEIGHT" not-null="true"/>

        <subclass name="Bird" discriminator-value="BIRD">
            <property name="wingsSpan" type="big_decimal" column="WING_SPAN"/>
        </subclass>

        <subclass name="Dog" discriminator-value="DOG">
            <property name="lungsVolume" type="big_decimal" column="LUNGS_VOLUME"/>
        </subclass>

        <subclass name="Fish" discriminator-value="FISH"/>
    </class>

2. Table per subclass

In this mapping approach we map properties contained in base class to one database table and properties contained in each subclass to it's target table. This way for hierarchy of one base class with three inherited classes we have four tables in database where each of tables mapped to subclass is connected to table mapped to base class by foreign key. Weakness of this approach is that we have more complicated database schema where it is more difficult to follow object in database. Strength of this approach is that we can use NOT NULL constraints to ensure integrity of all properties from subclasses. This is mapping where database structure closely follows object hierarchy.

<class name="Animal" table="ANIMAL">
        <id name="m_id" type="long" column="ID" access="field">
            <generator class="sequence">
                <param name="sequence">ANIMAL_SEQ</param>
            </generator>
        </id>

        <discriminator column="TYPE"/>

        <property name="name" type="string" length="100" column="NAME" not-null="true"/>
        <property name="weight" type="big_decimal" column="WEIGHT" not-null="true"/>

        <joined-subclass name="Bird" table="BIRD">
            <key column="ANIMAL_ID"/>
            <property name="wingsSpan" type="big_decimal" column="WING_SPAN" not-null="true"/>
        </joined-subclass>

        <joined-subclass name="Dog" table="DOG">
            <key column="ANIMAL_ID"/>
            <property name="lungsVolume" type="big_decimal" column="LUNGS_VOLUME" not-null="true"/>
        </joined-subclass>

        <joined-subclass name="Fish" table="FISH">
            <key column="ANIMAL_ID"/>
        </joined-subclass>
    </class>

3. Table per concrete class

In this mapping approach we map each concrete (non-abstract) subclass to one database table. Therefore we don't have to have database table for abstract root class and we have reduced number of tables to three and as result we can easily find all data for each concrete object instance in just one place in database. Problem with this mapping is that we have "column duplication" in database (for each field in base class we have column in subclass table).

<class name="Animal">
        <id name="m_id" type="long" column="ID" access="field">
            <generator class="sequence">
                <param name="sequence">ANIMAL_SEQ</param>
            </generator>
        </id>

        <discriminator column="TYPE"/>

        <property name="name" type="string" length="100" column="NAME" not-null="true"/>
        <property name="weight" type="big_decimal" column="WEIGHT" not-null="true"/>

        <union-subclass name="Bird" table="BIRD">
            <property name="wingsSpan" type="big_decimal" column="WING_SPAN" not-null="true"/>
        </union-subclass>

        <union-subclass name="Dog" table="DOG">
            <property name="lungsVolume" type="big_decimal" column="LUNGS_VOLUME" not-null="true"/>
        </union-subclass>

        <union-subclass name="Fish" table="FISH"/>
    </class>

So, which mapping approach should I use?

Before deciding which mapping to choose we have to take close look at our domain model and distribution of data (fields) through model (classes). One (extreme) case is that all properties are contained in our root class and we have subclasses used only to differentiate types of base class and to define different behaviour for each specific type. Another (also extreme) case is when we have base class used only to semantically mark kinship of our classes (and maybe define common behaviour) but all data (fields) are contained in subclasses.

First case would be ideal case for "table per class hierarchy" mapping and second case would be ideal for "table per concrete class" or "table per subclass" mapping. Of course, our problem will most often fall somewhere in between these two extremes and we will have to decide which approach should we take by weighting importance of NOT NULL constraint usage in ensuring our data integrity (if any property mapped to subclass is mandatory) versus simplicity of database schema (and relying on application to ensure our data integrity). Rule of thumb would be that for domain model where most data are contained in base class we would prefer to use "table per class hierarchy", for model where data are evenly distributed through base class and subclasses we would prefer to use "table per subclass" and for model where data are mostly contained in subclasses we would prefere to use "table per concrete class" or "table per subclass".

Hibernate offers use some additional mapping alternatives and it is possible to use combination of different mapping approaches for same class hierarchy. To get more information on this topic check Hibernate reference documentation.

One of the projects CROZ is currently participating in is dedicated to the production of Rich Client Application. Eclipse Rich Client Platform (Eclipse RCP) has been chosen as a platform for the production of client, whose main characteristic is that it enables XML configuration of user interface. The platform automatically manages various visual elements such as menus, toolbars, view or editor frames etc. User of the platform (or rather developer of the application) should concern himself with only the key business certain element is performing – for instance, about the action which should perform when selected from the menu or about the content of the view frame. The platform takes care of the rest – for instance, concerning the frame, its positioning and size, opening/closing, minimum/maximum, docking, stacking and so forth. That speeds up the development considerably and it is a lot easier to maintain the consistent look&feel of the application. In XML configuration of user interface it is customary to name the class which attends to a particular visual element. Your typical configuration element example:

<extension point="org.eclipse.ui.views">
<view id="net.croz.coolView" class="net.croz.CoolView" position="left"/>
</extension>

The basic work mode shows that the platform is controlling class instantiation and instance configuration, therefore the user has the command, via XML configuration, over only those class aspects which emerge form its role of visual element controlled by Eclipse RCP. For instance, it is characteristic that the class for the view frame will have dependencies on some sources of data which needs to be visualized. For all such things the class author is left his own devices. On the other hand, CROZ already has the tradition of exploiting Spring’s IoC object configuration, thus it is only natural that there should be a need for a solution which will enable control of the instantiation and object configuration to be moved from the Eclipse RCP to Spring’s IoC container. Fortunately, Eclipse RCP practices Factory Object approach – if there is a class name in the XML which implements the appropriate Factory interface, RCP will instantiate that class and then let that instance create the final object which controls the visual element.

Another important characteristic of the platform Eclipse RCP is that it enables modularity of application above the level offered by Java language itself. In fact, precisely that modularity is the main motivation for the adoption of XLM configuration. Basic approach is as follows: RCP itself is made of a module set (Eclipse term for “module” is “plugin” which we will use hereafter) of which for example, one is intended for managing visual elements. He declares extension points for each element category, for instance, the views point for view frames. Plugin developed by a platform user defines its extension for that point by stating its class name and other criterions concerning frame display in XML configuration. By the very addition of his plugin to the plugin set which compiles the application we can accomplish that it contributes its visual elements to the application without having to write the control code in Java.

The requirement for modularity of application is reflected on Spring configuration as well. It is obvious that one cannot build the entire application context in a centralized manner because that would mean how a certain “main” plugin should know beforehand about all the other plugins and about the configuration of their respective objects. Thus, each plugin should have its own context but it is preferable to be able to connect that context to some common, universally defined context which would contain objects of greater significance for the entire application.

We found an open-source project on the web [1] (we shall name it ESpring) which enables answering of these questions in a rather sophisticated style. The project in question was in a relatively rudimental state and was more of a proof-of-concept than a finalized product so we needed to finish it and de-bug it a great deal, however the key ideas remained untouched.

The project is composed of a single plugin which declares its extension point. Application plugins join their extensions to this point in order to contribute their application context to the central context register. The context is inscribed in the register under an ID defined in the extension. When producing its application context plugin can by ID ask ESpring for an arbitrary second application context to be used as its parent. Example of extension definition for ESpring:

<extension point="net.croz.espring.appContextContributors">
<appContextContributor id="coolPluginContext" parent="rootContext"
  class="net.croz.coolplugin.ApplicationContextContributor"/>
</extension>

All registered contexts are available anywhere in the Eclipse configuration database plugin.xml, where one customarily states the class name of the visual element. Instead of the class name of the desired object, we state the particular class name of the ESpring plugin, which in turn implements Factory interface and will deliver the object configured in the application context to the platform:

<extension point="org.eclipse.ui.views">
<view id="net.croz.coolView" 
 class="net.croz.espring.GetBean:coolPluginContext/coolView"
 position="left"/>
</extension>

Now comes in another important ability of Eclipse RCP without which this approach could not have become a reality: after the name of Factory-class we can add a colon and a string behind it which will be forwarded to the instance of that class. In this way we can transmit key data necessary for Factory to locate the appropriate application context and the object within it.

With a careful analysis of the described solution’s architecture one could complain that the creation of the application context has been unnecessarily complicated: it not enough to state just the location of configuration database but one needs to create ApplicationContextContributor class which does the creation of the application context itself. The reason for that is the above mentioned modularity of RCP plugins “above the level offered by Java language itself”: namely, one plugin can see only those classes of the other plugin which it explicitly declared to be “public”. Therefore it is necessary that the creation of application context be done by the class of the client plugin.

[1] Neil Bartlett, project „Eclipse RCP Spring Support“, http://sourceforge.net/projects/eclipse-spring