xref: /freebsd/sbin/setkey/setkey.8 (revision ce4946daa5ce852d28008dac492029500ab2ee95) 
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.Pp
188.Bl -tag -compact -width Ds
189.It Ar src
190.It Ar dst
191Source/destination of the secure communication is specified as
192IPv4/v6 address.
193.Nm
194does not consult hostname-to-address for arguments
195.Ar src
196and
197.Ar dst .
198They must be in numeric form.
199.\"
200.Pp
201.It Ar protocol
202.Ar protocol
203is one of following:
204.Bl -tag -width Fl -compact
205.It Li esp
206ESP based on rfc2405
207.It Li esp-old
208ESP based on rfc1827
209.It Li ah
210AH based on rfc2402
211.It Li ah-old
212AH based on rfc1826
213.It Li ipcomp
214IPCOMP
215.El
216.\"
217.Pp
218.It Ar spi
219Security Parameter Index (SPI) for the SAD and the SPD.
220It must be decimal number or hexadecimal number
221You can not use the set of SPI values in the range 0 through 255.
222.Po
223with
224.Li 0x
225attached
226.Pc .
227.\"
228.Pp
229.It Ar extensions
230take some of the following:
231.Bl -tag -width Fl -compact
232.\"
233.It Fl m Ar mode
234Specify a security protocol mode for use.
235.Ar mode
236is one of following:
237.Li transport , tunnel
238or
239.Li any .
240The default value is
241.Li any .
242.\"
243.It Fl r Ar size
244Specify window size of bytes for replay prevention.
245.Ar size
246must be decimal number in 32-bit word.  If
247.Ar size
248is zero or not specified, replay check don't take place.
249.\"
250.It Fl u Ar id
251Specify the identifier of policy.  See also
252.Xr ipsec_set_policy 3 .
253.\"
254.It Fl f Ar pad_option
255.Ar pad_option
256is one of following:
257.Li zero-pad , random-pad
258or
259.Li seq-pad
260.\"
261.It Fl f Li nocyclic-seq
262Don't allow cyclic sequence number.
263.\"
264.It Fl lh Ar time
265.It Fl ls Ar time
266Specify hard/soft lifetime.
267.El
268.\"
269.Pp
270.It Ar algorithm
271.Bl -tag -width Fl -compact
272.It Fl E Ar ealgo Ar key
273Specify encryption algorithm.
274.It Fl A Ar aalgo Ar key
275Specify authentication algorithm.
276If
277.Fl A
278is used for esp, it will be treated as ESP payload authentication algorithm.
279.It Fl C Ar calgo Op Fl R
280Specify compression algorithm.
281If
282.Fl R
283is not specified with
284.Li ipcomp
285line, the kernel will use well-known IPComp CPI
286.Pq compression parameter index
287on IPComp CPI field on packets, and
288.Ar spi
289field will be ignored.
290.Ar spi
291field is only for kernel internal use in this case.
292.\"Therefore, compression protocol number will appear on IPComp CPI field.
293If
294.Fl R
295is used,
296the value on
297.Ar spi
298field will appear on IPComp CPI field on outgoing packets.
299.Ar spi
300field needs to be smaller than
301.Li 0x10000
302in this case.
303.El
304.Pp
305.Li esp
306SAs accept
307.Fl E
308and
309.Fl A .
310.Li esp-old
311SAs accept
312.Fl E
313only.
314.Li ah
315and
316.Li ah-old
317SAs accept
318.Fl A
319only.
320.Li ipcomp
321SAs accept
322.Fl C
323only.
324.Pp
325.Ar key
326must be double-quoted character string or series of hexadecimal digits.
327.Pp
328Possible values for
329.Ar ealgo ,
330.Ar aalgo
331and
332.Ar calgo
333are specified in separate section.
334.\"
335.Pp
336.It Ar src_range
337.It Ar dst_range
338These are selections of the secure communication specified as
339IPv4/v6 address or IPv4/v6 address range, and it may accompany
340TCP/UDP port specification.
341This takes the following form:
342.Bd -literal -offset
343.Ar address
344.Ar address/prefixlen
345.Ar address[port]
346.Ar address/prefixlen[port]
347.Ed
348.Pp
349.Ar prefixlen
350and
351.Ar port
352must be decimal number.
353The square bracket around
354.Ar port
355is really necessary.
356They are not manpage metacharacters.
357.Pp
358.Nm
359does not consult hostname-to-address for arguments
360.Ar src
361and
362.Ar dst .
363They must be in numeric form.
364.\"
365.Pp
366.It Ar upperspec
367Upper-layer protocol to be used.
368Currently
369.Li tcp ,
370.Li udp
371and
372.Li any
373can be specified.
374.Li any
375stands for
376.Dq any protocol .
377.Pp
378NOTE:
379.Ar upperspec
380does not work against forwarding case at this moment,
381as it requires extra reassembly at forwarding node
382.Pq not implemented at this moment .
383.\"
384.Pp
385.It Ar policy
386.Ar policy
387is the one of following:
388.Pp
389.Bl -item -compact
390.It
391.Fl P
392.Ar direction
393.Li discard
394.It
395.Fl P
396.Ar direction
397.Li none
398.It
399.Fl P
400.Ar direction
401.Li ipsec
402.Ar protocol/mode/src-dst/level
403.El
404.Pp
405You must specify the direction of its policy as
406.Ar direction .
407Either
408.Li out
409or
410.Li in
411are used.
412.Li discard
413means the packet matching indexes will be discarded.
414.Li none
415means that IPsec operation will not take place onto the packet.
416.Li ipsec
417means that IPsec operation will take place onto the packet.
418Either
419.Li ah ,
420.Li esp
421or
422.Li ipcomp
423is to be set as
424.Ar protocol .
425.Ar mode
426is either
427.Li transport
428or
429.Li tunnel .
430You must specify the end-points addresses of the SA as
431.Ar src
432and
433.Ar dst
434with
435.Sq -
436between these addresses which is used to specify the SA to use.
437.Ar level
438is to be one of the following:
439.Li default , use
440or
441.Li require .
442.Li default
443means the kernel consults to the system wide default against protocol you
444specified, e.g.
445.Li esp_trans_deflev
446sysctl variable, when the kernel processes the packet.
447.Li use
448means that the kernel use a SA if it's available,
449otherwise the kernel keeps normal operation.
450.Li require
451means SA is required whenever the kernel deals with the packet.
452Note that
453.Dq Li discard
454and
455.Dq Li none
456are not in the syntax described in
457.Xr ipsec_set_policy 3 .
458There are little differences in the syntax.
459See
460.Xr ipsec_set_policy 3
461for detail.
462.Pp
463.El
464.Pp
465.\"
466.Sh ALGORITHMS
467The following list shows the supported algorithms.
468.Sy protocol
469and
470.Sy algorithm
471are almost orthogonal.
472Followings are the list of authentication algorithms that can be used as
473.Ar aalgo
474in
475.Fl A Ar aalgo
476of
477.Ar protocol
478parameter:
479.Pp
480.Bd -literal -offset indent
481algorithm	keylen (bits)	comment
482hmac-md5	128		ah: rfc2403
483		128		ah-old: rfc2085
484hmac-sha1	160		ah: rfc2404
485		160		ah-old: 128bit ICV (no document)
486keyed-md5	128		ah: 96bit ICV (no document)
487		128		ah-old: rfc1828
488keyed-sha1	160		ah: 96bit ICV (no document)
489		160		ah-old: 128bit ICV (no document)
490null		0 to 2048	for debugging
491.Ed
492.Pp
493Followings are the list of encryption algorithms that can be used as
494.Ar ealgo
495in
496.Fl E Ar ealgo
497of
498.Ar protocol
499parameter:
500.Pp
501.Bd -literal -offset indent
502algorithm	keylen (bits)	comment
503des-cbc		64		esp-old: rfc1829, esp: rfc2405
5043des-cbc	192		rfc2451
505simple		0 to 2048	rfc2410
506blowfish-cbc	40 to 448	rfc2451
507cast128-cbc	40 to 128	rfc2451
508rc5-cbc		40 to 2040	rfc2451
509des-deriv	64		ipsec-ciph-des-derived-01 (expired)
5103des-deriv	192		no document
511.Ed
512.Pp
513Followings are the list of compression algorithms that can be used as
514.Ar calgo
515in
516.Fl C Ar calgo
517of
518.Ar protocol
519parameter:
520.Pp
521.Bd -literal -offset indent
522algorithm	comment
523deflate		rfc2394
524lzs		rfc2395
525.Ed
526.\"
527.Sh EXAMPLES
528.Bd -literal -offset
529add	3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
530		-E des-cbc "ESP SA!!" ;
531
532add	3ffe:501:4819::1 3ffe:501:481d::1 ah 123456
533		-A hmac-sha1 "AH SA configuration!" ;
534
535add	10.0.11.41 10.0.11.33 esp 0x10001
536		-E des-cbc "ESP with"
537		-A hmac-md5 "authentication!!" ;
538
539get	3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
540
541flush ;
542
543dump esp ;
544
545spdadd	10.0.11.41/32[21] 10.0.11.33/32[any] any
546		-P out ipsec esp/tunnel/192.168.0.1-192.168.1.2/require ;
547
548.Ed
549.\"
550.Sh RETURN VALUES
551The command exits with 0 on success, and non-zero on errors.
552.\"
553.Sh SEE ALSO
554.Xr ipsec_set_policy 3 ,
555.Xr sysctl 8
556.\"
557.Sh HISTORY
558The
559.Nm
560command first appeared in WIDE Hydrangea IPv6 protocol stack kit.
561The command was completely re-designed in June 1998.
562.\"
563.\" .Sh BUGS
564