]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - sbin/setkey/setkey.8
Remove spurious newline
[FreeBSD/FreeBSD.git] / sbin / setkey / setkey.8
1 .\"     $KAME: setkey.8,v 1.89 2003/09/07 22:17:41 itojun Exp $
2 .\"
3 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
4 .\" All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\"    notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\"    notice, this list of conditions and the following disclaimer in the
13 .\"    documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the project nor the names of its contributors
15 .\"    may be used to endorse or promote products derived from this software
16 .\"    without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" $FreeBSD$
31 .\"
32 .Dd April 9, 2017
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 v
43 .Fl c
44 .Nm
45 .Op Fl v
46 .Fl f Ar filename
47 .Nm
48 .Op Fl Pgltv
49 .Fl D
50 .Nm
51 .Op Fl Pv
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 indent
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 g
85 Only SPD entries with global scope are dumped with
86 .Fl D
87 and
88 .Fl P
89 flags.
90 .It Fl t
91 Only SPD entries with ifnet scope are dumped with
92 .Fl D
93 and
94 .Fl P
95 flags.
96 Such SPD entries are linked to the corresponding
97 .Xr if_ipsec 4
98 virtual tunneling interface.
99 .It Fl h
100 Add hexadecimal dump on
101 .Fl x
102 mode.
103 .It Fl l
104 Loop forever with short output on
105 .Fl D .
106 .It Fl v
107 Be verbose.
108 The program will dump messages exchanged on
109 .Dv PF_KEY
110 socket, including messages sent from other processes to the kernel.
111 .It Fl x
112 Loop forever and dump all the messages transmitted to
113 .Dv PF_KEY
114 socket.
115 .Fl xx
116 makes each timestamp unformatted.
117 .El
118 .Ss Configuration syntax
119 With
120 .Fl c
121 or
122 .Fl f
123 on the command line,
124 .Nm
125 accepts the following configuration syntax.
126 Lines starting with hash signs
127 .Pq Ql #
128 are treated as comment lines.
129 .Bl -tag -width indent
130 .It Xo
131 .Li add
132 .Op Fl 46n
133 .Ar src Ar dst Ar protocol Ar spi
134 .Op Ar extensions
135 .Ar algorithm ...
136 .Li \&;
137 .Xc
138 Add an SAD entry.
139 .Li add
140 can fail with multiple reasons,
141 including when the key length does not match the specified algorithm.
142 .\"
143 .It Xo
144 .Li get
145 .Op Fl 46n
146 .Ar src Ar dst Ar protocol Ar spi
147 .Li \&;
148 .Xc
149 Show an SAD entry.
150 .\"
151 .It Xo
152 .Li delete
153 .Op Fl 46n
154 .Ar src Ar dst Ar protocol Ar spi
155 .Li \&;
156 .Xc
157 Remove an SAD entry.
158 .\"
159 .It Xo
160 .Li deleteall
161 .Op Fl 46n
162 .Ar src Ar dst Ar protocol
163 .Li \&;
164 .Xc
165 Remove all SAD entries that match the specification.
166 .\"
167 .It Xo
168 .Li flush
169 .Op Ar protocol
170 .Li \&;
171 .Xc
172 Clear all SAD entries matched by the options.
173 .Fl F
174 on the command line achieves the same functionality.
175 .\"
176 .It Xo
177 .Li dump
178 .Op Ar protocol
179 .Li \&;
180 .Xc
181 Dumps all SAD entries matched by the options.
182 .Fl D
183 on the command line achieves the same functionality.
184 .\"
185 .It Xo
186 .Li spdadd
187 .Op Fl 46n
188 .Ar src_range Ar dst_range Ar upperspec Ar policy
189 .Li \&;
190 .Xc
191 Add an SPD entry.
192 .\"
193 .It Xo
194 .Li spddelete
195 .Op Fl 46n
196 .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
197 .Li \&;
198 .Xc
199 Delete an SPD entry.
200 .\"
201 .It Xo
202 .Li spdflush
203 .Li \&;
204 .Xc
205 Clear all SPD entries.
206 .Fl FP
207 on the command line achieves the same functionality.
208 .\"
209 .It Xo
210 .Li spddump
211 .Li \&;
212 .Xc
213 Dumps all SPD entries.
214 .Fl DP
215 on the command line achieves the same functionality.
216 .El
217 .\"
218 .Pp
219 Meta-arguments are as follows:
220 .Pp
221 .Bl -tag -compact -width indent
222 .It Ar src
223 .It Ar dst
224 Source/destination of the secure communication is specified as
225 IPv4/v6 address.
226 The
227 .Nm
228 utility
229 can resolve a FQDN into numeric addresses.
230 If the FQDN resolves into multiple addresses,
231 .Nm
232 will install multiple SAD/SPD entries into the kernel
233 by trying all possible combinations.
234 .Fl 4 ,
235 .Fl 6
236 and
237 .Fl n
238 restricts the address resolution of FQDN in certain ways.
239 .Fl 4
240 and
241 .Fl 6
242 restrict results into IPv4/v6 addresses only, respectively.
243 .Fl n
244 avoids FQDN resolution and requires addresses to be numeric addresses.
245 .\"
246 .Pp
247 .It Ar protocol
248 .Ar protocol
249 is one of following:
250 .Bl -tag -width Fl -compact
251 .It Li esp
252 ESP based on rfc2406
253 .It Li esp-old
254 ESP based on rfc1827
255 .It Li ah
256 AH based on rfc2402
257 .It Li ah-old
258 AH based on rfc1826
259 .It Li ipcomp
260 IPComp
261 .It Li tcp
262 TCP-MD5 based on rfc2385
263 .El
264 .\"
265 .Pp
266 .It Ar spi
267 Security Parameter Index
268 (SPI)
269 for the SAD and the SPD.
270 .Ar spi
271 must be a decimal number, or a hexadecimal number with
272 .Ql 0x
273 prefix.
274 SPI values between 0 and 255 are reserved for future use by IANA
275 and they cannot be used.
276 .\"
277 .Pp
278 .It Ar extensions
279 take some of the following:
280 .Bl -tag -width Fl -compact
281 .\"
282 .It Fl m Ar mode
283 Specify a security protocol mode for use.
284 .Ar mode
285 is one of following:
286 .Li transport , tunnel
287 or
288 .Li any .
289 The default value is
290 .Li any .
291 .\"
292 .It Fl r Ar size
293 Specify the bitmap size in octets of the anti-replay window.
294 .Ar size
295 is a 32-bit unsigned integer, and its value is one eighth of the
296 anti-replay window size in packets.
297 If
298 .Ar size
299 is zero or not specified, an anti-replay check does not take place.
300 .\"
301 .It Fl u Ar id
302 Specify the identifier of the policy entry in SPD.
303 See
304 .Ar policy .
305 .\"
306 .It Fl f Ar pad_option
307 defines the content of the ESP padding.
308 .Ar pad_option
309 is one of following:
310 .Bl -tag -width random-pad -compact
311 .It Li zero-pad
312 All of the padding are zero.
313 .It Li random-pad
314 A series of randomized values are set.
315 .It Li seq-pad
316 A series of sequential increasing numbers started from 1 are set.
317 .El
318 .\"
319 .It Fl f Li nocyclic-seq
320 Do not allow cyclic sequence number.
321 .\"
322 .It Fl lh Ar time
323 .It Fl ls Ar time
324 Specify hard/soft life time duration of the SA.
325 .El
326 .\"
327 .Pp
328 .It Ar algorithm
329 .Bl -tag -width Fl -compact
330 .It Fl E Ar ealgo Ar key
331 Specify an encryption algorithm
332 .Ar ealgo
333 for ESP.
334 .It Xo
335 .Fl E Ar ealgo Ar key
336 .Fl A Ar aalgo Ar key
337 .Xc
338 Specify a encryption algorithm
339 .Ar ealgo ,
340 as well as a payload authentication algorithm
341 .Ar aalgo ,
342 for ESP.
343 .It Fl A Ar aalgo Ar key
344 Specify an authentication algorithm for AH.
345 .It Fl C Ar calgo Op Fl R
346 Specify a compression algorithm for IPComp.
347 If
348 .Fl R
349 is specified, the
350 .Ar spi
351 field value will be used as the IPComp CPI
352 (compression parameter index)
353 on wire as is.
354 If
355 .Fl R
356 is not specified,
357 the kernel will use well-known CPI on wire, and
358 .Ar spi
359 field will be used only as an index for kernel internal usage.
360 .El
361 .Pp
362 .Ar key
363 must be double-quoted character string, or a series of hexadecimal digits
364 preceded by
365 .Ql 0x .
366 .Pp
367 Possible values for
368 .Ar ealgo ,
369 .Ar aalgo
370 and
371 .Ar calgo
372 are specified in separate section.
373 .\"
374 .Pp
375 .It Ar src_range
376 .It Ar dst_range
377 These are selections of the secure communication specified as
378 IPv4/v6 address or IPv4/v6 address range, and it may accompany
379 TCP/UDP port specification.
380 This takes the following form:
381 .Bd -unfilled
382 .Ar address
383 .Ar address/prefixlen
384 .Ar address[port]
385 .Ar address/prefixlen[port]
386 .Ed
387 .Pp
388 .Ar prefixlen
389 and
390 .Ar port
391 must be a decimal number.
392 The square brackets around
393 .Ar port
394 are necessary and are not manpage metacharacters.
395 For FQDN resolution, the rules applicable to
396 .Ar src
397 and
398 .Ar dst
399 apply here as well.
400 .\"
401 .Pp
402 .It Ar upperspec
403 The upper layer protocol to be used.
404 You can use one of the words in
405 .Pa /etc/protocols
406 as
407 .Ar upperspec ,
408 as well as
409 .Li icmp6 ,
410 .Li ip4 ,
411 or
412 .Li any .
413 The word
414 .Li any
415 stands for
416 .Dq any protocol .
417 The protocol number may also be used to specify the
418 .Ar upperspec .
419 A type and code related to ICMPv6 may also be specified as an
420 .Ar upperspec .
421 The type is specified first, followed by a comma and then the relevant
422 code.
423 The specification must be placed after
424 .Li icmp6 .
425 The kernel considers a zero to be a wildcard but
426 cannot distinguish between a wildcard and an ICMPv6
427 type which is zero.
428 The following example shows a policy where IPSec is not required for
429 inbound Neighbor Solicitations:
430 .Pp
431 .Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;"
432 .Pp
433 NOTE:
434 .Ar upperspec
435 does not work in the forwarding case at this moment,
436 as it requires extra reassembly at forwarding node,
437 which is not implemented at this moment.
438 Although there are many protocols in
439 .Pa /etc/protocols ,
440 protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec.
441 .\"
442 .Pp
443 .It Ar policy
444 .Ar policy
445 is expressed in one of the following three formats:
446 .Pp
447 .Bl -tag -width 2n -compact
448 .It Fl P Ar direction Li discard
449 .It Fl P Ar direction Li none
450 .It Xo Fl P Ar direction Li ipsec
451 .Ar protocol/mode/src-dst/level Op ...
452 .Xc
453 .El
454 .Pp
455 The direction of a policy must be specified as
456 one of:
457 .Li out ,
458 .Li in ,
459 .Li discard ,
460 .Li none ,
461 or
462 .Li ipsec .
463 The
464 .Li discard
465 direction
466 means that packets matching the supplied indices will be discarded
467 while
468 .Li none
469 means that IPsec operations will not take place on the packet and
470 .Li ipsec
471 means that IPsec operation will take place onto the packet.
472 The
473 .Ar protocol/mode/src-dst/level
474 statement gives the rule for how to process the packet.
475 The
476 .Ar protocol
477 is specified as
478 .Li ah ,
479 .Li esp
480 or
481 .Li ipcomp .
482 The
483 .Ar mode
484 is either
485 .Li transport
486 or
487 .Li tunnel .
488 If
489 .Ar mode
490 is
491 .Li tunnel ,
492 you must specify the end-point addresses of the SA as
493 .Ar src
494 and
495 .Ar dst
496 with a dash,
497 .Sq - ,
498 between the addresses.
499 If
500 .Ar mode
501 is
502 .Li transport ,
503 both
504 .Ar src
505 and
506 .Ar dst
507 can be omitted.
508 The
509 .Ar level
510 is one of the following:
511 .Li default , use , require
512 or
513 .Li unique .
514 If the SA is not available in every level, the kernel will request
515 the SA from the key exchange daemon.
516 A value of
517 .Li default
518 tells the kernel to use the system wide default protocol
519 e.g.,\& the one from the
520 .Li esp_trans_deflev
521 sysctl variable, when the kernel processes the packet.
522 A value of
523 .Li use
524 means that the kernel will use an SA if it is available,
525 otherwise the kernel will pass the packet as it would normally.
526 A value of
527 .Li require
528 means that an SA is required whenever the kernel sends a packet matched
529 that matches the policy.
530 The
531 .Li unique
532 level is the same as
533 .Li require
534 but, in addition, it allows the policy to bind with the unique out-bound SA.
535 For example, if you specify the policy level
536 .Li unique ,
537 .Xr racoon 8
538 will configure the SA for the policy.
539 If you configure the SA by manual keying for that policy,
540 you can put the decimal number as the policy identifier after
541 .Li unique
542 separated by colon
543 .Ql :\&
544 as in the following example:
545 .Li unique:number .
546 In order to bind this policy to the SA,
547 .Li number
548 must be between 1 and 32767,
549 which corresponds to
550 .Ar extensions Fl u
551 of manual SA configuration.
552 .Pp
553 When you want to use an SA bundle, you can define multiple rules.
554 For
555 example, if an IP header was followed by an AH header followed by an
556 ESP header followed by an upper layer protocol header, the rule would
557 be:
558 .Pp
559 .Dl esp/transport//require ah/transport//require ;
560 .Pp
561 The rule order is very important.
562 .Pp
563 Note that
564 .Dq Li discard
565 and
566 .Dq Li none
567 are not in the syntax described in
568 .Xr ipsec_set_policy 3 .
569 There are small, but important, differences in the syntax.
570 See
571 .Xr ipsec_set_policy 3
572 for details.
573 .El
574 .\"
575 .Sh ALGORITHMS
576 The following list shows the supported algorithms.
577 The
578 .Sy protocol
579 and
580 .Sy algorithm
581 are almost completely orthogonal.
582 The following list of authentication algorithms can be used as
583 .Ar aalgo
584 in the
585 .Fl A Ar aalgo
586 of the
587 .Ar protocol
588 parameter:
589 .Bd -literal -offset indent
590 algorithm       keylen (bits)   comment
591 hmac-md5        128             ah: rfc2403
592                 128             ah-old: rfc2085
593 hmac-sha1       160             ah: rfc2404
594                 160             ah-old: 128bit ICV (no document)
595 keyed-md5       128             ah: 96bit ICV (no document)
596                 128             ah-old: rfc1828
597 keyed-sha1      160             ah: 96bit ICV (no document)
598                 160             ah-old: 128bit ICV (no document)
599 null            0 to 2048       for debugging
600 hmac-sha2-256   256             ah: 128bit ICV (RFC4868)
601                 256             ah-old: 128bit ICV (no document)
602 hmac-sha2-384   384             ah: 192bit ICV (RFC4868)
603                 384             ah-old: 128bit ICV (no document)
604 hmac-sha2-512   512             ah: 256bit ICV (RFC4868)
605                 512             ah-old: 128bit ICV (no document)
606 hmac-ripemd160  160             ah: 96bit ICV (RFC2857)
607                                 ah-old: 128bit ICV (no document)
608 aes-xcbc-mac    128             ah: 96bit ICV (RFC3566)
609                 128             ah-old: 128bit ICV (no document)
610 tcp-md5         8 to 640        tcp: rfc2385
611 .Ed
612 .Pp
613 The following is the list of encryption algorithms that can be used as the
614 .Ar ealgo
615 in the
616 .Fl E Ar ealgo
617 of the
618 .Ar protocol
619 parameter:
620 .Bd -literal -offset indent
621 algorithm       keylen (bits)   comment
622 des-cbc         64              esp-old: rfc1829, esp: rfc2405
623 3des-cbc        192             rfc2451
624 null            0 to 2048       rfc2410
625 blowfish-cbc    40 to 448       rfc2451
626 cast128-cbc     40 to 128       rfc2451
627 des-deriv       64              ipsec-ciph-des-derived-01
628 rijndael-cbc    128/192/256     rfc3602
629 aes-ctr         160/224/288     draft-ietf-ipsec-ciph-aes-ctr-03
630 aes-gcm-16      160/224/288     rfc4106
631 camellia-cbc    128/192/256     rfc4312
632 .Ed
633 .Pp
634 Note that the first 128/192/256 bits of a key for
635 .Li aes-ctr or aes-gcm-16
636 will be used as AES key, and remaining 32 bits will be used as nonce.
637 .Pp
638 The following are the list of compression algorithms that can be used
639 as the
640 .Ar calgo
641 in the
642 .Fl C Ar calgo
643 of the
644 .Ar protocol
645 parameter:
646 .Bd -literal -offset indent
647 algorithm       comment
648 deflate         rfc2394
649 .Ed
650 .\"
651 .Sh EXIT STATUS
652 .Ex -std
653 .\"
654 .Sh EXAMPLES
655 Add an ESP SA between two IPv6 addresses using the
656 des-cbc encryption algorithm.
657 .Bd -literal -offset indent
658 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
659         -E des-cbc 0x3ffe05014819ffff ;
660 .Pp
661 .Ed
662 .\"
663 Add an authentication SA between two FQDN specified hosts:
664 .Bd -literal -offset indent
665 add -6 myhost.example.com yourhost.example.com ah 123456
666         -A hmac-sha1 "AH SA configuration!" ;
667 .Pp
668 .Ed
669 Use both ESP and AH between two numerically specified hosts:
670 .Bd -literal -offset indent
671 add 10.0.11.41 10.0.11.33 esp 0x10001
672         -E des-cbc 0x3ffe05014819ffff
673         -A hmac-md5 "authentication!!" ;
674 .Pp
675 .Ed
676 Get the SA information associated with first example above:
677 .Bd -literal -offset indent
678 get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
679 .Pp
680 .Ed
681 Flush all entries from the database:
682 .Bd -literal -offset indent
683 flush ;
684 .Pp
685 .Ed
686 Dump the ESP entries from the database:
687 .Bd -literal -offset indent
688 dump esp ;
689 .Pp
690 .Ed
691 Add a security policy between two networks that uses ESP in tunnel mode:
692 .Bd -literal -offset indent
693 spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
694         -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
695 .Pp
696 .Ed
697 Use TCP MD5 between two numerically specified hosts:
698 .Bd -literal -offset indent
699 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
700 add 10.1.10.36 10.1.10.34 tcp 0x1001 -A tcp-md5 "TCP-MD5 BGP secret" ;
701 .Ed
702 .\"
703 .Sh SEE ALSO
704 .Xr ipsec_set_policy 3 ,
705 .Xr if_ipsec 4 ,
706 .Xr racoon 8 ,
707 .Xr sysctl 8
708 .Rs
709 .%T "Changed manual key configuration for IPsec"
710 .%U http://www.kame.net/newsletter/19991007/
711 .%D "October 1999"
712 .Re
713 .\"
714 .Sh HISTORY
715 The
716 .Nm
717 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
718 The utility was completely re-designed in June 1998.
719 It first appeared in
720 .Fx 4.0 .
721 .\"
722 .Sh BUGS
723 The
724 .Nm
725 utility
726 should report and handle syntax errors better.
727 .Pp
728 For IPsec gateway configuration,
729 .Ar src_range
730 and
731 .Ar dst_range
732 with TCP/UDP port number do not work, as the gateway does not reassemble
733 packets
734 (cannot inspect upper-layer headers).