10.9. IPsec

Contributed by Yoshinobu Inoue , 5 March 2000.

The IPsec mechanism provides secure communication either for IP layer and socket layer communication. This section should explain how to use them. For implementation details, please refer to The Developers' Handbook.

The current IPsec implementation supports both transport mode and tunnel mode. However, tunnel mode comes with some restrictions. http://www.kame.net/newsletter/ has more comprehensive examples.

Please be aware that in order to use this functionality, you must have the following options compiled into your kernel:

    options          IPSEC              #IP security
    options          IPSEC_ESP          #IP security (crypto; define w/IPSEC)

10.9.1. Transport mode example with IPv4

Let's setup security association to deploy a secure channel between HOST A (10.2.3.4) and HOST B (10.6.7.8). Here we show a little complicated example. From HOST A to HOST B, only old AH is used. From HOST B to HOST A, new AH and new ESP are combined.

Now we should choose algorithm to be used corresponding to "AH"/"new AH"/"ESP"/"new ESP". Please refer to the setkey(8) man page to know algorithm names. Our choice is MD5 for AH, new-HMAC-SHA1 for new AH, and new-DES-expIV with 8 byte IV for new ESP.

Key length highly depends on each algorithm. For example, key length must be equal to 16 bytes for MD5, 20 for new-HMAC-SHA1, and 8 for new-DES-expIV. Now we choose "MYSECRETMYSECRET", "KAMEKAMEKAMEKAMEKAME", "PASSWORD", respectively.

OK, let's assign SPI (Security Parameter Index) for each protocol. Please note that we need 3 SPIs for this secure channel since three security headers are produced (one for from HOST A to HOST B, two for from HOST B to HOST A). Please also note that SPI MUST be greater than or equal to 256. We choose, 1000, 2000, and 3000, respectively.

    	         (1)
    	HOST A ------> HOST B
    
    	(1)PROTO=AH
    		ALG=MD5(RFC1826)
    		KEY=MYSECRETMYSECRET
    		SPI=1000
    
    	         (2.1)
    	HOST A <------ HOST B
    	       <------
    	         (2.2)
    
    	(2.1)
    	PROTO=AH
    		ALG=new-HMAC-SHA1(new AH)
    		KEY=KAMEKAMEKAMEKAMEKAME
    		SPI=2000
    
    	(2.2)
    	PROTO=ESP
    		ALG=new-DES-expIV(new ESP)
    			IV length = 8
    		KEY=PASSWORD
    		SPI=3000

Now, let's setup security association. Execute setkey(8) on both HOST A and B:

    # setkey -c
    add 10.2.3.4 10.6.7.8 ah-old  1000 -m transport -A keyed-md5 "MYSECRETMYSECRET" ;
    add 10.6.7.8 10.2.3.4 ah  2000 -m transport -A hmac-sha1 "KAMEKAMEKAMEKAMEKAME" ;
    add 10.6.7.8 10.2.3.4 esp 3000 -m transport -E des-cbc "PASSWORD" ;
    ^D

Actually, IPsec communication doesn't process until security policy entries will be defined. In this case, you must setup each host.

    At A:
    
    # setkey -c
    spdadd 10.2.3.4 10.6.7.8 any -P out ipsec
    	ah/transport/10.2.3.4-10.6.7.8/require ;
    ^D
    
    At B:
    
    # setkey -c
    spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
    	esp/transport/10.6.7.8-10.2.3.4/require ;
    spdadd 10.6.7.8 10.2.3.4 any -P out ipsec
    	ah/transport/10.6.7.8-10.2.3.4/require ;
    ^D
    
    
       HOST A --------------------------------------> HOST E
      10.2.3.4                                       10.6.7.8
              |                                     |
              ========== old AH keyed-md5 ==========>
    
              <========= new AH hmac-sha1 ===========
              <========= new ESP des-cbc ============

10.9.2. Transport mode example with IPv6

Another example using IPv6.

ESP transport mode is recommended for TCP port number 110 between Host-A and Host-B.

                  ============ ESP ============
                  |                           |
               Host-A                        Host-B
              fec0::10 -------------------- fec0::11

Encryption algorithm is blowfish-cbc whose key is "kamekame", and authentication algorithm is hmac-sha1 whose key is "this is the test key". Configuration at Host-A:

            # setkey -c <<EOF
            spdadd fec0::10[any] fec0::11[110] tcp -P out ipsec
                    esp/transport/fec0::10-fec0::11/use ;
            spdadd fec0::11[110] fec0::10[any] tcp -P in ipsec
                    esp/transport/fec0::11-fec0::10/use ;
            add fec0::10 fec0::11 esp 0x10001
                    -m transport
                    -E blowfish-cbc "kamekame"
                    -A hmac-sha1 "this is the test key" ;
            add fec0::11 fec0::10 esp 0x10002
                    -m transport
                    -E blowfish-cbc "kamekame"
                    -A hmac-sha1 "this is the test key" ;
            EOF

and at Host-B:

    # setkey -c <<EOF
            spdadd fec0::11[110] fec0::10[any] tcp -P out ipsec
                    esp/transport/fec0::11-fec0::10/use ;
            spdadd fec0::10[any] fec0::11[110] tcp -P in ipsec
                    esp/transport/fec0::10-fec0::11/use ;
            add fec0::10 fec0::11 esp 0x10001 -m transport
                    -E blowfish-cbc "kamekame"
                    -A hmac-sha1 "this is the test key" ;
            add fec0::11 fec0::10 esp 0x10002 -m transport
                    -E blowfish-cbc "kamekame"
                    -A hmac-sha1 "this is the test key" ;
            EOF

Note the direction of SP.

10.9.3. Tunnel mode example with IPv4

Tunnel mode between two security gateways

Security protocol is old AH tunnel mode, i.e. specified by RFC1826, with keyed-md5 whose key is "this is the test" as authentication algorithm.

                                 ======= AH =======
                                 |                |
             Network-A       Gateway-A        Gateway-B        Network-B
            10.0.1.0/24 ---- 172.16.0.1 ----- 172.16.0.2 ---- 10.0.2.0/24

Configuration at Gateway-A:

            # setkey -c <<EOF
            spdadd 10.0.1.0/24 10.0.2.0/24 any -P out ipsec
                    ah/tunnel/172.16.0.1-172.16.0.2/require ;
            spdadd 10.0.2.0/24 10.0.1.0/24 any -P in ipsec
                    ah/tunnel/172.16.0.2-172.16.0.1/require ;
            add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
                    -A keyed-md5 "this is the test" ;
            add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
                    -A keyed-md5 "this is the test" ;
    
            EOF

If port number field is omitted such above then "[any]" is employed. `-m' specifies the mode of SA to be used. "-m any" means wild-card of mode of security protocol. You can use this SA for both tunnel and transport mode.

and at Gateway-B:

            # setkey -c <<EOF
            spdadd 10.0.2.0/24 10.0.1.0/24 any -P out ipsec
                    ah/tunnel/172.16.0.2-172.16.0.1/require ;
            spdadd 10.0.1.0/24 10.0.2.0/24 any -P in ipsec
                    ah/tunnel/172.16.0.1-172.16.0.2/require ;
            add 172.16.0.1 172.16.0.2 ah-old 0x10003 -m any
                    -A keyed-md5 "this is the test" ;
            add 172.16.0.2 172.16.0.1 ah-old 0x10004 -m any
                    -A keyed-md5 "this is the test" ;
    
            EOF

Making SA bundle between two security gateways

AH transport mode and ESP tunnel mode is required between Gateway-A and Gateway-B. In this case, ESP tunnel mode is applied first, and AH transport mode is next.

                                ========== AH =========
                                |  ======= ESP =====  |
                                |  |               |  |
           Network-A          Gateway-A        Gateway-B           Network-B
        fec0:0:0:1::/64 --- fec0:0:0:1::1 ---- fec0:0:0:2::1 --- fec0:0:0:2::/64

10.9.4. Tunnel mode example with IPv6

Encryption algorithm is 3des-cbc, and authentication algorithm for ESP is hmac-sha1. Authentication algorithm for AH is hmac-md5. Configuration at Gateway-A:

            # setkey -c <<EOF
            spdadd fec0:0:0:1::/64 fec0:0:0:2::/64 any -P out ipsec
                    esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require
                    ah/transport/fec0:0:0:1::1-fec0:0:0:2::1/require ;
            spdadd fec0:0:0:2::/64 fec0:0:0:1::/64 any -P in ipsec
                    esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require
                    ah/transport/fec0:0:0:2::1-fec0:0:0:1::1/require ;
            add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10001 -m tunnel
                    -E 3des-cbc "kamekame12341234kame1234"
                    -A hmac-sha1 "this is the test key" ;
            add fec0:0:0:1::1 fec0:0:0:2::1 ah 0x10001 -m transport
                    -A hmac-md5 "this is the test" ;
            add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10001 -m tunnel
                    -E 3des-cbc "kamekame12341234kame1234"
                    -A hmac-sha1 "this is the test key" ;
            add fec0:0:0:2::1 fec0:0:0:1::1 ah 0x10001 -m transport
                    -A hmac-md5 "this is the test" ;
    
            EOF

Making SAs with the different end

ESP tunnel mode is required between Host-A and Gateway-A. Encryption algorithm is cast128-cbc, and authentication algorithm for ESP is hmac-sha1. ESP transport mode is recommended between Host-A and Host-B. Encryption algorithm is rc5-cbc, and authentication algorithm for ESP is hmac-md5.

                  ================== ESP =================
                  |  ======= ESP =======                 |
                  |  |                 |                 |
                 Host-A            Gateway-A           Host-B
              fec0:0:0:1::1 ---- fec0:0:0:2::1 ---- fec0:0:0:2::2

Configuration at Host-A:

            # setkey -c <<EOF
            spdadd fec0:0:0:1::1[any] fec0:0:0:2::2[80] tcp -P out ipsec
                    esp/transport/fec0:0:0:1::1-fec0:0:0:2::2/use
                    esp/tunnel/fec0:0:0:1::1-fec0:0:0:2::1/require ;
            spdadd fec0:0:0:2::1[80] fec0:0:0:1::1[any] tcp -P in ipsec
                    esp/transport/fec0:0:0:2::2-fec0:0:0:l::1/use
                    esp/tunnel/fec0:0:0:2::1-fec0:0:0:1::1/require ;
            add fec0:0:0:1::1 fec0:0:0:2::2 esp 0x10001
                    -m transport
                    -E cast128-cbc "12341234"
                    -A hmac-sha1 "this is the test key" ;
            add fec0:0:0:1::1 fec0:0:0:2::1 esp 0x10002
                    -E rc5-cbc "kamekame"
                    -A hmac-md5 "this is the test" ;
            add fec0:0:0:2::2 fec0:0:0:1::1 esp 0x10003
                    -m transport
                    -E cast128-cbc "12341234"
                    -A hmac-sha1 "this is the test key" ;
            add fec0:0:0:2::1 fec0:0:0:1::1 esp 0x10004
                    -E rc5-cbc "kamekame"
                    -A hmac-md5 "this is the test" ;
    
            EOF