1.\" $NetBSD: ipsecif.4,v 1.6 2024/09/29 19:35:35 bad Exp $ 2.\" 3.\" Copyright (C) 2017 Internet Initiative Japan Inc. 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.Dd January 25, 2018 31.Dt IPSECIF 4 32.Os 33.Sh NAME 34.Nm ipsecif 35.Nd IPsec interface 36.Sh SYNOPSIS 37.Cd "pseudo-device ipsecif" 38.Sh DESCRIPTION 39The 40.Nm 41interface is targeted for route-based VPNs. 42It can tunnel IPv4 and IPv6 traffic over either IPv4 or IPv6 and 43secure it with ESP. 44.Pp 45.Nm 46interfaces are dynamically created and destroyed with the 47.Xr ifconfig 8 48.Cm create 49and 50.Cm destroy 51subcommands. 52The administrator must configure 53.Nm 54tunnel endpoint addresses. 55These addresses will be used for the outer IP header of ESP packets. 56The administrator also configures the protocol 57and addresses for the inner IP header with the 58.Xr ifconfig 8 59.Cm inet 60or 61.Cm inet6 62subcommands, and modify the routing table to route the packets through 63the 64.Nm 65interface. 66.Pp 67The packet processing is similar to 68.Xr gif 4 69over 70.Xr ipsec 4 71transport mode, however the security policy management is different. 72.Xr gif 4 73over 74.Xr ipsec 4 75transport mode expects userland programs to manage their 76security policies. 77In contrast, 78.Nm 79manages its security policies by itself: when the administrator 80sets up an 81.Nm 82tunnel source and destination address pair, the related security policies 83are created automatically in the kernel. 84They are automatically deleted when the tunnel is destroyed. 85.Pp 86It also means that 87.Nm 88ensures that both the in and out security policy pairs exist, that is, 89.Nm 90avoids the trouble caused when only one of the in and out security 91policy pair exists. 92.Pp 93There are four security policies generated by 94.Nm : 95one in and out pair for IPv4 and IPv6 each. 96These security policies are equivalent to the following 97.Xr ipsec.conf 5 98configuration where src and dst are IP addresses specified to the tunnel: 99.Bd -literal -offset indent 100spdadd "src" "dst" ipv4 -P out ipsec esp/transport//unique; 101spdadd "dst" "src" ipv4 -P in ipsec esp/transport//unique; 102spdadd "src" "dst" ipv6 -P out ipsec esp/transport//unique; 103spdadd "dst" "src" ipv6 -P in ipsec esp/transport//unique; 104.Ed 105.Pp 106The 107.Nm 108configuration will fail if such security policies already exist, and 109vice versa. 110.Pp 111The related security associations can be established by an IKE daemon such as 112.Xr racoon 8 . 113They can also be manipulated manually by 114.Xr setkey 8 115with the 116.Fl u 117option which sets a security policy's unique id. 118.Pp 119Some 120.Xr ifconfig 8 121parameters change the behaviour of 122.Nm . 123link0 can enable NAT-Traversal, 124link1 can enable ECN friendly mode like 125.Xr gif 4 , 126and link2 can enable forwarding inner IPv6 packets. 127Only link2 is set by default. 128If you use only IPv4 packets as inner packets, you would want to 129do 130.Bd -literal -offset indent 131ifconfig ipsec0 -link2 132.Ed 133.Pp 134to reduce security associations for IPv6 packets. 135.Sh EXAMPLES 136Configuration example: 137.Bd -literal 138Out IP addr = 172.16.100.1 Out IP addr = 172.16.200.1 139wm0 = 192.168.0.1/24 wm0 = 192.168.0.2/24 140wm1 = 10.100.0.1/24 wm1 = 10.200.0.1/24 141 142+------------+ +------------+ 143| NetBSD_A | | NetBSD_B | 144|------------| |------------| 145| [ipsec0] - - - - - - - - (tunnel) - - - - - - - - [ipsec0] | 146| [wm0]------------- ... --------------[wm0] | 147| | | | 148+---[wm1]----+ +----[wm1]---+ 149 | | 150 | | 151+------------+ +------------+ 152| Host_X | | Host_Y | 153+------------+ +------------+ 154.Ed 155.Pp 156Host_X and Host_Y will be able to communicate via an IPv4 IPsec 157tunnel. 158.Pp 159On NetBSD_A: 160.Bd -literal 161# ifconfig wm0 inet 192.168.0.1/24 162# ifconfig ipsec0 create 163# ifconfig ipsec0 tunnel 192.168.0.1 192.168.0.2 164# ifconfig ipsec0 inet 172.16.100.1/32 172.16.200.1 165start IKE daemon or set security associations manually. 166# ifconfig wm1 inet 10.100.0.1/24 167# route add 10.200.0.1 172.16.100.1 168.Ed 169.Pp 170On NetBSD_B: 171.Bd -literal 172# ifconfig wm0 inet 192.168.0.2/24 173# ifconfig ipsec0 create 174# ifconfig ipsec0 tunnel 192.168.0.2 192.168.0.1 175# ifconfig ipsec0 inet 172.16.200.1/32 172.16.100.1 176start IKE daemon or set security associations manually. 177# ifconfig wm1 inet 10.200.0.1/24 178# route add 10.100.0.1 172.16.200.1 179.Ed 180.Sh SEE ALSO 181.Xr gif 4 , 182.Xr inet 4 , 183.Xr inet6 4 , 184.Xr ipsec 4 , 185.Xr ifconfig 8 , 186.Xr racoon 8 , 187.Xr setkey 8 188.Sh HISTORY 189The 190.Nm 191device first appeared in 192.Nx 8.0 . 193.Sh LIMITATIONS 194Currently, the 195.Nm 196interface supports the ESP protocol only. 197.Nm 198supports default port number (4500) only for NAT-Traversal. 199