IPSECADM(8)

NAME
ipsecadm - ipsec_tunnel administration

SYNOPSIS
ipsecadm <mode> <command> [options]

DESCRIPTION
ipsecadm is used to add, modify, remove and show IPsec related settings in the Linux kernel.

An SA is a contract between two hosts that defines a set of security parameters that are use when communicating. Every SA defines a security parameter index (SPI) which is a plain 32-bit number. An SA is uniquely identified by a source and a destination IP number and an SPI. Every IPsec packet contains the SPI unencrypted. The receiving IPsec uses the source address, destination address and SPI to know how to handle (e.g. decrypt) the packet.

An IPsec tunnel is a special network device that encrypts packets transmitted through it, and then adds a new IP header to the packet. The source and destination addresses of the new IP header are set when creating the tunnel. After the new IP header is added, the packet is re-routed like any normal packet.

MODES
The first argument to ipsecadm determines the mode of the application, which can be one of the following:

sa
    Add, delete or show security associations (SAs).

tunnel
    Add, modify, delete or show tunnels.

stats
    Show statistics and error counters.

key
    Create keys.

ADDING SECURITY ASSOCIATIONS
To add a new security association (SA), ipsecadm sa add is used.

The following options are recognized:

--dst=destination
    Specifies the IP number used to match the destination of IP packets. This is a required option.

--src=source
    Specifies the IP number used to match the source of IP packets. This is a required option.

--spi=spi
    Specifies the SPI. The SPI is added to outgoing packets, and used to match incoming packets. This is a required option.

--cipher=cipher
    Specifies the name of the cipher to use for this SA. Either this option or the --digest option is required; you may specify both. If you specify this option, you must also specify a key using either the --cipher-key or the --cipher-keyfile option.

--cipher-key=key
    Specifies the cipher key to use as a hexadecimal string. The size of the key depends on the cipher. Note that it is recommended to store the key in a file and use the --cipher-keyfile option instead, since the command line can be visible to ordinary users on the same system.

--cipher-keyfile=file
    Specifies the name of a file containing a binary cipher key.

--digest=digest
    Specifies the name of the digest to use for this SA. Either this option or the --cipher option is required; you may specify both. If you specify this option, you must also specify a key using either the --digest-key or the --digest-keyfile option.

--digest-key=key
    Specifies the digest key to use as a hexadecimal string. The size of the key depends on the digest. Note that it is recommended to store the key in a file and use the --digest-keyfile option instead, since the command line can be visible to ordinary users on the same system.

--digest-keyfile=file
    Specifies the name of a file containing a binary digest key.

--digest-hmac=size
    Specify the number of HMAC bits. The default value is 96 bits.

--duplex
    Create a pair of SAs with the local and remote addresses mirrored.

DELETING SECURITY ASSOCIATIONS
To delete security associations, ipsecadm sa del is used. This command will delete all SAs matching the specified options. In order to delete all SAs, the option --all must be used.

The following options are recognized:

--all
    Delete all SAs.

--dst=destination
    Specifies the IP number used to match the destination of IP packets. This is a required option if --all is not used.

--src=source
    Specifies the IP number used to match the source of IP packets. This is a required option if --all is not used.

--spi=spi
    Specifies the SPI. The SPI is added to outgoing packets, and used to match incoming packets.

--duplex
    Delete a pair of SAs with the local and remote addresses mirrored.

SHOWING SECURITY ASSOCIATIONS
To show information on SAs, ipsecadm sa show is used. The command will show all SAs that match the specified options. If no option is specified, all SAs are shown.

The following options are recognized:

--dst=destination
    Specifies the IP number used to match the destination of IP packets.

--src=source
    Specifies the IP number used to match the source of IP packets.

--spi=spi
    Specifies the SPI. The SPI is added to outgoing packets, and used to match incoming packets.

ADDING TUNNELS
To add a new IPsec tunnel, ipsecadm tunnel add is used. Each tunnel must have a unique combination of local and remote addresses. If either address is omitted it is acting as a wildcard address for incoming packets. It is optional to specify the SPI. If omitted, any SA matching the local and remote address of the packet is used.

The following options are recognized:

--local=local
    Specifies the local IP number. It is used as a source address for the outer IP header when sending packets, and is matched with the destination address of incoming IPsec tunnel packets. If not specified, the inner source address is also used as the outer source address for outgoing packets, and the tunnel will match any destination address of incoming IPsec packets.

--remote=remote
    Specifies the remote IP number. It is used as a destination address for the outer IP header when sending packets, and is matched with the source address of incoming IPsec tunnel packets. If not specified, the inner destination address is also used as the outer destination address for outgoing packets, and the tunnel will match any source address of incoming IPsec packets.

--spi=spi
    Force the use of a certain SPI. If not specified, the SPI of the first SA matching the destination and source addresses is used.

--nextdev=dev
    Specifies the next device for outgoing packets. Use this option to avoid loops when the outer destination address of a packet would cause the packet to be routed to the same IPsec device after encapsulation.

MODIFYING TUNNELS
To modify IPsec tunnels, ipsecadm tunnel modify is used. This command accepts the same options as the ipsecadm tunnel add command.

DELETING TUNNELS
To delete an IPsec tunnel, ipsecadm tunnel del is used. It takes one argument, which is either the name of an IPsec tunnel device, or --all to delete all tunnels.

SHOWING TUNNELS
To show information on a tunnel, ipsecadm tunnel show is used. It takes one optional argument, which is the name of the IPsec tunnel to show. If omitted, all IPsec tunnels will be shown.

SHOWING STATISTICS
To show all ipsec_tunnel statistics, ipsecadm stats show is used. It is a very useful tool to find out the cause of problems with IPsec tunnels.

CREATING KEYS
To create keys used for authentication and encryption, ipsecadm key create is used. This is especially useful when creating DES and 3DES keys which contain parity bits. Creation of weak keys is avoided for most algorithms. The key files are created with the permission bits set to only allow access by the user creating the key. The algorithm for which the key is going to be used is specified by the first argument. The following algorithms are known:

generic
    Generate a generic key of any size. The --bits option must be used to specify the size of the key in bits. No tests are made for weak keys (since the algorithm is unknown).

des
    Generate a DES key. The key size is 64 bits by default, but only 56 bits are used since 8 bits are used for parity bits. Weak keys will not be generated.

3des
    Generate a 3DES (i.e. tripple-DES) key. The key size is 192 bits, but only 168 bits are used since 24 bits are used for parity bits. Weak keys will not be generated.

md5
    Generate an MD5 key. The default key size is 128 bits.

sha1
    Generate an SHA-1 key. The default key size is 160 bits.

The following options are recognized:

--file=filename
    Name of the file where the key is stored. The file must not exist. This is a required option for all algorithms.

--bits=keysize
    Size of the key in bits. This option is required by some algorithms (e.g. generic), but not by all.

EXAMPLES
In the examples below there are two hosts A and B. Host A has the external IP address 1.2.3.4 and a local private network 10.1.1.1/24. Host B has the external IP address 5.6.7.8 and a local private network 10.2.2.1/24. All commands are entered on host A.

Create a 3DES key:

    ipsecadm key create 3des --file=demo.ciph.key

Add two SAs for communication between hosts A and B using SPI 0x1000:

    ipsecadm sa add --src=1.2.3.4 --dst=5.6.7.8 \
        --spi=0x1000 --cipher=3des-cbc \
        --cipher-keyfile=demo.ciph.key \
        --duplex

Show a list of all SAs:

    ipsecadm sa show

Create a tunnel named ipsecB between host A and B:

    ipsecadm tunnel add ipsecB \
        --local=1.2.3.4 --remote=5.6.7.8

Give the new tunnel an IP number:

    ifconfig ipsecB 10.1.1.1 up

Route all traffic to the private network at host B through the IPsec tunnel:

    route add -net 10.2.2.0/24 dev ipsecB

Verify that it works:

    ping 10.2.2.1

Delete the tunnel:

    ipsecadm tunnel del ipsecB

Delete the two SAs:

    ipsecadm sa del --src=1.2.3.4 --dst=5.6.7.8 \
        --spi=0x1000 --duplex

Sometimes you want the outer (new) IP header destination address to be the same as the inner destination address. An example of this occurs when you want to tunnel packets between two hosts on the same network. Let us add the host C with the IP address 1.2.3.5, which is on the same local network as host A. To create a tunnel on host A to host C, you might want to do it like this:

    ipsecadm tunnel add t1 --local=1.2.3.4 \
        --remote=1.2.3.5
    route add -host 1.2.3.5 dev t1

The problem with this approach is that when sending a packet to host C, the routing table will send the packet to t1 which will add the new destination address 1.2.3.5. If we tried to route this packet we would send it back to t1, and we would have a routing loop. Instead, we must specify the next network interface to send the packet to when creating the tunnel:

    ipsecadm tunnel add t1 --local=1.2.3.4 \
        --remote=1.2.3.5 --nextdev=eth0
    route add -host 1.2.3.5 dev t1

This time it works!

DIAGNOSTICS
All commands will hopefully generate meaningful error messages on all possible errors.

BUGS
To be discovered...

AUTHOR
Tobias Ringström <tobias@ringstrom.mine.nu>

CONTRIBUTORS

Norman Shulman <norm@arcturusnetworks.com>
    Authentication support, code review and bug fixes.

SEE ALSO
ifconfig(8), ip(8), route(8)