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     spddelete [-46n] src_range dst_range upperspec -P direction ;
99             Delete an SPD entry.
100
101     spdflush ;
102             Clear all SPD entries.  -FP on the command line achieves the same
103             functionality.
104
105     spddump ;
106             Dumps all SPD entries.  -DP on the command line achieves the same
107             functionality.
108
109     Meta-arguments are as follows:
110
111     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
122     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
131     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
137     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
176     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
192             key must be a double-quoted character string, or a series of
193             hexadecimal digits preceded by “0x”.
194
195             Possible values for ealgo, aalgo, and calgo are specified in the
196             Algorithms sections.
197
198     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
205             address
206             address/prefixlen
207             address[port]
208             address/prefixlen[port]
209
210             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
215     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
229             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
236     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
251     policy  policy is in one of the following three formats:
252
253           -P direction [priority specification] discard
254           -P direction [priority specification] none
255           -P direction [priority specification] ipsec
256                   protocol/mode/src-dst/level [...]
257
258             You must specify the direction of its policy as direction.
259             Either out, in, or fwd can be used.
260
261             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
269             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
275             {priority,prio} offset
276                      offset is an integer in the range from -2147483647 to
277                      214783648.
278
279             {priority,prio} base {+,-} offset
280                      base is either low (-1073741824), def (0), or high
281                      (1073741824)
282
283                      offset is an unsigned integer.  It can be up to
284                      1073741824 for positive offsets, and up to 1073741823
285                      for negative offsets.
286
287             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
292             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
321             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
328             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
331             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
335             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
339   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
344           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
367     These encryption algorithms can be used as ealgo in -E ealgo of the
368     protocol parameter:
369
370           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           camellia-cbc    128/192/256     rfc4312
382
383     Note that the first 128 bits of a key for aes-ctr will be used as AES
384     key, and the remaining 32 bits will be used as nonce.
385
386     These compression algorithms can be used as calgo in -C calgo of the
387     protocol parameter:
388
389           algorithm
390           deflate         rfc2394
391
392   RFC vs Linux kernel semantics
393     The Linux kernel uses the fwd policy instead of the in policy for packets
394     what are forwarded through that particular box.
395
396     In kernel mode, setkey manages and shows policies and SAs exactly as they
397     are stored in the kernel.
398
399     In RFC mode, setkey
400
401     creates fwd policies for every in policy inserted
402
403     (not implemented yet) filters out all fwd policies
404

RETURN VALUES

406     The command exits with 0 on success, and non-zero on errors.
407

EXAMPLES

409     add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
410             -E des-cbc 0x3ffe05014819ffff ;
411
412     add -6 myhost.example.com yourhost.example.com ah 123456
413             -A hmac-sha1 "AH SA configuration!" ;
414
415     add 10.0.11.41 10.0.11.33 esp 0x10001
416             -E des-cbc 0x3ffe05014819ffff
417             -A hmac-md5 "authentication!!" ;
418
419     get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
420
421     flush ;
422
423     dump esp ;
424
425     spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
426             -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
427
428     add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
429
430     add 10.0.11.41 10.0.11.33 esp 0x10001
431             -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh"
432             -E des-cbc 0x3ffe05014819ffff;
433
434     spdadd 10.0.11.41 10.0.11.33 any
435             -ctx 1 1 "system_u:system_r:unconfined_t:SystemLow-SystemHigh"
436             -P out ipsec esp/transport//require ;
437

SEE ALSO

439     ipsec_set_policy(3), racoon(8), sysctl(8)
440
441     Changed manual key configuration for IPsec, October 1999,
442     http://www.kame.net/newsletter/19991007/.
443

HISTORY

445     The setkey command first appeared in the WIDE Hydrangea IPv6 protocol
446     stack kit.  The command was completely re-designed in June 1998.
447

BUGS

449     setkey should report and handle syntax errors better.
450
451     For IPsec gateway configuration, src_range and dst_range with TCP/UDP
452     port numbers does not work, as the gateway does not reassemble packets
453     (it cannot inspect upper-layer headers).
454
455BSD                             March 19, 2004                             BSD
Impressum