DESCRIPTION

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

(no flag)

Dump the SAD entries or SPD entries contained in the specified
file

-

Print short help.

-a

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

-D

Dump the SAD entries.
If
-P
is also specified, the SPD entries are dumped.
If
-p
is specified, the ports are displayed.

-F

Flush the SAD entries.
If
-P
is also specified, the SPD entries are flushed.

-H

Add hexadecimal dump in
-x
mode.

-h

On
Nx ,
synonym for
-H
On other systems, synonym for
-?

-k

Use semantics used in kernel.
Available only in Linux.
See also
-r

-l

Loop forever with short output on
-D

-n

No action.
The program will check validity of the input, but no changes to
the SPD will be made.

-r

Use semantics described in IPsec RFCs.
This mode is default.
For details see section
Sx RFC vs Linux kernel semantics .
Available only in Linux.
See also
-k

-x

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

-V

Print version string.

-v

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

Configuration syntax

With
-c
or
-f
on the command line,
setkey
accepts the following configuration syntax.
Lines starting with hash signs
(`#'
)
are treated as comment lines.

add
[-46n
]
src dst protocol spi
[extensions
]
algorithm ...;

Add an SAD entry.
add
can fail for multiple reasons, including when the key length does
not match the specified algorithm.

get
[-46n
]
src dst protocol spi;

Show an SAD entry.

delete
[-46n
]
src dst protocol spi;

Remove an SAD entry.

deleteall
[-46n
]
src dst protocol;

Remove all SAD entries that match the specification.

flush
[protocol
]
;

Clear all SAD entries matched by the options.
-F
on the command line achieves the same functionality.

dump
[protocol
]
;

Dumps all SAD entries matched by the options.
-D
on the command line achieves the same functionality.

spdadd
[-46n
]
src_range dst_range upperspec label policy;

Add an SPD entry.

spdadd taggedtag policy;

Add an SPD entry based on a PF tag.
tag
must be a string surrounded by double quotes.

spddelete
[-46n
]
src_range dst_range upperspec -P direction;

Delete an SPD entry.

spdflush;

Clear all SPD entries.
-FP
on the command line achieves the same functionality.

spddump;

Dumps all SPD entries.
-DP
on the command line achieves the same functionality.

Meta-arguments are as follows:

src

dst

Source/destination of the secure communication is specified as
an IPv4/v6 address, and an optional port number between square
brackets.
setkey
can resolve a FQDN into numeric addresses.
If the FQDN resolves into multiple addresses,
setkey
will install multiple SAD/SPD entries into the kernel
by trying all possible combinations.
-4
-6
and
-n
restrict the address resolution of FQDN in certain ways.
-4
and
-6
restrict results into IPv4/v6 addresses only, respectively.
-n
avoids FQDN resolution and requires addresses to be numeric addresses.

protocol

protocol
is one of following:

esp

ESP based on rfc2406

esp-old

ESP based on rfc1827

esp-udp

ESP-UDP based on rfc3948

ah

AH based on rfc2402

ah-old

AH based on rfc1826

ipcomp

IPComp

tcp

TCP-MD5 based on rfc2385

spi

Security Parameter Index
(SPI)
for the SAD and the SPD.
spi
must be a decimal number, or a hexadecimal number with a
``0x
''
prefix.
SPI values between 0 and 255 are reserved for future use by IANA
and cannot be used.
TCP-MD5 associations must use 0x1000 and therefore only have per-host
granularity at this time.

extensions

take some of the following:

-m mode

Specify a security protocol mode for use.
mode
is one of following:
transport , tunnel
or
any
The default value is
any

-r size

Specify window size of bytes for replay prevention.
size
must be decimal number in 32-bit word.
If
size
is zero or not specified, replay checks don't take place.

-u id

Specify the identifier of the policy entry in the SPD.
See
policy

-f pad_option

defines the content of the ESP padding.
pad_option
is one of following:

zero-pad

All the paddings are zero.

random-pad

A series of randomized values are used.

seq-pad

A series of sequential increasing numbers started from 1 are used.

-f nocyclic-seq

Don't allow cyclic sequence numbers.

-lh time

-ls time

Specify hard/soft life time duration of the SA measured in seconds.

-bh bytes

-bs bytes

Specify hard/soft life time duration of the SA measured in bytes transported.

-ctx doi algorithm context-name

Specify an access control label. The access control label is interpreted
by the LSM (e.g., SELinux). Ultimately, it enables MAC on network
communications.

doi

The domain of interpretation, which is used by the
IKE daemon to identify the domain in which negotiation takes place.

algorithm

Indicates the LSM for which the label is generated (e.g., SELinux).

context-name

The string representation of the label that is interpreted by the LSM.

algorithm

-E ealgo key

Specify an encryption algorithm
ealgo
for ESP.

-E ealgo key
-A aalgo key

Specify an encryption algorithm
ealgo
as well as a payload authentication algorithm
aalgo
for ESP.

-A aalgo key

Specify an authentication algorithm for AH.

-C calgo [-R
]

Specify a compression algorithm for IPComp.
If
-R
is specified, the
spi
field value will be used as the IPComp CPI
(compression parameter index)
on wire as-is.
If
-R
is not specified,
the kernel will use well-known CPI on wire, and
spi
field will be used only as an index for kernel internal usage.

key
must be a double-quoted character string, or a series of hexadecimal
digits preceded by
``0x
''

Possible values for
ealgoaalgo
and
calgo
are specified in the
Sx Algorithms
sections.

src_range

dst_range

These select the communications that should be secured by IPsec.
They can be an IPv4/v6 address or an IPv4/v6 address range, and
may be accompanied by a TCP/UDP port specification.
This takes the following form:

addressaddress/prefixlenaddress[port]address/prefixlen[port]

prefixlen
and
port
must be decimal numbers.
The square brackets around
port
are really necessary,
they are not man page meta-characters.
For FQDN resolution, the rules applicable to
src
and
dst
apply here as well.

upperspec

Upper-layer protocol to be used.
You can use one of the words in
/etc/protocols
as
upperspec
or
icmp6ip4
or
anyany
stands for
``any protocol''
You can also use the protocol number.
You can specify a type and/or a code of ICMPv6 when the
upper-layer protocol is ICMPv6.
The specification can be placed after
icmp6
A type is separated from a code by single comma.
A code must always be specified.
When a zero is specified, the kernel deals with it as a wildcard.
Note that the kernel can not distinguish a wildcard from an ICPMv6
type of zero.
For example, the following means that the policy doesn't require IPsec
for any inbound Neighbor Solicitation.

spdadd ::/0 ::/0 icmp6 135,0 -P in none

Noteupperspec
does not work against forwarding case at this moment,
as it requires extra reassembly at the forwarding node
(not implemented at this moment)
There are many protocols in
/etc/protocols
but all protocols except of TCP, UDP, and ICMP may not be suitable
to use with IPsec.
You have to consider carefully what to use.

label

label
is the access control label for the policy. This label is interpreted
by the LSM (e.g., SELinux). Ultimately, it enables MAC on network
communications. When a policy contains an access control label, SAs
negotiated with this policy will contain the label. It's format:

-ctx doi algorithm context-name

doi

The domain of interpretation, which is used by the
IKE daemon to identify the domain in which negotiation takes place.

algorithm

Indicates the LSM for which the label is generated (e.g., SELinux).

context-name

The string representation of the label that is interpreted by the LSM.

You must specify the direction of its policy as
direction
Either
outin
or
fwd
can be used.

priority specification
is used to control the placement of the policy within the SPD.
Policy position is determined by
a signed integer where higher priorities indicate the policy is placed
closer to the beginning of the list and lower priorities indicate the
policy is placed closer to the end of the list.
Policies with equal priorities are added at the end of groups
of such policies.

Priority can only
be specified when setkey has been compiled against kernel headers that
support policy priorities (Linux >= 2.6.6).
If the kernel does not support priorities, a warning message will
be printed the first time a priority specification is used.
Policy priority takes one of the following formats:

{priority,prio} offset

offset

is an integer in the range from -2147483647 to 214783648.

{priority,prio} base {+,-} offset

base

is either
low (-1073741824)def (0)
or
high (1073741824)

offset
is an unsigned integer.
It can be up to 1073741824 for
positive offsets, and up to 1073741823 for negative offsets.

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.

The
protocol/mode/src-dst/level
part specifies the rule how to process the packet.
Either
ahesp
or
ipcomp
must be used as
protocolmode
is either
transport
or
tunnel
If
mode
is
tunnel
you must specify the end-point 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 omitted.
level
is to be one of the following:
default , use , require
or
unique
If the SA is not available in every level, the kernel will
ask the key exchange daemon to establish a suitable SA.
default
means the kernel consults the system wide default for the protocol
you specified, e.g. the
esp_trans_deflev
sysctl variable, when the kernel processes the packet.
use
means that the kernel uses an 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.
unique
is the same as
require
in addition, it allows the policy to match the unique out-bound SA.
You just specify the policy level
uniqueracoon(8)
will configure the SA for the policy.
If you configure the SA by manual keying for that policy,
you can put a decimal number as the policy identifier after
unique
separated by a colon
`:'
like:
unique:number
in order to bind this policy to the SA.
number
must be between 1 and 32767.
It corresponds to
extensions -u
of the manual SA configuration.
When you want to use SA bundle, you can define multiple rules.
For example, if an IP header was followed by an AH header followed
by an ESP header followed by an upper layer protocol header, the
rule would be:

esp/transport//require ah/transport//require

The rule order is very important.

When NAT-T is enabled in the kernel, policy matching for ESP over
UDP packets may be done on endpoint addresses and port
(this depends on the system.
System that do not perform the port check cannot support
multiple endpoints behind the same NAT).
When using ESP over UDP, you can specify port numbers in the endpoint
addresses to get the correct matching.
Here is an example: