[Previous] [Contents] [Index] [Next]

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.
Note: 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:
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:
Note: 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:

Algorithm: Keylen (bits): Comment:
hmac-md5 128 ah: RFC 2403,
ah-old: RFC 2085
hmac-shal 160 ah: RFC 2404,
ah-old: 128bit ICV (no document)
keyed-md5 128 ah: 96bit ICV (no document),
ah-old: RFC 1828
keyed-shal 160 ah: 96bit ICV (no document),
ah-old: 128bit ICV (no document)
null 0 to 2048 for debugging

Encryption algorithms for ealgo include:

Algorithm Keylen (bits) Comment
des-cbc 64 esp-old: RFC 1829,
esp: RFC 2405
3des-cbc 192 RFC 2451
simple 0 to 2048 RFC 2410
blowfish-cbc 40 to 448 RFC 2451
cast128-cbc 40 to 128 RFC 2451
des-deriv 64 ipsec-ciph-des-derived-01 (expired)
des-32iv 64 esp-old: RFC 1829
rijndael-cbc 128/192/256 draft-ietf-ipsec-ciph-aes-cbc-00

Compression algorithms for calgo include:

Algorithm Comment
deflate RFC 2394

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


[Previous] [Contents] [Index] [Next]