Configuring KAME for IPsec: manual keying

Jun-ichiro itojun Itoh, KAME Project

$Id: index.html,v 1.1 2001/04/17 03:42:16 itojun Exp $

Update note: We used sysctl MIBs for controlling host-wide IPsec policy in the past. Now it is preferred to configure SPD entries by using spdadd subcommand, than using sysctl MIBs, to control security policy for outbound packets. The following examples use SPD entries.

Introduction

KAME advanced networking kit is ready for performing IPsec operation. However, IPsec requires careful configuration, as it is related to the security policy of the host/site/organization/whatever.

This document tries to describe how you can configure IPsec connection between two hosts, or two organizations.

NOTE: To use IPsec part of KAME stack, please use very recent KAME kit as they are frequently updated. Please report any bugs to our mailing list or our bug database.

If you find any mistakes, please let the author know. The document will be updated right away. Thank you!

IPsec primer

IPsec stands for "IP security protocol". IPsec consists of two protocol: ESP (Encapsulated Security Payload) and AH (Authentication Header). ESP provides encryption of the IP packet, to protect packets from being peeped by bad guys. AH provides authentication of the IP packet, to prevent packets to be modified in transit.

There are two operation modes for IPsec: transport mode and tunnel mode. Transport mode is for endhosts. Endhosts will use transport mode to encrypt/authenticate packets sent from the host itself. Tunnel mode is for security gateways. Security gateways can encrypt/authenticate packets for other hosts in the site. In other word, tunnel mode is for VPN-like configuration.

An accompanying protocol, IKE (Internet Key Exchange protocol) is used for automatic encryption key exchange. This document does not speak about automatic keying, so we do not mention about IKE. (NOTE: IKE was called ISAKMP/Oakley in the past)

What to configure

To configure IPsec connection, you must configure the following items for each of the participating hosts:

SAD: SAD stands for "Security Association Database", and SAD is vital for performing IPsec connection. They provide encryption key, IP src/dst address (or addres range) to be handled by IPsec, encryption algorithm, encryption mode (transport or tunnel), and so forth. SAD entry is identified by an integer number called SPI (Security Parameter Index).
SPD: SPD stands for "Security Policy Database". SPD configures how you should encrypt/authenticate packets toward some other hosts (it defines "security policy" in this context). If SPD suggests encryption or authentication, SAD entry will be looked up and used.

Too many acronyms...

Configuring IPsec between endhosts

Suppose you have KAME-ready laptop (host A), and would like to make a IPsec connection with your KAME-ready desktop in your home (host B). Also assume that you would like to allow non-IPsec connetion to other hosts. If you do not allow this, you will not be able to resolve DNS query (because you must talk with DNS server using non-IPsec connection). We determine whether to use IPsec or not, based on IP address for the IP packet. KAME kit implements per-socket control of policy as well, but for simplicity this example does not use that.

Let us assume that host A is on 10.1.1.1, and host B is on 10.2.2.2. First, set up SAD by using setkey as below, for both hosts:

# setkey -c <<EOF
add 10.1.1.1 10.2.2.2 esp 9998 -E des-cbc "hogehoge" ;
add 10.2.2.2 10.1.1.1 esp 9999 -E des-cbc "hogehoge" ;
EOF

9998 and 9999 are SPI that identifies SAD. This example uses ESP with DES CBC mode, with encryption key "hogehoge" (If you are curious: "hogehoge" is Japanese word for "foobaa").

Next, you must configure SPD, again by using setkey. On 10.1.1.1, you will do the following:

# setkey -c <<EOF
spdadd 10.1.1.1 10.2.2.2 any -P out ipsec esp/transport//use;
EOF

On the other end, you'll do the similar:

# setkey -c <<EOF
spdadd 10.2.2.2 10.1.1.1 any -P out ipsec esp/transport//use;
EOF

The above spdadd lines configure security policy to be used when communicdating with the other end. ipsec esp/transport//use suggests to encrypt packet with transport mode, whenever key is found. The key is manually configured so they are readily available.

Under this configuration, all packets from host A to host B will be encrypted using ESP, with DES CBC mode. All other packets will not be encrypted, and sent as standard IP packet. Special programs may control its own policy by using setsockopt() system call. KAME ping has extra command line option to specify temporary security policy. Also, for inbound traffic, inetd has special support for IPsec.

Proxy ESPing in internet-reachable environment

Next example talks about making secure connection between two sites (organization). Two sites are internet-reachable (not firewalled) in this example. You would like to encrypt traffic between site A and B, not others. Other traffic must be carried by unencrypted IP packets, as usual.

[[[site A]]] ------- host a ===== host b ------- [[[site B]]]
	     bare IP	    IPsec	 bare IP

Suppose you have KAME-ready desktops in each of the site: host a and host b, in site A and site B. We will configure IPsec secure tunnel between host a and b. Any IP traffic that goes through host a and b will be encrypted by using tunnel-mode ESP.

endhost	endhost			endhost	endhost
  |	  |			  |	  |
==+=======+== site A		==+=======+== site B
  |				  |
host a				host b
  |				  |
  +...............................+

Please note that host a and b can be the outgoing router for the sites, but it is not mandatory; if endhosts point the host a/b as its default router, it should be okay. In the following figure, endhost X must point host a as default router. (Note that, however, to run this configuration you need to turn off ICMP redirects on each subnet to keep routing setups on endhost X).

host a	endhost X		host b	endhost Y
  |	  |			  |	  |
==+=======+== site A		==+=======+== site B
  |				  |
router				router
  |				  |
  +...............................+

Let us assume that host a is on 10.1.1.1, and host b is on 10.2.2.2. Site A and B spans over 10.1.1.0/24 and 10.2.2.0/24. First, set up SAD by using setkey as below, for both hosts:

# setkey -c <<EOF
add 10.1.1.1 10.2.2.2 esp 9998 -E des-cbc "hogehoge" ; (**)
add 10.2.2.2 10.1.1.1 esp 9999 -E des-cbc "hogehoge" ; (**)
EOF

The address after SPI (10.2.2.2 in the first line) shows the endpoint for IPsec tunnel. First line means the following:

Packet from 10.1.1.0/24 to 10.2.2.0/24 must be encrypted by using tunnel mode ESP.
SPI must be 9998 and DES CBC algorithm must be used.
Tunnel endpoint is 10.2.2.2 (host b).

Next, you must configure SPD using setkey. On 10.1.1.1:

# setkey -c <<EOF
spdadd 10.1.1.0/24 10.2.2.0/24 any -P ipsec esp/tunnel/10.1.1.1-10.2.2.2/use;
EOF

On the other end:

# setkey -c <<EOF
spdadd 10.2.2.0/24 10.1.1.0/24 any -P ipsec esp/tunnel/10.2.2.2-10.1.1.1/use;
EOF

ipsec esp/tunnel/10.1.1.1-10.2.2.2/use suggests to use tunnel mode IPsec to throw packets toward the other network.

This is because we are configuring tunnel mode ESP, not transport mode ESP. net.inet.ip.forwarding is important, as host a will act as gateway for hosts in site A.

KAME kit restrictions

Currently, KAME project is trying to stabilize/improve our IPsec stack. There are some functionalities that are yet to be implemented. Please check kit/IMPLEMENTATION for more details.