xref: /freebsd/sbin/setkey/setkey.8 (revision 77a0943ded95b9e6438f7db70c4a28e4d93946d4) 
1.\"     $FreeBSD$
2.\"     $KAME: setkey.8,v 1.28 2000/06/16 12:03:46 sakane 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 May 17, 1998
32.Dt SETKEY 8
33.Os KAME
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
57.Nm
58addes, updates, dumpes, or flushes
59Security Association Database (SAD) entries
60as well as Security Policy Database (SPD) entries in the kernel.
61.Pp
62.Nm
63takes a series of operations from the standard input
64.Po
65if invoked with
66.Fl c
67.Pc
68or the file named
69.Ar filename
70.Po
71if invoked with
72.Fl f Ar filename
73.Pc .
74.Bl -tag -width Ds
75.It Fl D
76Dump the SAD entries.
77If with
78.Fl P ,
79the SPD entries are dumped.
80.It Fl F
81Flush the SAD entries.
82If with
83.Fl P ,
84the SPD entries are flushed.
85.It Fl a
86.Nm
87usually does not display dead SAD entries with
88.Fl D .
89If with
90.Fl a ,
91the dead SAD entries will be displayed as well.
92A dead SAD entry means that
93it has been expired but remains
94because it is referenced by SPD entries.
95.It Fl d
96Enable to print debugging messages for command parser,
97without talking to kernel.  It is not used usually.
98.It Fl x
99Loop forever and dump all the messages transmitted to
100.Dv PF_KEY
101socket.
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.
111.Dv PF_KEY
112socket
113.Po
114including messages sent from other processes
115.Pc .
116.El
117.Pp
118Operations have the following grammar. Note that lines starting with
119hashmarks ('#') 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
128Add an SAD entry.
129.\"
130.It Xo
131.Li get
132.Ar src Ar dst Ar protocol Ar spi
133.Li ;
134.Xc
135Show an SAD entry.
136.\"
137.It Xo
138.Li delete
139.Ar src Ar dst Ar protocol Ar spi
140.Li ;
141.Xc
142Remove an SAD entry.
143.\"
144.It Xo
145.Li flush
146.Op Ar protocol
147.Li ;
148.Xc
149Clear all SAD entries matched by the options.
150.\"
151.It Xo
152.Li dump
153.Op Ar protocol
154.Li ;
155.Xc
156Dumps all SAD entries matched by the options.
157.\"
158.It Xo
159.Li spdadd
160.Ar src_range Ar dst_range Ar upperspec Ar policy
161.Li ;
162.Xc
163Add an SPD entry.
164.\"
165.It Xo
166.Li spddelete
167.Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
168.Li ;
169.Xc
170Delete an SPD entry.
171.\"
172.It Xo
173.Li spdflush
174.Li ;
175.Xc
176Clear all SPD entries.
177.\"
178.It Xo
179.Li spddump
180.Li ;
181.Xc
182Dumps all SPD entries.
183.El
184.\"
185.Pp
186Meta-arguments are as follows:
187.Bl -tag -compact -width Ds
188.It Ar src
189.It Ar dst
190Source/destination of the secure communication is specified as
191IPv4/v6 address.
192.Nm
193does not consult hostname-to-address for arguments
194.Ar src
195and
196.Ar dst .
197They must be in numeric form.
198.\"
199.Pp
200.It Ar protocol
201.Ar protocol
202is one of following:
203.Bl -tag -width Fl -compact
204.It Li esp
205ESP based on rfc2405
206.It Li esp-old
207ESP based on rfc1827
208.It Li ah
209AH based on rfc2402
210.It Li ah-old
211AH based on rfc1826
212.It Li ipcomp
213IPCOMP
214.El
215.\"
216.Pp
217.It Ar spi
218Security Parameter Index (SPI) for the SAD and the SPD.
219It must be decimal number or hexadecimal number
220You can not use the set of SPI values in the range 0 through 255.
221.Po
222with
223.Li 0x
224attached
225.Pc .
226.\"
227.Pp
228.It Ar extensions
229take some of the following:
230.Bl -tag -width Fl -compact
231.\"
232.It Fl m Ar mode
233Specify a security protocol mode for use.
234.Ar mode
235is one of following:
236.Li transport , tunnel
237or
238.Li any .
239The default value is
240.Li any .
241.\"
242.It Fl r Ar size
243Specify window size of bytes for replay prevention.
244.Ar size
245must be decimal number in 32-bit word.  If
246.Ar size
247is zero or not specified, replay check don't take place.
248.\"
249.It Fl u Ar id
250Specify the identifier of policy.  See also
251.Xr ipsec_set_policy 3 .
252.\"
253.It Fl f Ar pad_option
254.Ar pad_option
255is one of following:
256.Li zero-pad , random-pad
257or
258.Li seq-pad
259.\"
260.It Fl f Li nocyclic-seq
261Don't allow cyclic sequence number.
262.\"
263.It Fl lh Ar time
264.It Fl ls Ar time
265Specify hard/soft lifetime.
266.El
267.\"
268.Pp
269.It Ar algorithm
270.Bl -tag -width Fl -compact
271.It Fl E Ar ealgo Ar key
272Specify encryption algorithm.
273.It Fl A Ar aalgo Ar key
274Specify authentication algorithm.
275If
276.Fl A
277is used for esp, it will be treated as ESP payload authentication algorithm.
278.It Fl C Ar calgo Op Fl R
279Specify compression algorithm.
280If
281.Fl R
282is not specified with
283.Li ipcomp
284line, the kernel will use well-known IPComp CPI
285.Pq compression parameter index
286on IPComp CPI field on packets, and
287.Ar spi
288field will be ignored.
289.Ar spi
290field is only for kernel internal use in this case.
291.\"Therefore, compression protocol number will appear on IPComp CPI field.
292If
293.Fl R
294is used,
295the value on
296.Ar spi
297field will appear on IPComp CPI field on outgoing packets.
298.Ar spi
299field needs to be smaller than
300.Li 0x10000
301in this case.
302.El
303.Pp
304.Li esp
305SAs accept
306.Fl E
307and
308.Fl A .
309.Li esp-old
310SAs accept
311.Fl E
312only.
313.Li ah
314and
315.Li ah-old
316SAs accept
317.Fl A
318only.
319.Li ipcomp
320SAs accept
321.Fl C
322only.
323.Pp
324.Ar key
325must be double-quoted character string or series of hexadecimal digits.
326.Pp
327Possible values for
328.Ar ealgo ,
329.Ar aalgo
330and
331.Ar calgo
332are specified in separate section.
333.\"
334.It Ar src_range
335.It Ar dst_range
336These are selections of the secure communication specified as
337IPv4/v6 address or IPv4/v6 address range, and it may accompany
338TCP/UDP port specification.
339This takes the following form:
340.Bd -literal -offset
341.Ar address
342.Ar address/prefixlen
343.Ar address[port]
344.Ar address/prefixlen[port]
345.Ed
346.Pp
347.Ar prefixlen
348and
349.Ar port
350must be decimal number.
351The square bracket around
352.Ar port
353is really necessary.
354They are not manpage metacharacters.
355.Pp
356.Nm
357does not consult hostname-to-address for arguments
358.Ar src
359and
360.Ar dst .
361They must be in numeric form.
362.\"
363.It Ar upperspec
364Upper-layer protocol to be used.
365Currently
366.Li tcp ,
367.Li udp
368and
369.Li any
370can be specified.
371.Li any
372stands for
373.Dq any protocol .
374.Pp
375NOTE:
376.Ar upperspec
377does not work against forwarding case at this moment,
378as it requires extra reassembly at forwarding node
379.Pq not implemented at this moment .
380.\"
381.It Ar policy
382.Ar policy
383is the one of following:
384.Bd -literal -offset
385.Xo
386.Fl P
387.Ar direction
388.Li discard
389.Xc
390.Xo
391.Fl P
392.Ar direction
393.Li none
394.Xc
395.Xo
396.Fl P
397.Ar direction
398.Li ipsec
399.Ar protocol/mode/src-dst/level
400.Xc
401.Ed
402.Pp
403You must specify the direction of its policy as
404.Ar direction .
405Either
406.Li out
407or
408.Li in
409are used.
410.Li discard
411means the packet matching indexes will be discarded.
412.Li none
413means that IPsec operation will not take place onto the packet.
414.Li ipsec
415means that IPsec operation will take place onto the packet.
416Either
417.Li ah ,
418.Li esp
419or
420.Li ipcomp
421is to be set as
422.Ar protocol .
423.Ar mode
424is either
425.Li transport
426or
427.Li tunnel .
428You must specify the end-points addresses of the SA as
429.Ar src
430and
431.Ar dst
432with
433.Sq -
434between these addresses which is used to specify the SA to use.
435.Ar level
436is to be one of the following:
437.Li default , use
438or
439.Li require .
440.Li default
441means the kernel consults to the system wide default against protocol you
442specified, e.g.
443.Li esp_trans_deflev
444sysctl variable, when the kernel processes the packet.
445.Li use
446means that the kernel use a SA if it's available,
447otherwise the kernel keeps normal operation.
448.Li require
449means SA is required whenever the kernel deals with the packet.
450Note that
451.Dq Li discard
452and
453.Dq Li none
454are not in the syntax described in
455.Xr ipsec_set_policy 3 .
456There are little differences in the syntax.
457See
458.Xr ipsec_set_policy 3
459for detail.
460.Pp
461.El
462.Pp
463.\"
464.Sh ALGORITHMS
465The following list shows the supported algorithms.
466.Sy protocol
467and
468.Sy algorithm
469are almost orthogonal.
470Followings are the list of authentication algorithms that can be used as
471.Ar aalgo
472in
473.Fl A Ar aalgo
474of
475.Ar protocol
476parameter:
477.Pp
478.Bd -literal -offset indent
479algorithm	keylen (bits)	comment
480hmac-md5	128		ah: rfc2403
481		128		ah-old: rfc2085
482hmac-sha1	160		ah: rfc2404
483		160		ah-old: 128bit ICV (no document)
484keyed-md5	128		ah: 96bit ICV (no document)
485		128		ah-old: rfc1828
486keyed-sha1	160		ah: 96bit ICV (no document)
487		160		ah-old: 128bit ICV (no document)
488null		0 to 2048	for debugging
489.Ed
490.Pp
491Followings are the list of encryption algorithms that can be used as
492.Ar ealgo
493in
494.Fl E Ar ealgo
495of
496.Ar protocol
497parameter:
498.Pp
499.Bd -literal -offset indent
500algorithm	keylen (bits)	comment
501des-cbc		64		esp-old: rfc1829, esp: rfc2405
5023des-cbc	192		rfc2451
503simple		0 to 2048	rfc2410
504blowfish-cbc	40 to 448	rfc2451
505cast128-cbc	40 to 128	rfc2451
506rc5-cbc		40 to 2040	rfc2451
507des-deriv	64		ipsec-ciph-des-derived-01 (expired)
5083des-deriv	192		no document
509.Ed
510.Pp
511Followings are the list of compression algorithms that can be used as
512.Ar calgo
513in
514.Fl C Ar calgo
515of
516.Ar protocol
517parameter:
518.Pp
519.Bd -literal -offset indent
520algorithm	comment
521deflate		rfc2394
522lzs		rfc2395
523.Ed
524.\"
525.Sh EXAMPLES
526.Bd -literal -offset
527add	3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
528		-E des-cbc "ESP SA!!" ;
529
530add	3ffe:501:4819::1 3ffe:501:481d::1 ah 123456
531		-A hmac-sha1 "AH SA configuration!" ;
532
533add	10.0.11.41 10.0.11.33 esp 0x10001
534		-E des-cbc "ESP with"
535		-A hmac-md5 "authentication!!" ;
536
537get	3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
538
539flush ;
540
541dump esp ;
542
543spdadd	10.0.11.41/32[21] 10.0.11.33/32[any] any
544		-P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
545
546.Ed
547.\"
548.Sh RETURN VALUES
549The command exits with 0 on success, and non-zero on errors.
550.\"
551.Sh SEE ALSO
552.Xr ipsec_set_policy 3 ,
553.Xr sysctl 8
554.\"
555.Sh HISTORY
556The
557.Nm
558command first appeared in WIDE Hydrangea IPv6 protocol stack kit.
559The command was completely re-designed in June 1998.
560.\"
561.\" .Sh BUGS
562