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