1 .\" $KAME: setkey.8,v 1.89 2003/09/07 22:17:41 itojun Exp $
3 .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project.
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
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.
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
38 .Nd "manually manipulate the IPsec SA/SP database"
60 utility adds, updates, dumps, or flushes
61 Security Association Database (SAD) entries
62 as well as Security Policy Database (SPD) entries in the kernel.
66 utility takes a series of operations from the standard input
73 .Bl -tag -width indent
78 the SPD entries are dumped.
80 Flush the SAD entries.
83 the SPD entries are flushed.
85 Only SPD entries with global scope are dumped with
91 Only SPD entries with ifnet scope are dumped with
96 Such SPD entries are linked to the corresponding
98 virtual tunneling interface.
100 Add hexadecimal dump on
104 Loop forever with short output on
108 The program will dump messages exchanged on
110 socket, including messages sent from other processes to the kernel.
112 Loop forever and dump all the messages transmitted to
116 makes each timestamp unformatted.
118 .Ss Configuration syntax
125 accepts the following configuration syntax.
126 Lines starting with hash signs
128 are treated as comment lines.
129 .Bl -tag -width indent
133 .Ar src Ar dst Ar protocol Ar spi
140 can fail with multiple reasons,
141 including when the key length does not match the specified algorithm.
146 .Ar src Ar dst Ar protocol Ar spi
154 .Ar src Ar dst Ar protocol Ar spi
162 .Ar src Ar dst Ar protocol
165 Remove all SAD entries that match the specification.
172 Clear all SAD entries matched by the options.
174 on the command line achieves the same functionality.
181 Dumps all SAD entries matched by the options.
183 on the command line achieves the same functionality.
188 .Ar src_range Ar dst_range Ar upperspec Ar policy
196 .Ar src_range Ar dst_range Ar upperspec Fl P Ar direction
205 Clear all SPD entries.
207 on the command line achieves the same functionality.
213 Dumps all SPD entries.
215 on the command line achieves the same functionality.
219 Meta-arguments are as follows:
221 .Bl -tag -compact -width indent
224 Source/destination of the secure communication is specified as
229 can resolve a FQDN into numeric addresses.
230 If the FQDN resolves into multiple addresses,
232 will install multiple SAD/SPD entries into the kernel
233 by trying all possible combinations.
238 restricts the address resolution of FQDN in certain ways.
242 restrict results into IPv4/v6 addresses only, respectively.
244 avoids FQDN resolution and requires addresses to be numeric addresses.
250 .Bl -tag -width Fl -compact
262 TCP-MD5 based on rfc2385
267 Security Parameter Index
269 for the SAD and the SPD.
271 must be a decimal number, or a hexadecimal number with
274 SPI values between 0 and 255 are reserved for future use by IANA
275 and they cannot be used.
279 take some of the following:
280 .Bl -tag -width Fl -compact
283 Specify a security protocol mode for use.
286 .Li transport , tunnel
293 Specify the bitmap size in octets of the anti-replay window.
295 is a 32-bit unsigned integer, and its value is one eighth of the
296 anti-replay window size in packets.
299 is zero or not specified, an anti-replay check does not take place.
302 Specify the identifier of the policy entry in SPD.
306 .It Fl f Ar pad_option
307 defines the content of the ESP padding.
310 .Bl -tag -width random-pad -compact
312 All of the padding are zero.
314 A series of randomized values are set.
316 A series of sequential increasing numbers started from 1 are set.
319 .It Fl f Li nocyclic-seq
320 Do not allow cyclic sequence number.
324 Specify hard/soft life time duration of the SA.
329 .Bl -tag -width Fl -compact
330 .It Fl E Ar ealgo Ar key
331 Specify an encryption algorithm
335 .Fl E Ar ealgo Ar key
336 .Fl A Ar aalgo Ar key
338 Specify a encryption algorithm
340 as well as a payload authentication algorithm
343 .It Fl A Ar aalgo Ar key
344 Specify an authentication algorithm for AH.
345 .It Fl C Ar calgo Op Fl R
346 Specify a compression algorithm for IPComp.
351 field value will be used as the IPComp CPI
352 (compression parameter index)
357 the kernel will use well-known CPI on wire, and
359 field will be used only as an index for kernel internal usage.
363 must be double-quoted character string, or a series of hexadecimal digits
372 are specified in separate section.
377 These are selections of the secure communication specified as
378 IPv4/v6 address or IPv4/v6 address range, and it may accompany
379 TCP/UDP port specification.
380 This takes the following form:
383 .Ar address/prefixlen
385 .Ar address/prefixlen[port]
391 must be a decimal number.
392 The square brackets around
394 are necessary and are not manpage metacharacters.
395 For FQDN resolution, the rules applicable to
403 The upper layer protocol to be used.
404 You can use one of the words in
417 The protocol number may also be used to specify the
419 A type and code related to ICMPv6 may also be specified as an
421 The type is specified first, followed by a comma and then the relevant
423 The specification must be placed after
425 The kernel considers a zero to be a wildcard but
426 cannot distinguish between a wildcard and an ICMPv6
428 The following example shows a policy where IPSec is not required for
429 inbound Neighbor Solicitations:
431 .Dl "spdadd ::/0 ::/0 icmp6 135,0 -P in none;"
435 does not work in the forwarding case at this moment,
436 as it requires extra reassembly at forwarding node,
437 which is not implemented at this moment.
438 Although there are many protocols in
440 protocols other than TCP, UDP and ICMP may not be suitable to use with IPsec.
445 is expressed in one of the following three formats:
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 ...
455 The direction of a policy must be specified as
466 means that packets matching the supplied indices will be discarded
469 means that IPsec operations will not take place on the packet and
471 means that IPsec operation will take place onto the packet.
473 .Ar protocol/mode/src-dst/level
474 statement gives the rule for how to process the packet.
492 you must specify the end-point addresses of the SA as
498 between the addresses.
510 is one of the following:
511 .Li default , use , require
514 If the SA is not available in every level, the kernel will request
515 the SA from the key exchange daemon.
518 tells the kernel to use the system wide default protocol
519 e.g.,\& the one from the
521 sysctl variable, when the kernel processes the packet.
524 means that the kernel will use an SA if it is available,
525 otherwise the kernel will pass the packet as it would normally.
528 means that an SA is required whenever the kernel sends a packet matched
529 that matches the policy.
534 but, in addition, it allows the policy to bind with the unique out-bound SA.
535 For example, if you specify the policy level
538 will configure the SA for the policy.
539 If you configure the SA by manual keying for that policy,
540 you can put the decimal number as the policy identifier after
544 as in the following example:
546 In order to bind this policy to the SA,
548 must be between 1 and 32767,
551 of manual SA configuration.
553 When you want to use an SA bundle, you can define multiple rules.
555 example, if an IP header was followed by an AH header followed by an
556 ESP header followed by an upper layer protocol header, the rule would
559 .Dl esp/transport//require ah/transport//require ;
561 The rule order is very important.
567 are not in the syntax described in
568 .Xr ipsec_set_policy 3 .
569 There are small, but important, differences in the syntax.
571 .Xr ipsec_set_policy 3
576 The following list shows the supported algorithms.
581 are almost completely orthogonal.
582 The following list of authentication algorithms can be used as
589 .Bd -literal -offset indent
590 algorithm keylen (bits) comment
591 hmac-sha1 160 ah: rfc2404
592 160 ah-old: 128bit ICV (no document)
593 null 0 to 2048 for debugging
594 hmac-sha2-256 256 ah: 128bit ICV (RFC4868)
595 256 ah-old: 128bit ICV (no document)
596 hmac-sha2-384 384 ah: 192bit ICV (RFC4868)
597 384 ah-old: 128bit ICV (no document)
598 hmac-sha2-512 512 ah: 256bit ICV (RFC4868)
599 512 ah-old: 128bit ICV (no document)
600 aes-xcbc-mac 128 ah: 96bit ICV (RFC3566)
601 128 ah-old: 128bit ICV (no document)
602 tcp-md5 8 to 640 tcp: rfc2385
605 The following is the list of encryption algorithms that can be used as the
612 .Bd -literal -offset indent
613 algorithm keylen (bits) comment
614 null 0 to 2048 rfc2410
615 aes-cbc 128/192/256 rfc3602
616 aes-ctr 160/224/288 rfc3686
617 aes-gcm-16 160/224/288 rfc4106
620 Note that the first 128/192/256 bits of a key for
621 .Li aes-ctr or aes-gcm-16
622 will be used as AES key, and remaining 32 bits will be used as nonce.
624 The following are the list of compression algorithms that can be used
632 .Bd -literal -offset indent
641 Add an ESP SA between two IPv6 addresses using the
642 AES-GCM encryption algorithm.
643 .Bd -literal -offset indent
644 add 3ffe:501:4819::1 3ffe:501:481d::1 esp 123457
645 -E aes-gcm-16 0x3ffe050148193ffe050148193ffe050148193ffe ;
649 Add an authentication SA between two FQDN specified hosts:
650 .Bd -literal -offset indent
651 add -6 myhost.example.com yourhost.example.com ah 123456
652 -A hmac-sha2-256 "AH SA configuration!" ;
655 Get the SA information associated with first example above:
656 .Bd -literal -offset indent
657 get 3ffe:501:4819::1 3ffe:501:481d::1 ah 123456 ;
660 Flush all entries from the database:
661 .Bd -literal -offset indent
665 Dump the ESP entries from the database:
666 .Bd -literal -offset indent
670 Add a security policy between two networks that uses ESP in tunnel mode:
671 .Bd -literal -offset indent
672 spdadd 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 ;
676 Use TCP MD5 between two numerically specified hosts:
677 .Bd -literal -offset indent
678 add 10.1.10.34 10.1.10.36 tcp 0x1000 -A tcp-md5 "TCP-MD5 BGP secret" ;
679 add 10.1.10.36 10.1.10.34 tcp 0x1001 -A tcp-md5 "TCP-MD5 BGP secret" ;
683 .Xr ipsec_set_policy 3 ,
688 .%T "Changed manual key configuration for IPsec"
689 .%U http://www.kame.net/newsletter/19991007/
696 utility first appeared in WIDE Hydrangea IPv6 protocol stack kit.
697 The utility was completely re-designed in June 1998.
705 should report and handle syntax errors better.
707 For IPsec gateway configuration,
711 with TCP/UDP port number do not work, as the gateway does not reassemble
713 (cannot inspect upper-layer headers).