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