1.\" $NetBSD: ipsecif.4,v 1.4 2018/01/11 08:59:27 wiz 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 11, 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 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 their security policy managements are different. 72.Xr gif 4 73over 74.Xr ipsec 4 75transport mode expects for userland programs to managed its 76security policies. 77In contrast, 78.Nm 79manages its security policies by itself, that is, when the administrator 80sets up a 81.Nm 82tunnel source and destination address pair, the related security policies 83are created automatically in the kernel. 84Therefore, the security policies of 85.Nm 86are added/deleted atomically. 87.Pp 88It also means that 89.Nm 90ensures that both the in and out security policy pairs exist, that is, 91.Nm 92avoids the trouble caused when only one of the in and out security 93policy pair exists. 94.Pp 95There are four security policies generated by 96.Nm , 97that is, one in and out pair for IPv4 and IPv6 each. 98These security policies equal to the following 99.Xr ipsec.conf 5 100configuration where src and dst are IP addresses specified to the tunnel: 101.Bd -literal -offset indent 102spdadd "src" "dst" ipv4 -P out ipsec esp/transport//unique; 103spdadd "dst" "src" ipv4 -P in ipsec esp/transport//unique; 104spdadd "src" "dst" ipv6 -P out ipsec esp/transport//unique; 105spdadd "dst" "src" ipv6 -P in ipsec esp/transport//unique; 106.Ed 107.Pp 108Therefore, 109.Nm 110configuration will fail if you already added such security policies, and 111vice versa. 112.Pp 113The related security associates can be established by an IKE daemon such as 114.Xr racoon 8 . 115They can also be manipulated manually by 116.Xr setkey 8 117with the 118.Fl u 119option which sets a security policy's unique id. 120.Pp 121Some 122.Xr ifconfig 8 123parameters change 124.Nm Ap s 125behaviour. 126link0 can enable NAT-Traversal, 127link1 can enable ECN friendly mode like 128.Xr gif 4 , 129and link2 can enable forwarding inner IPv6 packets. 130Only link2 is set by default. 131If you use only IPv4 packets as inner packets, you would want to 132do 133.Bd -literal -offset indent 134ifconfig ipsec0 -link2 135.Ed 136.Pp 137to reduce security associates for IPv6 packets. 138.Sh EXAMPLES 139Configuration example: 140.Bd -literal 141Host X--NetBSD A ----------------tunnel---------- NetBSD B------Host E 142 \\ | 143 \\ / 144 +-----Router B--------Router C---------+ 145.Ed 146.Pp 147On 148.Nx 149system A 150.Bd -literal 151# ifconfig wm0 inet 192.168.0.1/24 152# ifconfig ipsec0 create 153# ifconfig ipsec0 tunnel 192.168.0.1 192.168.0.2 154# ifconfig ipsec0 inet 172.16.100.1/32 172.16.200.1 155start IKE daemon or set security associates manually. 156# ifconfig wm1 inet 10.100.0.1/24 157# route add 10.200.0.1 172.16.100.1 158.Ed 159.Pp 160On 161.Nx 162system B 163.Bd -literal 164# ifconfig wm0 inet 192.168.0.2/24 165# ifconfig ipsec0 create 166# ifconfig ipsec0 tunnel 192.168.0.2 192.168.0.1 167# ifconfig ipsec0 inet 172.16.200.1/32 172.16.100.1 168start IKE daemon or set security associates manually. 169# ifconfig wm1 inet 10.200.0.1/24 170# route add 10.100.0.1 172.16.200.1 171.Ed 172.Sh SEE ALSO 173.Xr gif 4 , 174.Xr inet 4 , 175.Xr inet6 4 , 176.Xr ipsec 4 , 177.Xr ifconfig 8 , 178.Xr racoon 8 , 179.Xr setkey 8 180.Sh HISTORY 181The 182.Nm 183device first appeared in 184.Nx 8.0 . 185.Sh LIMITATIONS 186Currently, the 187.Nm 188interface supports the ESP protocol only. 189.Nm 190supports default port number (4500) only for NAT-Traversal. 191