SETKEY(8)

NAME
setkey - manually manipulate the IPsec SA/SP database

SYNOPSIS
setkey [ -dv] -c setkey [ -dv] -f filename setkey [ -adPlv] -D setkey [ -dPv] -F setkey [ -h] -x

DESCRIPTION

setkey adds, updates, dumps, or flushes Security Association Database (SAD) entries as well as Security Policy Database (SPD) entries in the kernel.

setkey takes a series of operations from the standard input (if invoked with -c) or the file named filename (if invoked with -f filename).

-D  Dump the SAD entries. If with -P, the SPD entries are dumped.

-F  Flush the SAD entries. If with -P, the SPD entries are flushed.

-a  setkey usually does not display dead SAD entries with -D. If with -a, the dead SAD entries will be displayed as well. A dead SAD entry means that it has been expired but remains because it is referenced by SPD entries.

-d  Enable to print debugging messages for command parser, without talking to kernel. It is not used usually.

-x  Loop forever and dump all the messages transmitted to PF_KEY socket. -xx makes each timestamps unformatted.

-h  Add hexadecimal dump on -x mode.

-l  Loop forever with short output on -D.

-v  Be verbose. The program will dump messages exchanged on PF_KEY socket, including messages sent from other processes to the kernel.

Operations have the following grammar. Note that lines starting with hashmarks ('#') are treated as comment lines.

add src dst protocol spi extensions algorithm... ;
    Add an SAD entry.

get src dst protocol spi ;
    Show an SAD entry.

delete src dst protocol spi ;
    Remove an SAD entry.

deleteall src dst protocol ;
    Remove all SAD entries that match the specification.

flush protocol ;
    Clear all SAD entries matched by the options.

dump protocol ;
    Dump all SAD entries matched by the options.

spdadd src_range dst_range upperspec policy ;
    Add an SPD entry.

spddelete src_range dst_range upperspec -P direction ;
    Delete an SPD entry.

spdflush ;
    Clear all SPD entries.

spddump ;
    Dump all SPD entries.

Meta-arguments are as follows:

src, dst
    Source/destination of the secure communication is specified as IPv4/v6 address. setkey does not consult hostname-to-address for arguments src and dst. They must be in numeric form.

protocol
    protocol is one of following:

    esp ESP based on rfc2405

    ah  AH based on rfc2402

spi Security Parameter Index (SPI) for the SAD and the SPD. It must be decimal number or hexadecimal number (with 0x attached). You cannot use the set of SPI values in the range 0 through 255.

extensions
    takes some of the following:

    -m mode
        Specify a security protocol mode for use. mode is one of following: transport or tunnel. The default value is transport. NOTE: it is a difference of KAME. Our implemenation does not allow to use single SA both for transport and tunnel mode via IPsec interface. Tunneled frames still can be encapsulated in transport mode SA, provided you use tunnel devices and apply transport mode IPsec to IPIP protocol.

    -r size
        Specify window size of bytes for replay prevention. size must be decimal number in the range 0 ... 32. If size is zero, replay check doesn't take place. If size is not specified, replay window is 32 for AH and authenticated ESP, and disabled for unauthenticated ESP. NOTE: it is a difference of KAME. Default value must be reasonable before all.

    -lh time, -ls time
        Specify hard/soft life time duration of the SA.

algorithm

    -E ealgo key
        Specify an encryption algorithm.

    -A aalgo key
        Specify an authentication algorithm. If -A is used with protocol esp, it will be treated as ESP payload authentication algorithm.
protocol esp accepts -E and -A. protocol ah accepts -A only. key must be double-quoted character string or series of hexadecimal digits. Possible values for ealgo and aalgo are specified in separate section.

src_range,  dst_range
    These are selections of the secure communication specified as IPv4/v6 address or IPv4/v6 address range, and it may accompany TCP/UDP port specification. This takes the following form:

    •   address

    •   address/prefixlen

    •   address[port]

    •   address/prefixlen[port]
prefixlen and port must be decimal numbers. The square bracket around port is really necessary. They are not manpage metacharacters. setkey does not consult hostname-to-address for arguments src and dst. They must be in numeric form.

upperspec
    Upper-layer protocol to be used. You can use one of words in /etc/protocols as upperspec. Or icmp6, ip4, and any can be specified. any stands for any protocol. Also you can use the protocol number. NOTE: upperspec is not advised against forwarding case at this moment, as it requires extra reassembly at forwarding node (not implemented at this moment). We have many protocols in /etc/protocols, but protocols except of TCP, UDP and ICMP may not be suitable to use with IPSec. You have to consider and be careful to use them.

policy
    policy is the one of following:

    •   -P direction discard

    •   -P direction none

    •   -P direction ipsec protocol/mode/src-dst/level
You must specify the direction of its policy as direction. Either out or in or fwd are used. discard means the packet matching indexes will be discarded. none means that IPsec operation will not take place onto the packet. ipsec means that IPsec operation will take place onto the packet. Either ah or esp is to be set as protocol. mode is either transport or tunnel. If mode is tunnel, you must specify the end-points addresses of the SA as src and dst with - between these addresses which is used to specify the SA to use. If mode is transport, both src and dst can be omited. level is to be one of the following: use or require. If the SA is not available in every level, the kernel will request getting SA to the key exchange daemon. use means that the kernel use a SA if it's available, otherwise the kernel keeps normal operation. require means SA is required whenever the kernel sends a packet matched with the policy. Note that discard and none are not in the syntax described in ipsec_set_policy(3). There are little differences in the syntax. See ipsec_set_policy(3) for detail.

ALGORITHMS

The following list shows the supported algorithms. protocol and algorithm are almost orthogonal. Followings are the list of authentication algorithms that can be used as aalgo in -A aalgo of protocol parameter: algorithmkeylen (bits)commenthmac-md5128ah: rfc2403hmac-sha1160ah: rfc2401

Followings are the list of encryption algorithms that can be used as ealgo in -E ealgo of protocol parameter: algorithmkeylen (bits)commentdes-cbc64esp: rfc24053des-cbc192esp: rfc2451

EXAMPLES
add	10.0.11.41 10.0.11.33 esp 123457
		-m tunnel -E des-cbc "ESP SA!!" ;
add	10.0.11.41 10.0.11.33 ah 123456
		-m transport -A hmac-sha1 "AH SA configuration!" ;
add	10.0.11.41 10.0.11.34 esp 0x10001
                -m tunnel
		-E des-cbc "ESP with"
		-A hmac-md5 "authentication!!" ;
get	10.0.11.41 10.0.11.33 ah 123456 ;
flush ;
dump esp ;

Encapsulate output of telnetd in ESP tunnel encrypted with DES and authenticated with MD5.
spdadd	192.168.0.1/32[23] 192.168.0.2/32[any] any
		-P out ipsec esp/tunnel/10.0.11.41-10.0.11.34/require ;

Or alternatively, encapsulate output of telnetd in ESP tunnel encrypted with DES, but with stronger authentication of whole encapsulated packet with MD5.
spdadd	192.168.0.1/32[23] 192.168.0.2/32[any] any
		-P out ipsec
                esp/tunnel/10.0.11.41-10.0.11.33/require
	        ah/transport//require ;

RETURN VALUES

The command exits with 0 on success, and non-zero on errors.

SEE ALSO

ipsec_set_policy(3), racoon(8), sysctl(8)

HISTORY

The setkey command first appeared in WIDE Hydrangea IPv6 protocol stack kit. The command was completely re-designed in June 1998.

This port to Linux was made on November 2002.