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