setkey

Manually manipulate the IPsec SA/SP database

Syntax:

setkey [-v] -c 
setkey [-v] -f filename
setkey [-aPlv] -D
setkey [-Pv] -F
setkey [-h] -x

Options:

-a

Also display the dead SAD (Security Association Database) entries. A SAD entry is dead when it has expired, but it may still be referenced by SPD (Security Policy Database) entries.

-c

Specify an operation from standard input. For a list of valid operations, see the "Operations" section, below.

-D

Dump the SAD entries.

When used with:	Also dump:
-a	dead entries
-P	SPD entries

-F

Flush the SAD entries. When specified with -P, also flush the SPD entries.

-f filename

File that contains the operations to be performed. For more information about the valid operations, see the "Operations" section, below.

-h

Dump entries in a hexadecimal format.

-l

Loop forever with short output on -D.

-P

Dump (when specified with -D) or flush (with -F) the SPD entries.

-v

Be verbose. Display messages transmitted to the PF_KEY socket (including messages sent from other processes).

-x

Loop forever and dump all the messages transmitted to the PF_KEY socket.

Description:

The setkey utility adds, updates, dumps, or flushes the Security Association Database (SAD) entries and the Security Policy Database (SPD) entries in the stack.

Operations

The following operations may be specified from either standard input (using -c) or from a file (using -f filename).

Lines that start with hashmarks (#) are treated as comment lines. Operations have the following grammar:

add src dst protocol spi [extensions] algorithm... ;

Add an SAD entry. This operation can fail, for example, if the key length doesn't match the specified algorithm.

delete src dst protocol spi ;

Remove an SAD entry.

dump [protocol] ;

Dump all SAD entries matched by this protocol (same functionality as -D on the command line).

flush [protocol] ;

Clear all SAD entries matched by this protocol (same functionality as -F on the command line).

get src dst protocol spi ;

Show an SAD entry.

spdadd src_range dst_range upperspec policy ;

Add an SPD entry.

spddelete src_range dst_range upperspec -P direction ;

Delete an SPD entry.

spddump ;

Dump all SPD entries (same functionality as -DP on the command line).

spdflush ;

Clear all SPD entries (same functionality as -FP on the command line).

Meta-arguments for operations

The meta-arguments for the operations are as follows:

algorithm

Specify an encryption, authentication, or compression algorithm.

---

See the "Algorithms for protocol " section below for a list of the valid values for aalgo, ealgo and calgo.

---

-A aalgo key

Specify an authentication algorithm (aalgo) for the ah and ah-old protocols.

-E ealgo key

Specify an encryption algorithm (ealgo) for the esp or esp-old protocols.

-E ealgo key -A aalgo key

Specify an encryption algorithm (ealgo) for the esp or esp-old protocols, as well as a payload authentication algorithm (aalgo) for esp.

-C calgo [-R]

Specify a compression algorithm for IPComp (IP Payload Compression Protocol).

If -R is specified, the value of the spi field is used as the IPComp CPI (compression parameter index) field on outgoing packets. The field must be smaller than 0x10000.

If -R isn't specified, the stack uses the IPComp CPI (compression parameter index) from the IPComp CPI field on the packets, and the spi field is ignored.

key

A double-quoted character string or series of hexadecimal digits preceded by 0x.

dst,
src

Specify the destination or source of the secure communication as an IPv4/v6 address. The address must be in numeric form since setkey doesn't consult hostname-to-address for these arguments.

dst_range,
src_range

Selections of the secure communication specified as an IPv4/v6 address or an IPv4/v6 address range. They may accompany TCP/UDP port specifications. Valid forms are:

address
address/prefixlen
address[port]
address/prefixlen[port]
    

The values for prefixlen and port must be specified as a decimal number; src and dst must be expressed in numeric form. The square brackets around port are part of the syntax, they're not optional.

extensions

Valid options are:

-f nocyclic-seq

Don't allow cyclic sequence numbers.

-f pad_option

Specify the content of the esp padding, where pad_option is one of:

• random-pad -- set a series of randomized values.
• seq-pad -- set a series of sequential increasing numbers starting from 1.
• zero-pad -- set everything to zero.

-lh time

Specify a hard lifetime.

-ls time

Specify a soft lifetime.

-m mode

Security protocol mode to be used, which is one of:

• any (the default) -- use whichever security protocol mode is available.
• transport -- protect peer-to-peer communication between end nodes.
• tunnel -- include IP-in-IP encapsulation operations. It's designed for security gateways like VPN configurations.

-r size

The window size, in bytes, for replay prevention. The value of size is a decimal number in a 32-bit word. If size is zero or not specified, replay check doesn't take place.

-u id

Specify the identifier in order to relate the policy with the SA. The value of id must be a decimal number between 1 and 32767.

policy

Takes the form:

-P direction discard
-P direction ipsec request ...
-P direction none
    

See "Setting the policy" in the IPsec protocols page for detailed descriptions of the above arguments.

protocol

Valid options are:

• ah -- AH (Authentication Header) based on RFC 2402.
• ah-old -- AH based on RFC 1826.
• esp -- ESP (Encapsulated Security Payload) based on RFC 2405.
• esp-old -- ESP based on RFC 1827.
• ipcomp -- IPCOMP (IP Payload Compression Protocol).

spi

Security Parameter Index (SPI) for the SAD and the SPD. It's a decimal number, or a hexadecimal number prefixed with 0x. SPI values between the range 0 and 255 are reserved for future use.

upperspec

Specify the upper-layer protocol to use, which is one of:

• any (use any protocol)
• tcp
• udp.

---

Currently, upperspec doesn't work against forwarding.

---

Algorithms for protocol

The following tables show the algorithm to use for each protocol parameter. The protocol and algorithm parameters are almost orthogonal.

Authentication algorithms for aalgo include:

Encryption algorithms for ealgo include:

Compression algorithms for calgo include:

Examples:

add  3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
             -E des-cbc "ESP SA!!" ;

add 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456
            -A hmac-sha1 "AH SA configuration!" ;

add 10.0.11.41 10.0.11.33 esp 0x10001
            -E des-cbc "ESP with"
            -A hmac-md5 "authentication!!" ;

get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;

flush ;

dump esp ;

spdadd  10.0.11.41/32[21] 10.0.11.33/32[any] any
                -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;

Exit status:

0

Success.

>0

An error occurred.

See also:

/etc/inetd.conf, sysctl

IPsec protocol in the Library Reference