FreeBSD Handbook
Prev	Chapter 10 Security	Next

10.9 IPsec

Contributed by Yoshinobu Inoue.

Terminating Characters: Throughout examples in this section, and other sections, you will notice that there is a ``^D'' at the end of some examples. This means to hold down the Control key and hit the D key. Another commonly used character is ``^C'', which respectively means to hold down Control and press C.

Tip: For other HOWTOs detailing IPsec implementation in FreeBSD, take a look at http://www.daemonnews.org/200101/ipsec-howto.html and http://www.freebsddiary.org/ipsec.php.

The IPsec mechanism provides secure communication 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 us 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 an 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 us 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 us 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 does not process until security policy entries are 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 the port number field is omitted such as 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

Prev	Home	Next
OpenSSL	Up	OpenSSH