]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - sbin/setkey/setkey.8
MFC r316490:
[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 5, 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 window size of bytes for replay prevention.
294 .Ar size
295 must be decimal number in 32-bit word.
296 If
297 .Ar size
298 is zero or not specified, replay check does not take place.
299 .\"
300 .It Fl u Ar id
301 Specify the identifier of the policy entry in SPD.
302 See
303 .Ar policy .
304 .\"
305 .It Fl f Ar pad_option
306 defines the content of the ESP padding.
307 .Ar pad_option
308 is one of following:
309 .Bl -tag -width random-pad -compact
310 .It Li zero-pad
311 All of the padding are zero.
312 .It Li random-pad
313 A series of randomized values are set.
314 .It Li seq-pad
315 A series of sequential increasing numbers started from 1 are set.
316 .El
317 .\"
318 .It Fl f Li nocyclic-seq
319 Do not allow cyclic sequence number.
320 .\"
321 .It Fl lh Ar time
322 .It Fl ls Ar time
323 Specify hard/soft life time duration of the SA.
324 .El
325 .\"
326 .Pp
327 .It Ar algorithm
328 .Bl -tag -width Fl -compact
329 .It Fl E Ar ealgo Ar key
330 Specify an encryption algorithm
331 .Ar ealgo
332 for ESP.
333 .It Xo
334 .Fl E Ar ealgo Ar key
335 .Fl A Ar aalgo Ar key
336 .Xc
337 Specify a encryption algorithm
338 .Ar ealgo ,
339 as well as a payload authentication algorithm
340 .Ar aalgo ,
341 for ESP.
342 .It Fl A Ar aalgo Ar key
343 Specify an authentication algorithm for AH.
344 .It Fl C Ar calgo Op Fl R
345 Specify a compression algorithm for IPComp.
346 If
347 .Fl R
348 is specified, the
349 .Ar spi
350 field value will be used as the IPComp CPI
351 (compression parameter index)
352 on wire as is.
353 If
354 .Fl R
355 is not specified,
356 the kernel will use well-known CPI on wire, and
357 .Ar spi
358 field will be used only as an index for kernel internal usage.
359 .El
360 .Pp
361 .Ar key
362 must be double-quoted character string, or a series of hexadecimal digits
363 preceded by
364 .Ql 0x .
365 .Pp
366 Possible values for
367 .Ar ealgo ,
368 .Ar aalgo
369 and
370 .Ar calgo
371 are specified in separate section.
372 .\"
373 .Pp
374 .It Ar src_range
375 .It Ar dst_range
376 These are selections of the secure communication specified as
377 IPv4/v6 address or IPv4/v6 address range, and it may accompany
378 TCP/UDP port specification.
379 This takes the following form:
380 .Bd -unfilled
381 .Ar address
382 .Ar address/prefixlen
383 .Ar address[port]
384 .Ar address/prefixlen[port]
385 .Ed
386 .Pp
387 .Ar prefixlen
388 and
389 .Ar port
390 must be a decimal number.
391 The square brackets around
392 .Ar port
393 are necessary and are not manpage metacharacters.
394 For FQDN resolution, the rules applicable to
395 .Ar src
396 and
397 .Ar dst
398 apply here as well.
399 .\"
400 .Pp
401 .It Ar upperspec
402 The upper layer protocol to be used.
403 You can use one of the words in
404 .Pa /etc/protocols
405 as
406 .Ar upperspec ,
407 as well as
408 .Li icmp6 ,
409 .Li ip4 ,
410 or
411 .Li any .
412 The word
413 .Li any
414 stands for
415 .Dq any protocol .
416 The protocol number may also be used to specify the
417 .Ar upperspec .
418 A type and code related to ICMPv6 may also be specified as an
419 .Ar upperspec .
420 The type is specified first, followed by a comma and then the relevant
421 code.
422 The specification must be placed after
423 .Li icmp6 .
424 The kernel considers a zero to be a wildcard but
425 cannot distinguish between a wildcard and an ICMPv6
426 type which is zero.
427 The following example shows a policy where IPSec is not required for
428 inbound Neighbor Solicitations:
429 .Pp
430 .Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;"
431 .Pp
432 NOTE:
433 .Ar upperspec
434 does not work in the forwarding case at this moment,
435 as it requires extra reassembly at forwarding node,
436 which is not implemented at this moment.
437 Although there are many protocols in
438 .Pa /etc/protocols ,
439 protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec.
440 .\"
441 .Pp
442 .It Ar policy
443 .Ar policy
444 is expressed in one of the following three formats:
445 .Pp
446 .Bl -tag -width 2n -compact
447 .It Fl P Ar direction Li discard
448 .It Fl P Ar direction Li none
449 .It Xo Fl P Ar direction Li ipsec
450 .Ar protocol/mode/src-dst/level Op ...
451 .Xc
452 .El
453 .Pp
454 The direction of a policy must be specified as
455 one of:
456 .Li out ,
457 .Li in ,
458 .Li discard ,
459 .Li none ,
460 or
461 .Li ipsec .
462 The
463 .Li discard
464 direction
465 means that packets matching the supplied indices will be discarded
466 while
467 .Li none
468 means that IPsec operations will not take place on the packet and
469 .Li ipsec
470 means that IPsec operation will take place onto the packet.
471 The
472 .Ar protocol/mode/src-dst/level
473 statement gives the rule for how to process the packet.
474 The
475 .Ar protocol
476 is specified as
477 .Li ah ,
478 .Li esp
479 or
480 .Li ipcomp .
481 The
482 .Ar mode
483 is either
484 .Li transport
485 or
486 .Li tunnel .
487 If
488 .Ar mode
489 is
490 .Li tunnel ,
491 you must specify the end-point addresses of the SA as
492 .Ar src
493 and
494 .Ar dst
495 with a dash,
496 .Sq - ,
497 between the addresses.
498 If
499 .Ar mode
500 is
501 .Li transport ,
502 both
503 .Ar src
504 and
505 .Ar dst
506 can be omitted.
507 The
508 .Ar level
509 is one of the following:
510 .Li default , use , require
511 or
512 .Li unique .
513 If the SA is not available in every level, the kernel will request
514 the SA from the key exchange daemon.
515 A value of
516 .Li default
517 tells the kernel to use the system wide default protocol
518 e.g.,\& the one from the
519 .Li esp_trans_deflev
520 sysctl variable, when the kernel processes the packet.
521 A value of
522 .Li use
523 means that the kernel will use an SA if it is available,
524 otherwise the kernel will pass the packet as it would normally.
525 A value of
526 .Li require
527 means that an SA is required whenever the kernel sends a packet matched
528 that matches the policy.
529 The
530 .Li unique
531 level is the same as
532 .Li require
533 but, in addition, it allows the policy to bind with the unique out-bound SA.
534 For example, if you specify the policy level
535 .Li unique ,
536 .Xr racoon 8
537 will configure the SA for the policy.
538 If you configure the SA by manual keying for that policy,
539 you can put the decimal number as the policy identifier after
540 .Li unique
541 separated by colon
542 .Ql :\&
543 as in the following example:
544 .Li unique:number .
545 In order to bind this policy to the SA,
546 .Li number
547 must be between 1 and 32767,
548 which corresponds to
549 .Ar extensions Fl u
550 of manual SA configuration.
551 .Pp
552 When you want to use an SA bundle, you can define multiple rules.
553 For
554 example, if an IP header was followed by an AH header followed by an
555 ESP header followed by an upper layer protocol header, the rule would
556 be:
557 .Pp
558 .Dl esp/transport//require ah/transport//require ;
559 .Pp
560 The rule order is very important.
561 .Pp
562 Note that
563 .Dq Li discard
564 and
565 .Dq Li none
566 are not in the syntax described in
567 .Xr ipsec_set_policy 3 .
568 There are small, but important, differences in the syntax.
569 See
570 .Xr ipsec_set_policy 3
571 for details.
572 .El
573 .\"
574 .Sh ALGORITHMS
575 The following list shows the supported algorithms.
576 The
577 .Sy protocol
578 and
579 .Sy algorithm
580 are almost completely orthogonal.
581 The following list of authentication algorithms can be used as
582 .Ar aalgo
583 in the
584 .Fl A Ar aalgo
585 of the
586 .Ar protocol
587 parameter:
588 .Bd -literal -offset indent
589 algorithm       keylen (bits)   comment
590 hmac-md5        128             ah: rfc2403
591                 128             ah-old: rfc2085
592 hmac-sha1       160             ah: rfc2404
593                 160             ah-old: 128bit ICV (no document)
594 keyed-md5       128             ah: 96bit ICV (no document)
595                 128             ah-old: rfc1828
596 keyed-sha1      160             ah: 96bit ICV (no document)
597                 160             ah-old: 128bit ICV (no document)
598 null            0 to 2048       for debugging
599 hmac-sha2-256   256             ah: 128bit ICV (RFC4868)
600                 256             ah-old: 128bit ICV (no document)
601 hmac-sha2-384   384             ah: 192bit ICV (RFC4868)
602                 384             ah-old: 128bit ICV (no document)
603 hmac-sha2-512   512             ah: 256bit ICV (RFC4868)
604                 512             ah-old: 128bit ICV (no document)
605 hmac-ripemd160  160             ah: 96bit ICV (RFC2857)
606                                 ah-old: 128bit ICV (no document)
607 aes-xcbc-mac    128             ah: 96bit ICV (RFC3566)
608                 128             ah-old: 128bit ICV (no document)
609 tcp-md5         8 to 640        tcp: rfc2385
610 .Ed
611 .Pp
612 The following is the list of encryption algorithms that can be used as the
613 .Ar ealgo
614 in the
615 .Fl E Ar ealgo
616 of the
617 .Ar protocol
618 parameter:
619 .Bd -literal -offset indent
620 algorithm       keylen (bits)   comment
621 des-cbc         64              esp-old: rfc1829, esp: rfc2405
622 3des-cbc        192             rfc2451
623 null            0 to 2048       rfc2410
624 blowfish-cbc    40 to 448       rfc2451
625 cast128-cbc     40 to 128       rfc2451
626 des-deriv       64              ipsec-ciph-des-derived-01
627 rijndael-cbc    128/192/256     rfc3602
628 aes-ctr         160/224/288     draft-ietf-ipsec-ciph-aes-ctr-03
629 aes-gcm-16      160/224/288     rfc4106
630 camellia-cbc    128/192/256     rfc4312
631 .Ed
632 .Pp
633 Note that the first 128/192/256 bits of a key for
634 .Li aes-ctr or aes-gcm-16
635 will be used as AES key, and remaining 32 bits will be used as nonce.
636 .Pp
637 The following are the list of compression algorithms that can be used
638 as the
639 .Ar calgo
640 in the
641 .Fl C Ar calgo
642 of the
643 .Ar protocol
644 parameter:
645 .Bd -literal -offset indent
646 algorithm       comment
647 deflate         rfc2394
648 .Ed
649 .\"
650 .Sh EXIT STATUS
651 .Ex -std
652 .\"
653 .Sh EXAMPLES
654 Add an ESP SA between two IPv6 addresses using the
655 des-cbc encryption algorithm.
656 .Bd -literal -offset indent
657 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
658         -E des-cbc 0x3ffe05014819ffff ;
659 .Pp
660 .Ed
661 .\"
662 Add an authentication SA between two FQDN specified hosts:
663 .Bd -literal -offset indent
664 add -6 myhost.example.com yourhost.example.com ah 123456
665         -A hmac-sha1 "AH SA configuration!" ;
666 .Pp
667 .Ed
668 Use both ESP and AH between two numerically specified hosts:
669 .Bd -literal -offset indent
670 add 10.0.11.41 10.0.11.33 esp 0x10001
671         -E des-cbc 0x3ffe05014819ffff
672         -A hmac-md5 "authentication!!" ;
673 .Pp
674 .Ed
675 Get the SA information associated with first example above:
676 .Bd -literal -offset indent
677 get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
678 .Pp
679 .Ed
680 Flush all entries from the database:
681 .Bd -literal -offset indent
682 flush ;
683 .Pp
684 .Ed
685 Dump the ESP entries from the database:
686 .Bd -literal -offset indent
687 dump esp ;
688 .Pp
689 .Ed
690 Add a security policy between two networks that uses ESP in tunnel mode:
691 .Bd -literal -offset indent
692 spdadd 10.0.11.41/32[21] 10.0.11.33/32[any] any
693         -P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
694 .Pp
695 .Ed
696 Use TCP MD5 between two numerically specified hosts:
697 .Bd -literal -offset indent
698 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
699 add 10.1.10.36 10.1.10.34 tcp 0x1001 -A tcp-md5 "TCP-MD5 BGP secret" ;
700 .Ed
701 .\"
702 .Sh SEE ALSO
703 .Xr ipsec_set_policy 3 ,
704 .Xr if_ipsec 4 ,
705 .Xr racoon 8 ,
706 .Xr sysctl 8
707 .Rs
708 .%T "Changed manual key configuration for IPsec"
709 .%U http://www.kame.net/newsletter/19991007/
710 .%D "October 1999"
711 .Re
712 .\"
713 .Sh HISTORY
714 The
715 .Nm
716 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
717 The utility was completely re-designed in June 1998.
718 It first appeared in
719 .Fx 4.0 .
720 .\"
721 .Sh BUGS
722 The
723 .Nm
724 utility
725 should report and handle syntax errors better.
726 .Pp
727 For IPsec gateway configuration,
728 .Ar src_range
729 and
730 .Ar dst_range
731 with TCP/UDP port number do not work, as the gateway does not reassemble
732 packets
733 (cannot inspect upper-layer headers).