1SETKEY(8)                 BSD System Manager's Manual                SETKEY(8)
2

NAME

4     setkey — manually manipulate the IPsec SA/SP database
5

SYNOPSIS

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

DESCRIPTION

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
20     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
23     (no flag)
24             Dump the SAD entries or SPD entries contained in the specified
25             file.
26
27     -?      Print short help.
28
29     -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
34     -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
37     -F      Flush the SAD entries.  If -P is also specified, the SPD entries
38             are flushed.
39
40     -H      Add hexadecimal dump in -x mode.
41
42     -h      On NetBSD, synonym for -H.  On other systems, synonym for -?.
43
44     -k      Use semantics used in kernel.  Available only in Linux.  See also
45             -r.
46
47     -l      Loop forever with short output on -D.
48
49     -n      No action.  The program will check validity of the input, but no
50             changes to the SPD will be made.
51
52     -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
56     -x      Loop forever and dump all the messages transmitted to the PF_KEY
57             socket.  -xx prints the unformatted timestamps.
58
59     -V      Print version string.
60
61     -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
65   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
70     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
74     get [-46n] src dst protocol spi ;
75             Show an SAD entry.
76
77     delete [-46n] src dst protocol spi ;
78             Remove an SAD entry.
79
80     deleteall [-46n] src dst protocol ;
81             Remove all SAD entries that match the specification.
82
83     flush [protocol] ;
84             Clear all SAD entries matched by the options.  -F on the command
85             line achieves the same functionality.
86
87     dump [protocol] ;
88             Dumps all SAD entries matched by the options.  -D on the command
89             line achieves the same functionality.
90
91     spdadd [-46n] src_range dst_range upperspec label policy ;
92             Add an SPD entry.
93
94     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
98     spdupdate [-46n] src_range dst_range upperspec label policy ;
99             Updates an SPD entry.
100
101     spdupdate tagged tag policy ;
102             Update an SPD entry based on a PF tag.  tag must be a string sur‐
103             rounded by double quotes.
104
105     spddelete [-46n] src_range dst_range upperspec -P direction ;
106             Delete an SPD entry.
107
108     spdflush ;
109             Clear all SPD entries.  -FP on the command line achieves the same
110             functionality.
111
112     spddump ;
113             Dumps all SPD entries.  -DP on the command line achieves the same
114             functionality.
115
116     Meta-arguments are as follows:
117
118     src
119     dst     Source/destination of the secure communication is specified as an
120             IPv4/v6 address, and an optional port number between square
121             brackets.  setkey can resolve a FQDN into numeric addresses.  If
122             the FQDN resolves into multiple addresses, setkey will install
123             multiple SAD/SPD entries into the kernel by trying all possible
124             combinations.  -4, -6, and -n restrict the address resolution of
125             FQDN in certain ways.  -4 and -6 restrict results into IPv4/v6
126             addresses only, respectively.  -n avoids FQDN resolution and
127             requires addresses to be numeric addresses.
128
129     protocol
130             protocol is one of following:
131             esp         ESP based on rfc2406
132             esp-old     ESP based on rfc1827
133             ah          AH based on rfc2402
134             ah-old      AH based on rfc1826
135             ipcomp      IPComp
136             tcp         TCP-MD5 based on rfc2385
137
138     spi     Security Parameter Index (SPI) for the SAD and the SPD.  spi must
139             be a decimal number, or a hexadecimal number with a “0x” prefix.
140             SPI values between 0 and 255 are reserved for future use by IANA
141             and cannot be used.  TCP-MD5 associations must use 0x1000 and
142             therefore only have per-host granularity at this time.
143
144     extensions
145             take some of the following:
146             -m mode     Specify a security protocol mode for use.  mode is
147                         one of following: transport, tunnel, or any.  The
148                         default value is any.
149             -r size     Specify window size of bytes for replay prevention.
150                         size must be decimal number in 32-bit word.  If size
151                         is zero or not specified, replay checks don't take
152                         place.
153             -u id       Specify the identifier of the policy entry in the
154                         SPD.  See policy.
155             -f pad_option
156                         defines the content of the ESP padding.  pad_option
157                         is one of following:
158                         zero-pad    All the paddings are zero.
159                         random-pad  A series of randomized values are used.
160                         seq-pad     A series of sequential increasing numbers
161                                     started from 1 are used.
162             -f nocyclic-seq
163                         Don't allow cyclic sequence numbers.
164             -lh time
165             -ls time    Specify hard/soft life time duration of the SA mea‐
166                         sured in seconds.
167             -bh bytes
168             -bs bytes   Specify hard/soft life time duration of the SA mea‐
169                         sured in bytes transported.
170             -ctx doi algorithm context-name
171                         Specify an access control label.  The access control
172                         label is interpreted by the LSM (e.g., SELinux).
173                         Ultimately, it enables MAC on network communications.
174                         doi         The domain of interpretation, which is
175                                     used by the IKE daemon to identify the
176                                     domain in which negotiation takes place.
177                         algorithm   Indicates the LSM for which the label is
178                                     generated (e.g., SELinux).
179                         context-name
180                                     The string representation of the label
181                                     that is interpreted by the LSM.
182
183     algorithm
184             -E ealgo key
185                         Specify an encryption algorithm ealgo for ESP.
186             -E ealgo key -A aalgo key
187                         Specify an encryption algorithm ealgo, as well as a
188                         payload authentication algorithm aalgo, for ESP.
189             -A aalgo key
190                         Specify an authentication algorithm for AH.
191             -C calgo [-R]
192                         Specify a compression algorithm for IPComp.  If -R is
193                         specified, the spi field value will be used as the
194                         IPComp CPI (compression parameter index) on wire as-
195                         is.  If -R is not specified, the kernel will use
196                         well-known CPI on wire, and spi field will be used
197                         only as an index for kernel internal usage.
198
199             key must be a double-quoted character string, or a series of
200             hexadecimal digits preceded by “0x”.
201
202             Possible values for ealgo, aalgo, and calgo are specified in the
203             Algorithms sections.
204
205     src_range
206     dst_range
207             These select the communications that should be secured by IPsec.
208             They can be an IPv4/v6 address or an IPv4/v6 address range, and
209             may be accompanied by a TCP/UDP port specification.  This takes
210             the following form:
211
212             address
213             address/prefixlen
214             address[port]
215             address/prefixlen[port]
216
217             prefixlen and port must be decimal numbers.  The square brackets
218             around port are really necessary, they are not man page meta-
219             characters.  For FQDN resolution, the rules applicable to src and
220             dst apply here as well.
221
222     upperspec
223             Upper-layer protocol to be used.  You can use one of the words in
224             /etc/protocols as upperspec, or icmp6, ip4, gre, or any.  any
225             stands for “any protocol”.  You can also use the protocol number.
226             Additional specification can be placed after the protocol name
227             for some protocols.  You can specify a type and/or a code of ICMP
228             or ICMPv6.  The type is separated from a code by single comma and
229             the code must always be specified.  GRE key can be specified in
230             dotted-quad format or as plain number.  When a zero is specified,
231             the kernel deals with it as a wildcard.  Note that the kernel can
232             not distinguish a wildcard from an ICPMv6 type of zero.
233
234             For example, the following means that the policy doesn't require
235             IPsec for any inbound Neighbor Solicitation.
236                   spdadd ::/0 ::/0 icmp6 135,0 -P in none;
237
238             A second example of requiring transport mode encryption of spe‐
239             cific GRE tunnel:
240                   spdadd 0.0.0.0 0.0.0.0 gre 1234 ipsec
241                   esp/transport//require;
242
243             Note: upperspec does not work against forwarding case at this
244             moment, as it requires extra reassembly at the forwarding node
245             (not implemented at this moment).  There are many protocols in
246             /etc/protocols, but all protocols except of TCP, UDP, GRE, and
247             ICMP may not be suitable to use with IPsec.  You have to consider
248             carefully what to use.
249
250     label   label is the access control label for the policy.  This label is
251             interpreted by the LSM (e.g., SELinux).  Ultimately, it enables
252             MAC on network communications.  When a policy contains an access
253             control label, SAs negotiated with this policy will contain the
254             label.  Its format:
255             -ctx doi algorithm context-name
256                         doi         The domain of interpretation, which is
257                                     used by the IKE daemon to identify the
258                                     domain in which negotiation takes place.
259                         algorithm   Indicates the LSM for which the label is
260                                     generated (e.g., SELinux).
261                         context-name
262                                     The string representation of the label
263                                     that is interpreted by the LSM.
264
265     policy  policy is in one of the following three formats:
266             -P direction [priority specification] discard
267             -P direction [priority specification] none
268             -P direction [priority specification] ipsec
269             protocol/mode/src-dst/level [...]
270
271             You must specify the direction of its policy as direction.
272             Either out, in, or fwd can be used.
273
274             priority specification is used to control the placement of the
275             policy within the SPD.  Policy position is determined by a signed
276             integer where higher priorities indicate the policy is placed
277             closer to the beginning of the list and lower priorities indicate
278             the policy is placed closer to the end of the list.  Policies
279             with equal priorities are added at the end of groups of such
280             policies.
281
282             Priority can only be specified when setkey has been compiled
283             against kernel headers that support policy priorities (Linux >=
284             2.6.6).  If the kernel does not support priorities, a warning
285             message will be printed the first time a priority specification
286             is used.  Policy priority takes one of the following formats:
287
288             {priority,prio} offset
289                      offset is an integer in the range from -2147483647 to
290                      214783648.
291
292             {priority,prio} base {+,-} offset
293                      base is either low (-1073741824), def (0), or high
294                      (1073741824)
295
296                      offset is an unsigned integer.  It can be up to
297                      1073741824 for positive offsets, and up to 1073741823
298                      for negative offsets.
299
300             discard means the packet matching indexes will be discarded.
301             none means that IPsec operation will not take place onto the
302             packet.  ipsec means that IPsec operation will take place onto
303             the packet.
304
305             The protocol/mode/src-dst/level part specifies the rule how to
306             process the packet.  Either ah, esp, or ipcomp must be used as
307             protocol.  mode is either transport or tunnel.  If mode is
308             tunnel, you must specify the end-point addresses of the SA as src
309             and dst with ‘-’ between these addresses, which is used to spec‐
310             ify the SA to use.  If mode is transport, both src and dst can be
311             omitted.  level is to be one of the following: default, use,
312             require, or unique.  If the SA is not available in every level,
313             the kernel will ask the key exchange daemon to establish a suit‐
314             able SA.  default means the kernel consults the system wide
315             default for the protocol you specified, e.g. the esp_trans_deflev
316             sysctl variable, when the kernel processes the packet.  use means
317             that the kernel uses an SA if it's available, otherwise the ker‐
318             nel keeps normal operation.  require means SA is required when‐
319             ever the kernel sends a packet matched with the policy.  unique
320             is the same as require; in addition, it allows the policy to
321             match the unique out-bound SA.  You just specify the policy level
322             unique, racoon(8) will configure the SA for the policy.  If you
323             configure the SA by manual keying for that policy, you can put a
324             decimal number as the policy identifier after unique separated by
325             a colon ‘:’ like: unique:number in order to bind this policy to
326             the SA.  number must be between 1 and 32767.  It corresponds to
327             extensions -u of the manual SA configuration.  When you want to
328             use SA bundle, you can define multiple rules.  For example, if an
329             IP header was followed by an AH header followed by an ESP header
330             followed by an upper layer protocol header, the rule would be:
331                   esp/transport//require ah/transport//require;
332             The rule order is very important.
333
334             When NAT-T is enabled in the kernel, policy matching for ESP over
335             UDP packets may be done on endpoint addresses and port (this
336             depends on the system.  System that do not perform the port check
337             cannot support multiple endpoints behind the same NAT).  When
338             using ESP over UDP, you can specify port numbers in the endpoint
339             addresses to get the correct matching.  Here is an example:
340
341             spdadd 10.0.11.0/24[any] 10.0.11.33/32[any] any -P out ipsec
342                 esp/tunnel/192.168.0.1[4500]-192.168.1.2[30000]/require ;
343
344             These ports must be left unspecified (which defaults to 0) for
345             anything other than ESP over UDP.  They can be displayed in SPD
346             dump using setkey -DPp.
347
348             Note that “discard” and “none” are not in the syntax described in
349             ipsec_set_policy(3).  There are a few differences in the syntax.
350             See ipsec_set_policy(3) for detail.
351
352   Algorithms
353     The following list shows the supported algorithms.  protocol and
354     algorithm are almost orthogonal.  These authentication algorithms can be
355     used as aalgo in -A aalgo of the protocol parameter:
356
357           algorithm       keylen (bits)
358           hmac-md5        128             ah: rfc2403
359                           128             ah-old: rfc2085
360           hmac-sha1       160             ah: rfc2404
361                           160             ah-old: 128bit ICV (no document)
362           keyed-md5       128             ah: 96bit ICV (no document)
363                           128             ah-old: rfc1828
364           keyed-sha1      160             ah: 96bit ICV (no document)
365                           160             ah-old: 128bit ICV (no document)
366           null            0 to 2048       for debugging
367           hmac-sha256     256             ah: 96bit ICV
368                                           (draft-ietf-ipsec-ciph-sha-256-00)
369                           256             ah-old: 128bit ICV (no document)
370           hmac-sha384     384             ah: 96bit ICV (no document)
371                           384             ah-old: 128bit ICV (no document)
372           hmac-sha512     512             ah: 96bit ICV (no document)
373                           512             ah-old: 128bit ICV (no document)
374           hmac-ripemd160  160             ah: 96bit ICV (RFC2857)
375                                           ah-old: 128bit ICV (no document)
376           aes-xcbc-mac    128             ah: 96bit ICV (RFC3566)
377                           128             ah-old: 128bit ICV (no document)
378           tcp-md5         8 to 640        tcp: rfc2385
379
380     These encryption algorithms can be used as ealgo in -E ealgo of the
381     protocol parameter:
382
383           algorithm       keylen (bits)
384           des-cbc         64              esp-old: rfc1829, esp: rfc2405
385           3des-cbc        192             rfc2451
386           null            0 to 2048       rfc2410
387           blowfish-cbc    40 to 448       rfc2451
388           cast128-cbc     40 to 128       rfc2451
389           des-deriv       64              ipsec-ciph-des-derived-01
390           3des-deriv      192             no document
391           rijndael-cbc    128/192/256     rfc3602
392           twofish-cbc     0 to 256        draft-ietf-ipsec-ciph-aes-cbc-01
393           aes-ctr         160/224/288     draft-ietf-ipsec-ciph-aes-ctr-03
394           camellia-cbc    128/192/256     rfc4312
395
396     Note that the first 128 bits of a key for aes-ctr will be used as AES
397     key, and the remaining 32 bits will be used as nonce.
398
399     These compression algorithms can be used as calgo in -C calgo of the
400     protocol parameter:
401
402           algorithm
403           deflate         rfc2394
404
405   RFC vs Linux kernel semantics
406     The Linux kernel uses the fwd policy instead of the in policy for packets
407     what are forwarded through that particular box.
408
409     In kernel mode, setkey manages and shows policies and SAs exactly as they
410     are stored in the kernel.
411
412     In RFC mode, setkey
413
414     creates fwd policies for every in policy inserted
415
416     (not implemented yet) filters out all fwd policies
417

RETURN VALUES

419     The command exits with 0 on success, and non-zero on errors.
420

EXAMPLES

422     add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
423             -E des-cbc 0x3ffe05014819ffff ;
424
425     add -6 myhost.example.com yourhost.example.com ah 123456
426             -A hmac-sha1 "AH SA configuration!" ;
427
428     add 10.0.11.41 10.0.11.33 esp 0x10001
429             -E des-cbc 0x3ffe05014819ffff
430             -A hmac-md5 "authentication!!" ;
431
432     get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
433
434     flush ;
435
436     dump esp ;
437
438     spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
439             -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
440
441     add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
442
443     add 10.0.11.41 10.0.11.33 esp 0x10001
444             -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh"
445             -E des-cbc 0x3ffe05014819ffff;
446
447     spdadd 10.0.11.41 10.0.11.33 any
448             -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh"
449             -P out ipsec esp/transport//require ;
450

SEE ALSO

452     ipsec_set_policy(3), racoon(8), sysctl(8)
453
454     Changed manual key configuration for IPsec,
455     http://www.kame.net/newsletter/19991007/, October 1999.
456

HISTORY

458     The setkey command first appeared in the WIDE Hydrangea IPv6 protocol
459     stack kit.  The command was completely re-designed in June 1998.
460

BUGS

462     setkey should report and handle syntax errors better.
463
464     For IPsec gateway configuration, src_range and dst_range with TCP/UDP
465     port numbers does not work, as the gateway does not reassemble packets
466     (it cannot inspect upper-layer headers).
467
468BSD                              June 4, 2010                              BSD
Impressum