1SETKEY(8) BSD System Manager's Manual SETKEY(8)
2
4 setkey — manually manipulate the IPsec SA/SP database
5
7 setkey [-knrv] file ...
8 setkey [-knrv] -c
9 setkey [-krv] -f filename
10 setkey [-aklPrv] -D
11 setkey [-Pvp] -F
12 setkey [-H] -x
13 setkey [-?V]
14
16 setkey adds, updates, dumps, or flushes Security Association Database
17 (SAD) entries as well as Security Policy Database (SPD) entries in the
18 kernel.
19 setkey takes a series of operations from standard input (if invoked with
21 -c) or the file named filename (if invoked with -f filename).
22 (no flag)
24 Dump the SAD entries or SPD entries contained in the specified
25 file.
26 -? Print short help.
28 -a setkey usually does not display dead SAD entries with -D. If -a
30 is also specified, the dead SAD entries will be displayed as
31 well. A dead SAD entry is one that has expired but remains in
32 the system because it is referenced by some SPD entries.
33 -D Dump the SAD entries. If -P is also specified, the SPD entries
35 are dumped. If -p is specified, the ports are displayed.
36 -F Flush the SAD entries. If -P is also specified, the SPD entries
38 are flushed.
39 -H Add hexadecimal dump in -x mode.
41 -h On NetBSD, synonym for -H. On other systems, synonym for -?.
43 -k Use semantics used in kernel. Available only in Linux. See also
45 -r.
46 -l Loop forever with short output on -D.
48 -n No action. The program will check validity of the input, but no
50 changes to the SPD will be made.
51 -r Use semantics described in IPsec RFCs. This mode is default.
53 For details see section RFC vs Linux kernel semantics. Available
54 only in Linux. See also -k.
55 -x Loop forever and dump all the messages transmitted to the PF_KEY
57 socket. -xx prints the unformatted timestamps.
58 -V Print version string.
60 -v Be verbose. The program will dump messages exchanged on the
62 PF_KEY socket, including messages sent from other processes to
63 the kernel.
64 Configuration syntax
66 With -c or -f on the command line, setkey accepts the following configu‐
67 ration syntax. Lines starting with hash signs (‘#’) are treated as com‐
68 ment lines.
69 add [-46n] src dst protocol spi [extensions] algorithm ... ;
71 Add an SAD entry. add can fail for multiple reasons, including
72 when the key length does not match the specified algorithm.
73 get [-46n] src dst protocol spi ;
75 Show an SAD entry.
76 delete [-46n] src dst protocol spi ;
78 Remove an SAD entry.
79 deleteall [-46n] src dst protocol ;
81 Remove all SAD entries that match the specification.
82 flush [protocol] ;
84 Clear all SAD entries matched by the options. -F on the command
85 line achieves the same functionality.
86 dump [protocol] ;
88 Dumps all SAD entries matched by the options. -D on the command
89 line achieves the same functionality.
90 spdadd [-46n] src_range dst_range upperspec label policy ;
92 Add an SPD entry.
93 spdadd tagged tag policy ;
95 Add an SPD entry based on a PF tag. tag must be a string sur‐
96 rounded by double quotes.
97 spddelete [-46n] src_range dst_range upperspec -P direction ;
99 Delete an SPD entry.
100 spdflush ;
102 Clear all SPD entries. -FP on the command line achieves the same
103 functionality.
104 spddump ;
106 Dumps all SPD entries. -DP on the command line achieves the same
107 functionality.
108 Meta-arguments are as follows:
110 src
112 dst Source/destination of the secure communication is specified as an
113 IPv4/v6 address, and an optional port number between square
114 brackets. setkey can resolve a FQDN into numeric addresses. If
115 the FQDN resolves into multiple addresses, setkey will install
116 multiple SAD/SPD entries into the kernel by trying all possible
117 combinations. -4, -6, and -n restrict the address resolution of
118 FQDN in certain ways. -4 and -6 restrict results into IPv4/v6
119 addresses only, respectively. -n avoids FQDN resolution and
120 requires addresses to be numeric addresses.
121 protocol
123 protocol is one of following:
124 esp ESP based on rfc2406
125 esp-old ESP based on rfc1827
126 ah AH based on rfc2402
127 ah-old AH based on rfc1826
128 ipcomp IPComp
129 tcp TCP-MD5 based on rfc2385
130 spi Security Parameter Index (SPI) for the SAD and the SPD. spi must
132 be a decimal number, or a hexadecimal number with a “0x” prefix.
133 SPI values between 0 and 255 are reserved for future use by IANA
134 and cannot be used. TCP-MD5 associations must use 0x1000 and
135 therefore only have per-host granularity at this time.
136 extensions
138 take some of the following:
139 -m mode Specify a security protocol mode for use. mode is
140 one of following: transport, tunnel, or any. The
141 default value is any.
142 -r size Specify window size of bytes for replay prevention.
143 size must be decimal number in 32-bit word. If size
144 is zero or not specified, replay checks don't take
145 place.
146 -u id Specify the identifier of the policy entry in the
147 SPD. See policy.
148 -f pad_option
149 defines the content of the ESP padding. pad_option
150 is one of following:
151 zero-pad All the paddings are zero.
152 random-pad A series of randomized values are used.
153 seq-pad A series of sequential increasing numbers
154 started from 1 are used.
155 -f nocyclic-seq
156 Don't allow cyclic sequence numbers.
157 -lh time
158 -ls time Specify hard/soft life time duration of the SA mea‐
159 sured in seconds.
160 -bh bytes
161 -bs bytes Specify hard/soft life time duration of the SA mea‐
162 sured in bytes transported.
163 -ctx doi algorithm context-name
164 Specify an access control label. The access control
165 label is interpreted by the LSM (e.g., SELinux).
166 Ultimately, it enables MAC on network communications.
167 doi The domain of interpretation, which is
168 used by the IKE daemon to identify the
169 domain in which negotiation takes place.
170 algorithm Indicates the LSM for which the label is
171 generated (e.g., SELinux).
172 context-name
173 The string representation of the label
174 that is interpreted by the LSM.
175 algorithm
177 -E ealgo key
178 Specify an encryption algorithm ealgo for ESP.
179 -E ealgo key -A aalgo key
180 Specify an encryption algorithm ealgo, as well as a
181 payload authentication algorithm aalgo, for ESP.
182 -A aalgo key
183 Specify an authentication algorithm for AH.
184 -C calgo [-R]
185 Specify a compression algorithm for IPComp. If -R is
186 specified, the spi field value will be used as the
187 IPComp CPI (compression parameter index) on wire as-
188 is. If -R is not specified, the kernel will use
189 well-known CPI on wire, and spi field will be used
190 only as an index for kernel internal usage.
191 key must be a double-quoted character string, or a series of
193 hexadecimal digits preceded by “0x”.
194 Possible values for ealgo, aalgo, and calgo are specified in the
196 Algorithms sections.
197 src_range
199 dst_range
200 These select the communications that should be secured by IPsec.
201 They can be an IPv4/v6 address or an IPv4/v6 address range, and
202 may be accompanied by a TCP/UDP port specification. This takes
203 the following form:
204 address
206 address/prefixlen
207 address[port]
208 address/prefixlen[port]
209 prefixlen and port must be decimal numbers. The square brackets
211 around port are really necessary, they are not man page meta-
212 characters. For FQDN resolution, the rules applicable to src and
213 dst apply here as well.
214 upperspec
216 Upper-layer protocol to be used. You can use one of the words in
217 /etc/protocols as upperspec, or icmp6, ip4, or any. any stands
218 for “any protocol”. You can also use the protocol number. You
219 can specify a type and/or a code of ICMPv6 when the upper-layer
220 protocol is ICMPv6. The specification can be placed after icmp6.
221 A type is separated from a code by single comma. A code must
222 always be specified. When a zero is specified, the kernel deals
223 with it as a wildcard. Note that the kernel can not distinguish
224 a wildcard from an ICPMv6 type of zero. For example, the follow‐
225 ing means that the policy doesn't require IPsec for any inbound
226 Neighbor Solicitation.
227 spdadd ::/0 ::/0 icmp6 135,0 -P in none;
228 Note: upperspec does not work against forwarding case at this
230 moment, as it requires extra reassembly at the forwarding node
231 (not implemented at this moment). There are many protocols in
232 /etc/protocols, but all protocols except of TCP, UDP, and ICMP
233 may not be suitable to use with IPsec. You have to consider
234 carefully what to use.
235 label label is the access control label for the policy. This label is
237 interpreted by the LSM (e.g., SELinux). Ultimately, it enables
238 MAC on network communications. When a policy contains an access
239 control label, SAs negotiated with this policy will contain the
240 label. It's format:
241 -ctx doi algorithm context-name
242 doi The domain of interpretation, which is
243 used by the IKE daemon to identify the
244 domain in which negotiation takes place.
245 algorithm Indicates the LSM for which the label is
246 generated (e.g., SELinux).
247 context-name
248 The string representation of the label
249 that is interpreted by the LSM.
250 policy policy is in one of the following three formats:
252 -P direction [priority specification] discard
254 -P direction [priority specification] none
255 -P direction [priority specification] ipsec
256 protocol/mode/src-dst/level [...]
257 You must specify the direction of its policy as direction.
259 Either out, in, or fwd can be used.
260 priority specification is used to control the placement of the
262 policy within the SPD. Policy position is determined by a signed
263 integer where higher priorities indicate the policy is placed
264 closer to the beginning of the list and lower priorities indicate
265 the policy is placed closer to the end of the list. Policies
266 with equal priorities are added at the end of groups of such
267 policies.
268 Priority can only be specified when setkey has been compiled
270 against kernel headers that support policy priorities (Linux >=
271 2.6.6). If the kernel does not support priorities, a warning
272 message will be printed the first time a priority specification
273 is used. Policy priority takes one of the following formats:
274 {priority,prio} offset
276 offset is an integer in the range from -2147483647 to
277 214783648.
278 {priority,prio} base {+,-} offset
280 base is either low (-1073741824), def (0), or high
281 (1073741824)
282 offset is an unsigned integer. It can be up to
284 1073741824 for positive offsets, and up to 1073741823
285 for negative offsets.
286 discard means the packet matching indexes will be discarded.
288 none means that IPsec operation will not take place onto the
289 packet. ipsec means that IPsec operation will take place onto
290 the packet.
291 The protocol/mode/src-dst/level part specifies the rule how to
293 process the packet. Either ah, esp, or ipcomp must be used as
294 protocol. mode is either transport or tunnel. If mode is
295 tunnel, you must specify the end-point addresses of the SA as src
296 and dst with ‘-’ between these addresses, which is used to spec‐
297 ify the SA to use. If mode is transport, both src and dst can be
298 omitted. level is to be one of the following: default, use,
299 require, or unique. If the SA is not available in every level,
300 the kernel will ask the key exchange daemon to establish a suit‐
301 able SA. default means the kernel consults the system wide
302 default for the protocol you specified, e.g. the esp_trans_deflev
303 sysctl variable, when the kernel processes the packet. use means
304 that the kernel uses an SA if it's available, otherwise the ker‐
305 nel keeps normal operation. require means SA is required when‐
306 ever the kernel sends a packet matched with the policy. unique
307 is the same as require; in addition, it allows the policy to
308 match the unique out-bound SA. You just specify the policy level
309 unique, racoon(8) will configure the SA for the policy. If you
310 configure the SA by manual keying for that policy, you can put a
311 decimal number as the policy identifier after unique separated by
312 a colon ‘:’ like: unique:number in order to bind this policy to
313 the SA. number must be between 1 and 32767. It corresponds to
314 extensions -u of the manual SA configuration. When you want to
315 use SA bundle, you can define multiple rules. For example, if an
316 IP header was followed by an AH header followed by an ESP header
317 followed by an upper layer protocol header, the rule would be:
318 esp/transport//require ah/transport//require;
319 The rule order is very important.
320 When NAT-T is enabled in the kernel, policy matching for ESP over
322 UDP packets may be done on endpoint addresses and port (this
323 depends on the system. System that do not perform the port check
324 cannot support multiple endpoints behind the same NAT). When
325 using ESP over UDP, you can specify port numbers in the endpoint
326 addresses to get the correct matching. Here is an example:
327 spdadd 10.0.11.0/24[any] 10.0.11.33/32[any] any -P out ipsec
329 esp/tunnel/192.168.0.1[4500]-192.168.1.2[30000]/require ;
330 These ports must be left unspecified (which defaults to 0) for
332 anything other than ESP over UDP. They can be displayed in SPD
333 dump using setkey -DPp.
334 Note that “discard” and “none” are not in the syntax described in
336 ipsec_set_policy(3). There are a few differences in the syntax.
337 See ipsec_set_policy(3) for detail.
338 Algorithms
340 The following list shows the supported algorithms. protocol and
341 algorithm are almost orthogonal. These authentication algorithms can be
342 used as aalgo in -A aalgo of the protocol parameter:
343 algorithm keylen (bits)
345 hmac-md5 128 ah: rfc2403
346 128 ah-old: rfc2085
347 hmac-sha1 160 ah: rfc2404
348 160 ah-old: 128bit ICV (no document)
349 keyed-md5 128 ah: 96bit ICV (no document)
350 128 ah-old: rfc1828
351 keyed-sha1 160 ah: 96bit ICV (no document)
352 160 ah-old: 128bit ICV (no document)
353 null 0 to 2048 for debugging
354 hmac-sha256 256 ah: 96bit ICV
355 (draft-ietf-ipsec-ciph-sha-256-00)
356 256 ah-old: 128bit ICV (no document)
357 hmac-sha384 384 ah: 96bit ICV (no document)
358 384 ah-old: 128bit ICV (no document)
359 hmac-sha512 512 ah: 96bit ICV (no document)
360 512 ah-old: 128bit ICV (no document)
361 hmac-ripemd160 160 ah: 96bit ICV (RFC2857)
362 ah-old: 128bit ICV (no document)
363 aes-xcbc-mac 128 ah: 96bit ICV (RFC3566)
364 128 ah-old: 128bit ICV (no document)
365 tcp-md5 8 to 640 tcp: rfc2385
366 These encryption algorithms can be used as ealgo in -E ealgo of the
368 protocol parameter:
369 algorithm keylen (bits)
371 des-cbc 64 esp-old: rfc1829, esp: rfc2405
372 3des-cbc 192 rfc2451
373 null 0 to 2048 rfc2410
374 blowfish-cbc 40 to 448 rfc2451
375 cast128-cbc 40 to 128 rfc2451
376 des-deriv 64 ipsec-ciph-des-derived-01
377 3des-deriv 192 no document
378 rijndael-cbc 128/192/256 rfc3602
379 twofish-cbc 0 to 256 draft-ietf-ipsec-ciph-aes-cbc-01
380 aes-ctr 160/224/288 draft-ietf-ipsec-ciph-aes-ctr-03
381 Note that the first 128 bits of a key for aes-ctr will be used as AES
383 key, and the remaining 32 bits will be used as nonce.
384 These compression algorithms can be used as calgo in -C calgo of the
386 protocol parameter:
387 algorithm
389 deflate rfc2394
390 RFC vs Linux kernel semantics
392 The Linux kernel uses the fwd policy instead of the in policy for packets
393 what are forwarded through that particular box.
394 In kernel mode, setkey manages and shows policies and SAs exactly as they
396 are stored in the kernel.
397 In RFC mode, setkey
399 creates fwd policies for every in policy inserted
401 (not implemented yet) filters out all fwd policies
403
405 The command exits with 0 on success, and non-zero on errors.
406
408 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
409 -E des-cbc 0x3ffe05014819ffff ;
410 add -6 myhost.example.com yourhost.example.com ah 123456
412 -A hmac-sha1 "AH SA configuration!" ;
413 add 10.0.11.41 10.0.11.33 esp 0x10001
415 -E des-cbc 0x3ffe05014819ffff
416 -A hmac-md5 "authentication!!" ;
417 get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
419 flush ;
421 dump esp ;
423 spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
425 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
426 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
428 add 10.0.11.41 10.0.11.33 esp 0x10001
430 -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh"
431 -E des-cbc 0x3ffe05014819ffff;
432 spdadd 10.0.11.41 10.0.11.33 any
434 -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh"
435 -P out ipsec esp/transport//require ;
436
438 ipsec_set_policy(3), racoon(8), sysctl(8)
439 Changed manual key configuration for IPsec, October 1999,
441 http://www.kame.net/newsletter/19991007/.
442
444 The setkey command first appeared in the WIDE Hydrangea IPv6 protocol
445 stack kit. The command was completely re-designed in June 1998.
446
448 setkey should report and handle syntax errors better.
449 For IPsec gateway configuration, src_range and dst_range with TCP/UDP
451 port numbers does not work, as the gateway does not reassemble packets
452 (it cannot inspect upper-layer headers).
453BSD March 19, 2004 BSD