[redhat-lspp] IPSec Configuration doc

Joy Latten latten at austin.ibm.com
Wed Nov 15 15:39:03 UTC 2006

Klaus requested some basic steps and info for
configuring labeled ipsec. I started and came up with 
the following which can later be used to assist those
new to labeled ipsec and wishing to understand and use it.
This is by no means complete. I will fill in and improve
in time. Let me know if anything is incorrect or can be improved.

Currently, I am unable to successfully configure and run labeled
ipsec in enforcing mode on lspp 55 kernel. I'm working on ironing out
policy complaints so we can run in enforcing mode. Has anyone else
tried this?


A. Basic IPSec
B. Labeled IPSec
C. Configuring Labeled IPSec
D. Troubleshooting


Basic Labeled IPsec Configuration

You will need to have selinux installed as well as 
ipsec-tools-0.6.5-6 or later.

A basic IPsec configuration consists of ipsec security policy
and ipsec security associations.

IPsec security policies are stored in the Security Policy Database (SPD)
which resides in the kernel. The IPsec policy contains the information 
on the security services offered to an IP packet. It is indexed by the 
selectors; source and desination addresses, source and destination
and protocol.

The SPD is consulted for inbound and outbound processing 
of IP packets. Thus a traffic stream must have two policy
entries. One for inbound and another for outbound.

IPSec policy is entered manually by the setkey utility, 
which is part of the ipsec-tools package.

IPsec security associations are stored in the Security Association
Database (SAD), which also resides in the kernel. SAs are the agreements
established between two communicating entities. They contain the info
used to secure the IP packet.

SAs are one way. Thus a trafic stream will have two SAs. One for 
processing inbound packets and another for outbound packets.

SAs are created manually by using the setkey utility. The 
info passed to the setkey utility, such as cryptographic keys, 
algorithms, etc... must have been agreed upon by local and remote 
entities before entering. SAs are created dynamically, that is, 
created when needed, by using an IKE daemon. This daemon is named
racoon and can be found in the ipsec-tools package.

The racoon daemon uses a configuration file called racoon.conf.
The racoon.conf contains info that is used to create ISAKMP SAs
and IPSec SAs. 

ISAKMP SAs are used to establish secure communications
between local and remote racoon daemons in which to negotiate
IPSec SAs.


How Labeled IPSec works.

Labeled IPSec has extended IPSec such that IPSec Security Policy
and Security Associations may contain selinux labels.

How to add a Label in IPsec.
An IPsec Policy is manually entered using setkey utility.
A security context is included in the parameters entered into
the policy.

For example, 

spdadd any 
-ctx 1 1 "system_u:object_r:unlabeled_t:s3:c1.c5"
 -P in ipsec
spdadd any 
-ctx 1 1 "system_u:object_r:unlabeled_t:s3:c1.c5"
 -P out ipsec

Whether you decide to manually or dynamically create SAs,
the IPsec policy must be entered manually, first.

The kernel does an access check to determine whether the 
subject/process is allowed to set the security context 
contained in the policy. *(association:setcontext)

Manually created SAs
If entering Security Associations manually, you will have already
determined parameters required between the two communicating
hosts. You would enter these paramaters manually using setkey.

For example,

add esp 35590
-m transport
-ctx 1 1 "system_u:object_r:unlabeled_t:s0" 
-E 3des-cbc "06183223c23a21e8b36c566b"
-A hmac-md5 "IPSETEST89ABCDEF";

add esp 12360 
-m transport
-ctx 1 1 "system_u:object_r:unlabeled_t:s0"
-E 3des-cbc "06183223c23a21e8b36c566b"
-A hmac-md5 "IPSETEST89ABCDEF";

Dynamically created SAs
Usually the following happens to dynamically establish an SA.
An outbound packet is generated via an application, etc...
The IP layer checks the SPD for a policy. In labeled networking, 
if there isn't a policy, the packet is considered "unlabeled". 
If there is a policy containing a security context, SELinux
checks to see if the flow is allowed to access this policy.
The flow's security context must "polmatch" to the security
context contained in the policy. *(association:polmatch)
If it doesn't the packet will be dropped. If it does, the IP layer 
will next look for an SA.

If an SA has not been established yet, the linux
kernel sends an ACQUIRE message to all listening key sockets.
The racoon daemon will be listening. 

The ACQUIRE message is used to tell racoon to negotiate 
and "acquire" an SA. The kernel sends necessary info 
in the ACQUIRE, like source and destination address. 
If the policy contained a security context, then the
ACQUIRE will include a security context. However, it
won't be the same context as the policy. Instead, it
will be that of the socket which generated the packet.
The kernel will do an access check to see if the process
has permissions to set this context in SA that is to be
negotiated. *(association:setcontext)
If not, the ACQUIRE message is not sent and the packet is

Racoon will perform an access check to see if the security
context for the proposed SA "polmatches" to the security
context of the ipsec policy. *(association:polmatch)
If it doesn't, racoon complains about not being able to find 
a corresponding policy and negotiations are dropped. Ultimately, 
this results in no communications on this traffic stream. 

Once the SA is established, communications can begin for the
traffic stream. In Linux, the packet that generated the ACQUIRE
message is dropped. Thus you must try the communications again
once the SA is established. For example, "ping 10.x.x.x" results in
an ACQUIRE message. This ping fails since the packet is dropped.
Once the SA is established, another "ping 10.x.x.x" should work.

If an SA exists, note this will also be the case for manually
created SAs, no ACQUIRE message is sent. Instead, the kernel
does an access check. It checks that the flow is permitted to
use the SA. *(association:sendto)
If not, the packet is dropped. Otherwise, the packet is sent.

Note to Joy: More explanantion about how Linux handles SA bundles
and templates because there is another check in there.
See xfrm_find_bundle() and xfrm_tmpl_resolv().
Also need to add postroute_last() check done in netfiler.

When a labeled ipsec packet is received, the SPI, Source and Destination
addresses are extracted from the packet and used to lookup the SA. 
An SPI indicates that an SA pair has been established and all 
"polmatches" as described above have succeeded. Otherwise, the
SA would not have been "established". By established I mean 
accepted into the SAD. 

Once all ipsec processing has completed, the packet is passed
up to the transport layer. A check is done here to ensure the
socket has permission to receive data/packets labeled ith 
the security context from the SA used. *(association:recvfrom)


Configuring Labeled IPSec

Basic steps to use:

The examples used below are for Machine A, whose ipaddress is and Machine B whose ipaddress is
Machine A and Machine B wish to use labeled ipsec to secure
all communications between them.

All ipsec configuration is done in the sysadm_r role.

1. You must first add policies to the policy database for a
   particular traffic stream. To do this, add policy to a file
   and then use setkey to add the contents to the SPD.
For example, on Machine A, the file /tmp/setkey.ipsec contains 
the following policy info:

	spdadd any 
	-ctx 1 1 "system_u:object_r:unlabeled_t:s0:c0"
	-P out ipsec

	spdadd any
	-ctx 1 1 "system_u:object_r:unlabeled_t:s0:c0"
	-P in ipsec

Machine B's file /tmp/setkey.ipsec contains:

	spdadd any 
	-ctx 1 1 "system_u:object_r:unlabeled_t:s0:c0"
	-P in ipsec

	spdadd any
	-ctx 1 1 "system_u:object_r:unlabeled_t:s0:c0"
	-P out ipsec

NOTE: The only thing different on each machine is the direction
      "-P in|out".

  On each machine, run "setkey -f /tmp/setkey.label" to add the 
  policy to the SPD.

2. Now you need to configure racoon. For a simple config,
   I use pre-shared keys with a very basic racoon configuration.
   The two files I will use are psk.txt for preshared keys and
   racoon's basic config file, racoon.conf.
For example:
	I first add the following to /etc/racoon/psk.txt,
	(please add whatever text you want for your shared
	secret key. In this example, I used "flibbertigibbet".)    flibbertigibbet   flibbertigibbet

   In /etc/racoon/racoon.conf, I pretty much use the defaults.
   I have the following in my /etc/racoon/racoon.conf:

	path include "/etc/racoon";
	path pre_shared_key "/etc/racoon/psk.txt";
	path certificate "/etc/racoon/certs";

	sainfo anonymous
        	pfs_group 2;
        	lifetime time 1 hour ;
        	encryption_algorithm 3des, aes ;
        	authentication_algorithm hmac_sha1 ;
        	compression_algorithm deflate ;

NOTE: EACH IPsec SA racoon establishes will have the parameters
in sainfo anonymous. 

	On both Machine A and Machine B, start the racoon daemon. 
        On the command line issue,

To stop racoon, get its pid:
	ps -ef | grep racoon 
and then
	kill <racoon's pid>

Viewing and removing contents of SAD and SPD.
1. To view contents of SAD:
	setkey -D

2. To view contents of SPD:
	setkey -DP

3. To flush contents of SAD:
	setkey -F

4. To flush contents of SPD:
	setkey -FP


Troublshooting labeled ipsec
1. Racoon logs info to /var/log/messages.
2. Start racoon in foreground and turn on additional debugging:
	racoon -d [-d] -F
The more [-d]s you enter, the more debug info you get.

3. View the /var/log/audit/audit.log file for denied messages.
Search on "association". Most labeled ipsec permissions are in
the association class.
Also search on "comm=setkey" or "comm=racoon" to see if racoon or
setkey generated any denied messages.

More information about the redhat-lspp mailing list