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