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