| SETKEY(8) | System Manager's Manual | SETKEY(8) |
setkey — manually
manipulate the IPsec SA/SP database
setkey |
[-knrv] file ... |
setkey |
[-knrv] -c |
setkey |
[-krv] -f
filename |
setkey |
[-aklPrv] -D |
setkey |
[-Pvp] -F |
setkey |
[-H] -x |
setkey |
[-?V] |
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
standard input (if invoked with -c) or the file
named filename (if invoked with
-f filename).
-?-asetkey 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-P is also specified, the
SPD entries are dumped. If -p is specified, the
ports are displayed.-F-P is also specified,
the SPD entries are flushed.-H-x mode.-h-H.
On other systems, synonym for -?.-k-r.-l-D.-n-r-k.-xPF_KEY socket. -xx prints
the unformatted timestamps.-V-vPF_KEY socket, including messages sent from other
processes to the kernel.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 can fail for multiple
reasons, including when the key length does not match the specified
algorithm.get
[-46n] src
dst protocol
spi ;delete
[-46n] src
dst protocol
spi ;deleteall
[-46n] src
dst protocol ;flush
[protocol] ;-F
on the command line achieves the same functionality.dump
[protocol] ;-D
on the command line achieves the same functionality.spdadd
[-46n] src_range
dst_range upperspec
policy ;spdadd tagged tag
policy ;spddelete
[-46n] src_range
dst_range upperspec
-P direction ;spdflush
;-FP on the command line
achieves the same functionality.spddump
;-DP on the command line
achieves the same functionality.Meta-arguments are as follows:
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.
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.
-m
modetransport,
tunnel, or any. The
default value is any.-r
size-u
id-f
pad_optionzero-padrandom-padseq-pad-f
nocyclic-seq-lh
time-ls
time-bh
bytes-bs
bytes-E
ealgo key-E
ealgo key
-A aalgo
key-A
aalgo key-C
calgo [-R]-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 ealgo, aalgo, and calgo are specified in the Algorithms sections.
address address/prefixlen address[port] address/prefixlen[port]
prefixlen and port must be a decimal number. The square brackets around port are necessary and are not manpage metacharacters. For FQDN resolution, the rules applicable to src and dst apply here as well.
icmp6, ip4, or
any. any 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 must 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 ICMPv6 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 ;NOTE: upperspec does not work against forwarding case at this moment, as it requires extra reassembly at the forwarding node (currently not implemented). There are many protocols in /etc/protocols, protocols other than TCP, UDP, and ICMP may not be suitable to use with IPsec. You have to consider carefully what to use.
-P
direction [priority specification]
discard-P
direction [priority specification]
none-P
direction [priority specification]
ipsec
protocol/mode/src-dst/level [...]You must specify the direction of its policy as direction. Either out, in, 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:
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
ah, esp, or
ipcomp must be used as
protocol. mode 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
unique,
racoon(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 an 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//requireThe 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:
spdadd 10.0.11.0/24[any] 10.0.11.33/32[any] any -P out ipsec
esp/tunnel/192.168.0.1[4500]-192.168.1.2[30000]/require ;
setkey -DPp.
Note that “discard” and
“none” are not in the syntax
described in
ipsec_set_policy(3).
There are a few differences in the syntax. See
ipsec_set_policy(3) for
detail.
The following list shows the supported algorithms.
protocol
and
algorithm
are almost orthogonal. These authentication algorithms can be used as
aalgo in -A
aalgo of the protocol
parameter:
algorithm keylen (bits) comment hmac-md5 128 ah: rfc2403 128 ah-old: rfc2085 hmac-sha1 160 ah: rfc2404 160 ah-old: 128bit ICV (no document) keyed-md5 128 ah: 96bit ICV (no document) 128 ah-old: rfc1828 keyed-sha1 160 ah: 96bit ICV (no document) 160 ah-old: 128bit ICV (no document) null 0 to 2048 for debugging hmac-sha256 256 ah: 96bit ICV (draft-ietf-ipsec-ciph-sha-256-00) 256 ah-old: 128bit ICV (no document) hmac-sha384 384 ah: 96bit ICV (no document) 384 ah-old: 128bit ICV (no document) hmac-sha512 512 ah: 96bit ICV (no document) 512 ah-old: 128bit ICV (no document) hmac-ripemd160 160 ah: 96bit ICV (RFC2857) ah-old: 128bit ICV (no document) aes-xcbc-mac 128 ah: 96bit ICV (RFC3566) 128 ah-old: 128bit ICV (no document) tcp-md5 8 to 640 tcp: rfc2385
These encryption algorithms can be used as
ealgo in -E
ealgo of the protocol
parameter:
algorithm keylen (bits) comment des-cbc 64 esp-old: rfc1829, esp: rfc2405 3des-cbc 192 rfc2451 null 0 to 2048 rfc2410 blowfish-cbc 40 to 448 rfc2451 cast128-cbc 40 to 128 rfc2451 des-deriv 64 ipsec-ciph-des-derived-01 3des-deriv 192 no document rijndael-cbc 128/192/256 rfc3602 twofish-cbc 0 to 256 draft-ietf-ipsec-ciph-aes-cbc-01 aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03
Note that the first 128 bits of a key for
aes-ctr will be used as AES key, and the remaining
32 bits will be used as nonce.
These compression algorithms can be used as
calgo in -C
calgo of the protocol
parameter:
algorithm comment deflate rfc2394
The Linux kernel uses the fwd policy instead of the in policy for packets what are forwarded through that particular box.
In kernel mode,
setkey manages and shows policies and SAs exactly as
they are stored in the kernel.
In RFC mode, setkey
creates fwd policies for every
in policy inserted
(not implemented yet) filters out all fwd policies
The command exits with 0 on success, and non-zero on errors.
add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457 -E des-cbc 0x3ffe05014819ffff ; add -6 myhost.example.com yourhost.example.com ah 123456 -A hmac-sha1 "AH SA configuration!" ; add 10.0.11.41 10.0.11.33 esp 0x10001 -E des-cbc 0x3ffe05014819ffff -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 ; add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
ipsec_set_policy(3), racoon(8), sysctl(8)
Changed manual key configuration for IPsec, October 1999, http://www.kame.net/newsletter/19991007/.
The setkey command first appeared in the
WIDE Hydrangea IPv6 protocol stack kit. The command was completely
re-designed in June 1998.
setkey should report and handle syntax
errors better.
For IPsec gateway configuration, src_range and dst_range with TCP/UDP port numbers does not work, as the gateway does not reassemble packets (it cannot inspect upper-layer headers).
| March 19, 2004 | macOS 15.0 |