b72db79157c7d7687eb8bc94fdda22d5753f5167
[dragonfly.git] / usr.sbin / setkey / setkey.8
1 .\"     $KAME: setkey.8,v 1.49 2001/05/18 05:49:51 sakane Exp $
2 .\"     $FreeBSD: src/usr.sbin/setkey/setkey.8,v 1.4.2.15 2003/03/12 22:08:15 trhodes Exp $
3 .\"     $DragonFly: src/usr.sbin/setkey/setkey.8,v 1.7 2008/08/10 21:29:17 hasso Exp $
4 .\"
5 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
6 .\" All rights reserved.
7 .\"
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
10 .\" are met:
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\"    notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\"    notice, this list of conditions and the following disclaimer in the
15 .\"    documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the project nor the names of its contributors
17 .\"    may be used to endorse or promote products derived from this software
18 .\"    without specific prior written permission.
19 .\"
20 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" SUCH DAMAGE.
31 .\"
32 .Dd November 20, 2000
33 .Dt SETKEY 8
34 .Os
35 .\"
36 .Sh NAME
37 .Nm setkey
38 .Nd "manually manipulate the IPsec SA/SP database"
39 .\"
40 .Sh SYNOPSIS
41 .Nm
42 .Op Fl dv
43 .Fl c
44 .Nm
45 .Op Fl dv
46 .Fl f Ar filename
47 .Nm
48 .Op Fl adPlv
49 .Fl D
50 .Nm
51 .Op Fl dPv
52 .Fl F
53 .Nm
54 .Op Fl h
55 .Fl x
56 .\"
57 .Sh DESCRIPTION
58 The
59 .Nm
60 utility adds, updates, dumps, or flushes
61 Security Association Database (SAD) entries
62 as well as Security Policy Database (SPD) entries in the kernel.
63 .Pp
64 The
65 .Nm
66 utility takes a series of operations from the standard input
67 (if invoked with
68 .Fl c )
69 or the file named
70 .Ar filename
71 (if invoked with
72 .Fl f Ar filename ) .
73 .Bl -tag -width Ds
74 .It Fl D
75 Dump the SAD entries.
76 If with
77 .Fl P ,
78 the SPD entries are dumped.
79 .It Fl F
80 Flush the SAD entries.
81 If with
82 .Fl P ,
83 the SPD entries are flushed.
84 .It Fl a
85 Dead SAD entries are usually not displayed with
86 .Fl D .
87 If with
88 .Fl a ,
89 the dead SAD entries will be displayed as well.
90 A dead SAD entry means that
91 it has been expired but remains
92 because it is referenced by SPD entries.
93 .It Fl d
94 Enable to print debugging messages for command parser,
95 without talking to kernel.
96 It is not used usually.
97 .It Fl x
98 Loop forever and dump all the messages transmitted to
99 .Dv PF_KEY
100 socket.
101 .Fl xx
102 makes each timestamp unformatted.
103 .It Fl h
104 Add hexadecimal dump on
105 .Fl x
106 mode.
107 .It Fl l
108 Loop forever with short output on
109 .Fl D .
110 .It Fl v
111 Be verbose.
112 The program will dump messages exchanged on
113 .Dv PF_KEY
114 socket, including messages sent from other processes to the kernel.
115 .El
116 .Pp
117 Operations have the following grammar.
118 Note that lines starting with
119 hashmarks ('#') are treated as comment lines.
120 .Bl -tag -width Ds
121 .It Xo
122 .Li add
123 .Ar src Ar dst Ar protocol Ar spi
124 .Op Ar extensions
125 .Ar algorithm...
126 .Li ;
127 .Xc
128 Add an SAD entry.
129 .\"
130 .It Xo
131 .Li get
132 .Ar src Ar dst Ar protocol Ar spi
133 .Li ;
134 .Xc
135 Show an SAD entry.
136 .\"
137 .It Xo
138 .Li delete
139 .Ar src Ar dst Ar protocol Ar spi
140 .Li ;
141 .Xc
142 Remove an SAD entry.
143 .\"
144 .It Xo
145 .Li deleteall
146 .Ar src Ar dst Ar protocol
147 .Li ;
148 .Xc
149 Remove all SAD entries that match the specification.
150 .\"
151 .It Xo
152 .Li flush
153 .Op Ar protocol
154 .Li ;
155 .Xc
156 Clear all SAD entries matched by the options.
157 .\"
158 .It Xo
159 .Li dump
160 .Op Ar protocol
161 .Li ;
162 .Xc
163 Dumps all SAD entries matched by the options.
164 .\"
165 .It Xo
166 .Li spdadd
167 .Ar src_range Ar dst_range Ar upperspec Ar policy
168 .Li ;
169 .Xc
170 Add an SPD entry.
171 .\"
172 .It Xo
173 .Li spddelete
174 .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
175 .Li ;
176 .Xc
177 Delete an SPD entry.
178 .\"
179 .It Xo
180 .Li spdflush
181 .Li ;
182 .Xc
183 Clear all SPD entries.
184 .\"
185 .It Xo
186 .Li spddump
187 .Li ;
188 .Xc
189 Dumps all SPD entries.
190 .El
191 .\"
192 .Pp
193 Meta-arguments are as follows:
194 .Pp
195 .Bl -tag -compact -width Ds
196 .It Ar src
197 .It Ar dst
198 Source/destination of the secure communication is specified as
199 IPv4/v6 address.
200 The
201 .Nm
202 utility does not consult hostname-to-address for arguments
203 .Ar src
204 and
205 .Ar dst .
206 They must be in numeric form.
207 .\"
208 .Pp
209 .It Ar protocol
210 .Ar protocol
211 is one of following:
212 .Bl -tag -width Fl -compact
213 .It Li esp
214 ESP based on rfc2405
215 .It Li esp-old
216 ESP based on rfc1827
217 .It Li ah
218 AH based on rfc2402
219 .It Li ah-old
220 AH based on rfc1826
221 .It Li ipcomp
222 IPCOMP
223 .It Li tcp
224 TCP-MD5 based on rfc2385
225 .El
226 .\"
227 .Pp
228 .It Ar spi
229 Security Parameter Index (SPI) for the SAD and the SPD.
230 It must be decimal number or hexadecimal number
231 You cannot use the set of SPI values in the range 0 through 255.
232 (with
233 .Li 0x
234 attached).
235 TCP-MD5 associations must use 0x1000 and therefore only have per-host
236 granularity at this time.
237 .\"
238 .Pp
239 .It Ar extensions
240 takes some of the following:
241 .Bl -tag -width Fl -compact
242 .\"
243 .It Fl m Ar mode
244 Specify a security protocol mode for use.
245 .Ar mode
246 is one of following:
247 .Li transport , tunnel
248 or
249 .Li any .
250 The default value is
251 .Li any .
252 .\"
253 .It Fl r Ar size
254 Specify window size of bytes for replay prevention.
255 .Ar size
256 must be decimal number in 32-bit word.
257 If
258 .Ar size
259 is zero or not specified, replay check don't take place.
260 .\"
261 .It Fl u Ar id
262 Specify the identifier of the policy entry in SPD.
263 See
264 .Ar policy .
265 .\"
266 .It Fl f Ar pad_option
267 defines the content of the ESP padding.
268 .Ar pad_option
269 is one of following:
270 .Bl -tag -width random-pad -compact
271 .It Li zero-pad
272 All of the padding are zero.
273 .It Li random-pad
274 A series of randomized values are set.
275 .It Li seq-pad
276 A series of sequential increasing numbers started from 1 are set.
277 .El
278 .\"
279 .It Fl f Li nocyclic-seq
280 Don't allow cyclic sequence number.
281 .\"
282 .It Fl lh Ar time
283 .It Fl ls Ar time
284 Specify hard/soft life time duration of the SA.
285 .El
286 .\"
287 .Pp
288 .It Ar algorithm
289 .Bl -tag -width Fl -compact
290 .It Fl E Ar ealgo Ar key
291 Specify an encryption algorithm.
292 .It Fl A Ar aalgo Ar key
293 Specify an authentication algorithm.
294 If
295 .Fl A
296 is used with
297 .Ar protocol Li esp ,
298 it will be treated as ESP payload authentication algorithm.
299 .It Fl C Ar calgo Op Fl R
300 Specify compression algorithm.
301 If
302 .Fl R
303 is not specified with
304 .Li ipcomp
305 line, the kernel will use well-known IPComp CPI
306 (compression parameter index)
307 on IPComp CPI field on packets, and
308 .Ar spi
309 field will be ignored.
310 .Ar spi
311 field is only for kernel internal use in this case.
312 .\"Therefore, compression protocol number will appear on IPComp CPI field.
313 If
314 .Fl R
315 is used,
316 the value on
317 .Ar spi
318 field will appear on IPComp CPI field on outgoing packets.
319 .Ar spi
320 field needs to be smaller than
321 .Li 0x10000
322 in this case.
323 .El
324 .Pp
325 .Ar protocol Li esp
326 accepts
327 .Fl E
328 and
329 .Fl A .
330 .Ar protocol Li esp-old
331 accepts
332 .Fl E
333 only.
334 .Ar protocol Li ah
335 and
336 .Li ah-old
337 accept
338 .Fl A
339 only.
340 .Ar protocol Li ipcomp
341 accepts
342 .Fl C
343 only.
344 .Pp
345 .Ar key
346 must be double-quoted character string or series of hexadecimal digits.
347 .Pp
348 Possible values for
349 .Ar ealgo ,
350 .Ar aalgo
351 and
352 .Ar calgo
353 are specified in separate section.
354 .\"
355 .Pp
356 .It Ar src_range
357 .It Ar dst_range
358 These are selections of the secure communication specified as
359 IPv4/v6 address or IPv4/v6 address range, and it may accompany
360 TCP/UDP port specification.
361 This takes the following form:
362 .Bd -literal -offset
363 .Ar address
364 .Ar address/prefixlen
365 .Ar address[port]
366 .Ar address/prefixlen[port]
367 .Ed
368 .Pp
369 .Ar prefixlen
370 and
371 .Ar port
372 must be decimal number.
373 The square bracket around
374 .Ar port
375 is really necessary.
376 They are not manpage metacharacters.
377 .Pp
378 The
379 .Nm
380 utility does not consult hostname-to-address for arguments
381 .Ar src
382 and
383 .Ar dst .
384 They must be in numeric form.
385 .\"
386 .Pp
387 .It Ar upperspec
388 Upper-layer protocol to be used.
389 You can use one of words in
390 .Pa /etc/protocols
391 as
392 .Ar upperspec .
393 Or
394 .Li icmp6 ,
395 .Li ip4 ,
396 and
397 .Li any
398 can be specified.
399 .Li any
400 stands for
401 .Dq any protocol .
402 Also you can use the protocol number.
403 .Pp
404 NOTE:
405 .Ar upperspec
406 does not work against forwarding case at this moment,
407 as it requires extra reassembly at forwarding node
408 (not implemented at this moment).
409 We have many protocols in
410 .Pa /etc/protocols ,
411 but protocols except of TCP, UDP and ICMP may not be suitable to use with IPsec.
412 You have to consider and be careful to use them.
413 .Li icmp
414 .Li tcp
415 .Li udp
416 all protocols
417 .\"
418 .Pp
419 .It Ar policy
420 .Ar policy
421 is the one of following:
422 .Bd -literal -offset
423 .Xo
424 .Fl P Ar direction Li discard
425 .Xc
426 .Xo
427 .Fl P Ar direction Li none
428 .Xc
429 .Xo
430 .Fl P Ar direction Li ipsec Ar protocol/mode/src-dst/level
431 .Xc
432 .Ed
433 .Pp
434 You must specify the direction of its policy as
435 .Ar direction .
436 Either
437 .Li out
438 or
439 .Li in
440 are used.
441 .Li discard
442 means the packet matching indexes will be discarded.
443 .Li none
444 means that IPsec operation will not take place onto the packet.
445 .Li ipsec
446 means that IPsec operation will take place onto the packet.
447 Either
448 .Li ah ,
449 .Li esp
450 or
451 .Li ipcomp
452 is to be set as
453 .Ar protocol .
454 .Ar mode
455 is either
456 .Li transport
457 or
458 .Li tunnel .
459 If
460 .Ar mode
461 is
462 .Li tunnel ,
463 you must specify the end-points addresses of the SA as
464 .Ar src
465 and
466 .Ar dst
467 with
468 .Sq -
469 between these addresses which is used to specify the SA to use.
470 If
471 .Ar mode
472 is
473 .Li transport ,
474 both
475 .Ar src
476 and
477 .Ar dst
478 can be omitted.
479 .Ar level
480 is to be one of the following:
481 .Li default , use , require
482 or
483 .Li unique .
484 If the SA is not available in every level, the kernel will request
485 getting SA to the key exchange daemon.
486 .Li default
487 means the kernel consults to the system wide default against protocol you
488 specified, e.g.\&
489 .Li esp_trans_deflev
490 sysctl variable, when the kernel processes the packet.
491 .Li use
492 means that the kernel use a SA if it's available,
493 otherwise the kernel keeps normal operation.
494 .Li require
495 means SA is required whenever the kernel sends a packet matched
496 with the policy.
497 .Li unique
498 is the same to require.
499 In addition, it allows the policy to bind with the unique out-bound SA.
500 If you use the SA by manual keying,
501 you can put the decimal number as the policy identifier after
502 .Li unique
503 separated by colon
504 .Sq \:
505 like the following;
506 .Li unique:number .
507 .Li number
508 must be between 1 and 32767.
509 It corresponds to
510 .Ar extensions Fl u .
511 .Pp
512 Note that
513 .Dq Li discard
514 and
515 .Dq Li none
516 are not in the syntax described in
517 .Xr ipsec_set_policy 3 .
518 There are little differences in the syntax.
519 See
520 .Xr ipsec_set_policy 3
521 for detail.
522 .El
523 .\"
524 .Sh ALGORITHMS
525 The following list shows the supported algorithms.
526 .Sy protocol
527 and
528 .Sy algorithm
529 are almost orthogonal.
530 Followings are the list of authentication algorithms that can be used as
531 .Ar aalgo
532 in
533 .Fl A Ar aalgo
534 of
535 .Ar protocol
536 parameter:
537 .Bd -literal -offset indent
538 algorithm       keylen (bits)   comment
539 hmac-md5        128             ah: rfc2403
540                 128             ah-old: rfc2085
541 hmac-sha1       160             ah: rfc2404
542                 160             ah-old: 128bit ICV (no document)
543 keyed-md5       128             ah: 96bit ICV (no document)
544                 128             ah-old: rfc1828
545 keyed-sha1      160             ah: 96bit ICV (no document)
546                 160             ah-old: 128bit ICV (no document)
547 null            0 to 2048       for debugging
548 hmac-sha2-256   256             ah: 96bit ICV (no document)
549                 256             ah-old: 128bit ICV (no document)
550 hmac-sha2-384   384             ah: 96bit ICV (no document)
551                 384             ah-old: 128bit ICV (no document)
552 hmac-sha2-512   512             ah: 96bit ICV (no document)
553                 512             ah-old: 128bit ICV (no document)
554 tcp-md5         8 to 640        tcp: rfc2385
555 .Ed
556 .Pp
557 Followings are the list of encryption algorithms that can be used as
558 .Ar ealgo
559 in
560 .Fl E Ar ealgo
561 of
562 .Ar protocol
563 parameter:
564 .Bd -literal -offset indent
565 algorithm       keylen (bits)   comment
566 des-cbc         64              esp-old: rfc1829, esp: rfc2405
567 3des-cbc        192             rfc2451
568 simple          0 to 2048       rfc2410
569 blowfish-cbc    40 to 448       rfc2451
570 cast128-cbc     40 to 128       rfc2451
571 des-deriv       64              ipsec-ciph-des-derived-01 (expired)
572 3des-deriv      192             no document
573 rijndael-cbc    128/192/256     draft-ietf-ipsec-ciph-aes-cbc-00
574 .Ed
575 .Pp
576 Followings are the list of compression algorithms that can be used as
577 .Ar calgo
578 in
579 .Fl C Ar calgo
580 of
581 .Ar protocol
582 parameter:
583 .Bd -literal -offset indent
584 algorithm       comment
585 deflate         rfc2394
586 lzs             rfc2395
587 .Ed
588 .\"
589 .Sh EXAMPLES
590 .Bd -literal -offset
591 add     2001:db8:4819::1 2001:db8:481d::1 esp 123457
592                 -E des-cbc "ESP SA!!" ;
593
594 add     2001:db8:4819::1 2001:db8:481d::1 ah 123456
595                 -A hmac-sha1 "AH SA configuration!" ;
596
597 add     10.0.11.41 10.0.11.33 esp 0x10001
598                 -E des-cbc "ESP with"
599                 -A hmac-md5 "authentication!!" ;
600
601 get     2001:db8:4819::1 2001:db8:481d::1 ah 123456 ;
602
603 flush ;
604
605 dump esp ;
606
607 spdadd  10.0.11.41/32[21] 10.0.11.33/32[any] any
608                 -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
609
610 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
611
612 .Ed
613 .\"
614 .Sh DIAGNOSTICS
615 The command exits with 0 on success, and non-zero on errors.
616 .\"
617 .Sh SEE ALSO
618 .Xr ipsec_set_policy 3 ,
619 .Xr racoon 8 ,
620 .Xr sysctl 8
621 .\"
622 .Sh HISTORY
623 The
624 .Nm
625 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
626 The command was completely re-designed in June 1998.
627 .\"
628 .\" .Sh BUGS